Handle events without emitters or frills.
This implements the core eventuate objects, with a limited feature set. You may also want to look at eventuate which aggregates this, and several other modules to provide a reactive api for handling data over time.
var eventuate = require('eventuate-core')
// lets create a server object
var server = {}
// this server will produce request events
server.request = eventuate()
// lets consume them!
server.request(function onRequest (req) {
console.log('we got a request for ' + req.url)
})
// lets produce some of these requests
server.request.produce({ url: '/hello.js' })
server.request.produce({ url: '/world.js' })
server.request.produce({ url: '/bye.js' })
var eventuate = require('eventuate-core')
Create an object, event
, that represents a consumable event type.
Valid options are:
requireConsumption
(default:false
) - throw an error if a produced event is not consumed, useful for error producersdestroyResidual
(default:false
) - call the destroy function when the last consumer is removed viaremoveConsumer
orremoveAllConsumers
(after at least one consumer was added)
Convenient shortcut for calling event.consume(consumer)
.
Consume events with the consumer
function, which should have the signature
function (data [, done]) {}
. When an event is produced, it will be passed to the
consumer function as the first argument.
If the consumer
accepts a 2nd argument, it will be passed a done
callback
that should be called when the consumer is done processing the data event. This
is mandatory if you intend to support backpressure (aka eventuate saturation).
To fully support saturation, in addition to calling the done
callback, the
consumer
function should have an isSaturated
method, which when called will
return a boolean value, indicating whether or not the consumer is saturated.
When the eventuate produces a value that is consumed by the consumer
,
isSaturated
will be checked. If true
is returned, this will cause the
eventuate to produce on the saturated
basic eventuate property.
When the done
callback is called, the eventuate will check isSaturated
again. If no consumers are considered saturated
, then the eventuate will
produce on the unsaturated
basic eventuate.
These events may be used to implement back-pressure on sources that support it.
Returns event
.
Produce an event. All event
consumer functions will be called with data
. If
the requireConsumption
option was provided, and nothing consumes the data, an
error will be thrown. In this case, if the data being produced is an instanceof
Error
, it will be thrown directly, otherwise an UnconsumedEventError
(see
below) will be thrown, and the data that was produced will be attached to the
error as a data
property.
Remove the formerly added consumer
, so that it will not be called with future
produced events.
If the consumer
function has a property of removed
, and that property is a
function, it will be executed (with no arguments) after it is removed.
Remove all consumers from the eventuate event
.
Returns true
is the eventuate has any consumers, otherwise false
.
Returns a shallow copy of the array of all consuming functions.
Remove all consumers, prevent further consumers from being added, and throw an
EventuateDestroyedError if further produce
calls are attempted. This function
is called automatically when the last consumer is removed if the
destroyResidual
option was set to true.
Returns true
if the eventuate has been destroyed, otherwise false
.
Returns true
if any consumers are saturated, otherwise false
.
A basic eventuate representing
Error
objects produced by the eventuate. By assigning a handler to the
event.error
, any Error
objects produced will no longer be supplied to
event
consumers; only event.error
consumers will receive them.
A basic eventuate representing additions of consumers.
Any consumers of consumerAdded
will be invoked and passed the consumer
function
that was added to the eventuate.
Example:
var event = eventuate()
event.consumerAdded(function (eventConsumer) {
console.log('a consumer was added to event: ' + eventConsumer.name)
})
A basic eventuate representing removal of consumers. Any consumers of
consumerRemoved
will be invoked with the consumer
function removed from the
eventuate
.
Example:
var event = eventuate()
event.consumerRemoved(function (eventConsumer) {
console.log('a consumer was removed from event: ' + eventConsumer.name)
})
A basic eventuate that produces (no payload) when any consumer enters a saturated state.
A basic eventuate that produces (no payload), when the eventuate is no longer considered saturated (i.e. no consumers are saturated).
A basic eventuate representing destruction of the event. This eventuate occurs
only one time, after destroy
is called. This eventuate will not occur if
destroyResidual
was set to false
at eventuate creation.
Exposes the factory function used to create the eventuate. Example:
var eventuate = require('eventuate'),
assert = require('assert')
var event = eventuate()
assert(event.factory === eventuate)
var errors = require('eventuate/errors')
Constructor of error potentially thrown from eventuate.produce
when
requireConsumption
is true.
Constructor of error thrown from eventuate.produce
when the eventuate is
already destroyed.
The following modules support and extend the functionality of eventuate and are included in the eventuate module (without the -core).
- eventuate-next - act once (via callback or promise) upon the next occurrence of an eventuate
- eventuate-filter - create filtered eventuate, acting as subset of broader eventuate
- eventuate-map - create mapped eventuates, producing events transformed from the source eventuate
- eventuate-reduce - create an eventuate that reduces events produced from a source eventuate
The eventuate core mixin may be used to add eventuate core functionality to another object. You should first assign the mixin's properties, then call the mixin in the context of your object to initialize it.
For example:
var eventuateCoreMixin = require('eventuate-core/mixin')
var myObject = {}
Object.assign(myObject, eventuateCoreMixin.properties)
eventuateCoreMixin.call(myObject /*, options */)
Alternatively, the constructor may be required and used for extending or
creating new eventuate objects. Be warned, that new EventuateCore
will return
a non-function object, meaning the event(consumer)
shortcut will not work.
The long-form event.consume(consumer)
will need to be required.
const EventuateCore = require('eventuate-core/constructor')
var event = new EventuateCore
With npm do:
npm install --save eventuate-core
npm test
Or to run tests in phantom: npm run phantom
npm run view-cover
This will output a textual coverage report.
npm run open-cover
This will open an HTML coverage report in the default browser.