Manage consumers standing in queue for resources.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Manage consumers standing in a queue for limited resources.


var waitlist = require('waitlist');
var EventEmitter = require('events').EventEmitter;

var ws = waitlist();

ws.add('beep', { id : 0 });
ws.add('boop', { id : 1 });

(function consume (userId) {
    setTimeout(function () {
        var em = new EventEmitter;
        em.on('spot', function (n) {
            console.log('user ' + userId + ' in spot ' + n);
        em.on('available', function (res) {
            console.log('user ' + userId
                + ' using resource ' + JSON.stringify(res)
        em.on('expire', function () {
            console.log('user ' + userId + ' expired');
        ws.acquire(Math.random() * 1000, em.emit.bind(em));
        consume(userId + 1);
    }, Math.random() * 500);


$ node examples/shared.js 
user 0 using resource {"id":0}
user 1 using resource {"id":1}
user 2 in spot 1
user 2 in spot 1
user 3 in spot 2
user 0 expired
user 2 using resource {"id":0}
user 3 in spot 1
user 3 in spot 1
user 4 in spot 2
user 3 in spot 1
user 4 in spot 2
user 5 in spot 3
user 1 expired
user 3 using resource {"id":1}
user 4 in spot 1
user 5 in spot 2


var waitlist = require('waitlist')

var ws = waitlist()

Create a new waitlist.

ws.add(name, res)

Add a new resource name with the resource object res. res will be made available to consumers.


Remove a resource by its name.

ws.acquire(time, emit)

Try to acquire an available resource for time milliseconds.

If time is 0, the session won't expire automatically.

Resource events will be passed through the emit function supplied.

The available resource that was last used the longest time ago will be favored in computing which resource to deliver.


Release a granted token.

ws.on('stats', cb)

Emitted whenever the queue stats of available resources and connected clients changes. cb(stats) is called with the ws.stats object which looks like:

{ resources : 2, waiting : 0, using : 1 },

resource events

The emit function passed to ws.acquire() receives these events:

'token', token

Emits the token for the current session right after acquire() is called.

'spot', ix

If the resource isn't available right away, emit the position in the queue.

'available', res, name, time

Emitted when a resource res with the name name is ready for time milliseconds of use.


Emitted when a session's alloted time is up.


Emitted when a session is finished either through ws.release() or expiry.


With npm do:

npm install waitlist

build status