guaranteeEvents/README.md

guaranteeEvents

This module exports a single function that when passed an event(s) and an EventEmitter compatible object will register a couple of handlers that will provide the following functionality:

• Cache event data for each event of the given type that gets emitted.

• Call new handlers of the specified event with each of the prior event data sets in order of event occurrence.

• Add a .clearGuaranteedQueue(<evetn>) method to the emitter to facilitate event cache cleaning.

This is useful for modules like glob that use the EventEmitter model to pass data to the user (see examples below).

This is similar to how state change handlers work in jQuery.Deferred or in Promise objects.

Install

$ npm install guarantee-events

Basic Examples

A synthetic example illustrating the basic functionality:

var emitter = new (require('events').EventEmitter)
var guaranteeEvents = require('guarantee-events')

guaranteeEvents('event', emitter)

// emit some events...
emitter.emit('event', 'some data')

emitter.emit('event', 'some', 'more', 'data')


// Here the handler will be called for each event it missed...
emitter.on('event', function(){ console.log([].slice.apply(argumnts).join(' ')) })


emitter.emit('event', 'some data')

A real-life use-case:

var glob = require('glob')
var guaranteeEvents = require('guarantee-events')


// build a glob object with cached 'match' and 'end' events...
var results = guaranteeEvents('match end', glob('**/*js'))


// Do stuff for some time...


// This will not miss a single result, regardless of how long it 
// took to do stuff...
results.on('match', function(path){ console.log('found: '+path) })

Cache cleaning and use for long running emitters

This is not recommended for use in long running event emitters as each event emitted data will get stored and might get quite large, i.e. a potential source for a leak.

To deal with this issue a .clearGuaranteedQueue(<event>) method is added to the emitter, this will clear the cache for a specific event and a shorthand form .clearGuaranteedQueue('*') that will clear the cache for all wrapped events.

So for the above example:

// This this will drop all the prior match data, so newly registred handlers
// will not see them...
// NOTE: this will not affect the underlaying glob object in any way. 
results.clearGuaranteedQueue('match')