Need private packages and team management tools?Check out npm Orgs. »


1.1.1 • Public • Published

A Node.js module that helps users create, find, and join "events" such as a multiplayer game. You may think of this as a matchmaking lobby backend.


  • Events are created by users.
  • Users join events.
  • Events have a required capacity.
    • Events start when the event is at capacity.
  • Events have a whitelist and a blacklist of users.
    • If there's a whitelist, only users on the whitelist may join the event.
    • If there's a blacklist, any user on the blacklist may not join the event.
  • No user may join an event after the event has started.
  • A user may fetch events with which they are somehow involved (created, whitelisted, joined)
  • The creator of an event may cancel a pending event.
    • Active/started events may not be canceled.
  • The system auto-cancels or expires events that fail to start after some time.
    • The larger the capacity, the more time the event has to start before auto-cancellation.
  • A user may autojoin a compatible, pending event.
    • Same desired capacity and event parameters
  • An event's params is encoded as a string and can contain anything.
    • This might encode a desired rules-of-play for a game for instance.

Runtime Dependencies

A running Redis instance.


npm i --save matchmaker-redis


const Redis = require('ioredis')
const redis = new Redis(process.env.REDIS_URL)
const matchmaker = require('matchmaker-redis')(redis)


An event looks like this:

event = {
  id: string,
  capacity: int,
  params: string,
  userIds: [string],
  userAliases: [string],
  startedAt: int

Create an event and wait for others to join it.

  userId: string,
  userAlias: string,
  capacity: int,
  params: string,
  perUserTimeoutSec: int,
  whitelist: [string],
  blacklist: [string],
}) -> Promise(event)

Find a pending event with the given params and user count and join it.

  userId: string,
  userAlias: string,
  capacity: int,
  params: string,
}) -> Promise(event)

The creator may cancel an event before it auto-expires.

cancelEvent(userId, eventId) -> Promise(true)

Get the pending and active events the user has created, joined, or been whitelisted on.

getEventsFor(userId) -> Promise({
  active: [event],
  pending: [event]

Join a specific event. Usually in response to a user seeing that they are on a whitelist.

joinEvent(userId, userAlias, eventId) -> Promise(event)

PUBSUB Side Effects

When a user joins an event, a JSON message is published to channel events/${}.

{ "type": "join",
  "userId": string,
  "userAlias": string }

When an event is canceled, a message is published to channel events/${}.

{ "type": "cancel" }


Uses Redis for event coordination and storage but is not associated with any particular transport (HTTP, WebSockets, etc).

Running Tests

Note that the TEST_DB_NO (default: 1) database will be cleared/flushed.

$ git clone ...

$ npm i

$ redis-server &

$ REDIS_URL=redis:// \
  TEST_DB_NO=1 \
  DEBUG=tests npm test


npm i matchmaker-redis

Downloadsweekly downloads









last publish


  • avatar
Report a vulnerability