until

An event collector of nodejs' EventEmitter

npm install until
2 downloads in the last week
11 downloads in the last month

until

unitl is a very simple helper object that helps on waiting multiple EventEmitter. It is an EventEmitter itselt, and it waits for all the EventEmitter firing success events, or one of them firing failure event.

The APIs are

var waitings = new require('until').Waitings();
waitings.add(EventEmitter      e,
             Array or String   success events,
             Array or String   fail events,
             Array or String   notification events)

An example:

var waitings = new until.Waitings();
waitings.add(emitter,         // The emitter object
             ['ok', 'done'],  // A list of event names that stand for success.
             ['bad', 'fail'], // A list of event names that stand for failure.
             ['progress']);   // A list of event names will continuously send.

Class 'Waitings'

var waiting = new until.Waitings();

This class is the main class of the APIs. Waitings object is an EventEmitter which provides 'ok', 'error' events. Waitings object listens to many EventEmitters and fire 'ok' when it realizes all the EventEmitters it listens to have fired success events, or 'error' when one of the EventEmitters fired an error event.

We don't know what name the success/error event are, so we expect users to define the success/error event name when they add the EventEmitter into the listening-to list of Waitings.

Waitings.add(emitter, success, error)

  • emitter: EventEmitter
  • success: String or Array of String
  • error: String or Array of String

Adding a EventEmitter to the Waitings object. emitter is an EventEmitter that is to be listened to. success is a list of events that stand for 'success', when Waitings object heard the event in the success list, it knows this emitter "finished successfully". So does error.

Event: 'ok'

This will be fired only once, when all of the EventEmitter that the Waitings is waiting for finished successfully. The handler of this event is expected to look like

function handler(list)

The list argument is an array that stores the arguemnts of each event handler, with following structure:

{
  "emitter" : // The reference of the emitter that fires this success event
  "event"   : // String: the event name the emitter fired
  "arg"     : // Array: the arguments passed to the event handler
}

No matter how many times an EventEmitter fires the success events, only the first event will be stored.

Event: 'error'

If one of the EventEmitter fires the error event, this event will be fired, and there will no futher event from this Waitings.

The handler is expected to take a argument, which is error, the argument that is got from the EventEmitter which fires the error event.

Test

A very earily test runner is located at ./test.js, use

node test.js

to run the test cases.

License

We release this package with Apache License 2.0. Please see the LICENSE file in the source.

npm loves you