eventize-js

eventize.js

yet another fantastic pub/sub events micro framework for javascript!

Features

• clean, minimal & easy api
• all api-calls and downstream-listeners-calls are 100% synchronous, no async
• battle-proven & fully tested (jasmine specs & karma included)
• apache-2.0 license

Getting Started

Attach the eventized object api to any custom object you want.

const eventize = require('eventize-js');

var obj = eventize({});

obj.on('foo', hello => console.log('hello', hello));

obj.emit('foo', 'world');       // => "hello world"

obj.connect({
    foo (bar) {
        console.log('hejho', bar);
    }
});

obj.emit('foo', 'eventize');       // => "hello eventize", "hejho eventize"

Installation

npm install eventize-js

API

The eventize API

eventize( obj )

Attach the eventized object api to an object. Returns the obj.

The eventized object API

obj.on( eventName, [ priority, ] callbackFunc )
obj.on( eventName, [ priority, ] object )

obj.on( callbackFunc )    // => alias for: object.on( '*', callbackFunc )
obj.on( object )          // => alias for: object.on( '*', object )

Registers a listener to be executed whenever eventName gets fired.

• Define the listener by a callback function (callbackFunc) or by an object reference (object).
• The priority is optional and should be a number. The default priority is defined by eventize.PRIO_DEFAULT (which is 0 by default).
• The eventName is mandatory and should be a string.
• Returns a listener de-registration id (which is a number). Use this id to unregister your listener via off().

Use * as eventName to create a catch'm all listener. Catch'm all listeners will be called ..

• regardless off the event name
• but after all other listeners within same priority

Define listener by object

• When the event is fired, a method with the same name as the event will be called (but only if such a method exists)
• When such a method does not exists, but the listener is an eventized object, the emit() method of the listener object will be called instead

obj.on( eventName )
obj.on()

Re-activates all listeners or by event name. You can de-activate listeners with off().

obj.once( eventName, [ priority, ] callbackFunc )
obj.once( eventName, [ priority, ] object )

obj.once( callbackFunc )      // => object.once( '*', callbackFunc )
obj.once( object )            // => object.once( '*', object )

Registers a listener to be executed when eventName gets fired. Once the listener is called, de-register the listener. Apart from that once() works like on().

obj.connect( object )

Binds an object or multiple functions to multiple events.

Has almost the same effect as writing obj.on(object) but this should be the preferred way (there are some differences affecting the sender context argument passed over to eventized object listener .. see emit() for more details).

obj.connect( object, mapping )

Binds multiple functions from an object to multiple events configured by a mapping. Configure the event name to function name mapping with an optional priority for each event.

Examples

Connect multiple events to object methods:

obj.connect({
    foo () { console.log('hello') }
    bar (sender) { console.log(obj === sender) }
});

obj.emit('foo');   // => 'hello'
obj.emit('bar');   // => 'true'
obj.emit('plah');  // nothing will happen

Connect an object with a mapping:

obj.connect(options, {
    onProjectionUpdated : [100, 'projectionUpdated'],
    onFrame             : 'frame',
    onFrameEnd          : 'frameEnd'
});

obj.emit('frame', ..);   // => options.onFrame(..)

obj.emit( eventName [, args... ] )

Fire an event.

All listeners will be called in (1st) priority and (2nd) creation time order.

There are two expections of this rule:

• catch'm all listeners will be called after all other listeners within same priority
• listeners registered by connect() will be called with priority = eventize.PRIO_DEFAULT BUT before all catch'm all listeners for this priority.

emit() will not return any value (undefined).

You should NOT emit the catch'm all event!

The Listener Context

(the this reference inside your listener function)

• When the listener is registered by a callback function, this is the sender context (this is your eventized object which owns the emit() method)
• When the listener is registered by an object reference or by connect(), is always the listener object itself!

All other args will be transferred to the listener.

All object listeners (which are registered by object reference via on() or by connect()) will receive an extra argument (as last argument) which is a reference to the sender object.

Sender Object

The sender object passed into the listener as additional argument is defined by how the listener was registered ..

• connected objects (registered by connect()) will always get a reference to the emitting object (that is the object which is executing emit())
• object listeners registered by a.on() will always get a reference to the object in which they were filed (that is the object with .on())

Examples

const PRIO = 100;

let a = eventize({});

a.on('foo', (x, y, z, undef) => {    // by function
    console.log(x+3, y+3, z+3, undef === undefined);
});

a.on('*', PRIO, {                    // by object
    foo (x, y, z, senderCtx) {
      console.log(x+6, y+6, z+6, a === senderCtx);
    }
});

a.connect({                          // connect object
    foo (x, y, z, senderCtx) {
      console.log(x+9, y+9, z+9, a === senderCtx);
    }
});

let b = eventize({});                // by eventized object

b.on('foo', (x, y, z, senderCtx) => {
    console.log(x, y, z, b === senderCtx);
});

a.on('foo', PRIO, b);

a.emit('foo', 1, 2, 3);

// "1 2 3 false"
// "4 5 6 true"
// "7 8 9 true"
// "10 11 12 true"

obj.emitReduce( eventName [, value= {} ] [, args... ] )

Fire an event and return a result.

The return value from a listener is the new value used for the next listener in the call chain (unless the return value is undefined). That means the result (return value from emitReduce()) is the return value from the last called listener.

Apart from that it works like emit().

obj.off( id )
obj.off( callback )
obj.off( object )
obj.off( eventName )
obj.off()

Removes a listener from an event.

De-activate listener by id or previously bound object (registered by .on() or .connect()) or callback function reference or eventName or silence all events.

Extra API Helpers

eventize.is( obj )

Check if obj is an eventized object (has the eventized object api). Returns true or false

eventize.PRIO_MAX
eventize.PRIO_A
eventize.PRIO_B
eventize.PRIO_C
eventize.PRIO_DEFAULT = 0
eventize.PRIO_LOW
eventize.PRIO_MIN

Some predefined priorities. Use it or not. They are defined just for convenience.