emoney

E$

A lightweight, isomorphic event emitter.

Overview

E$ can be used standalone or inherited by other classes.

// Standalone
const emoney = E$({
    handleE$() { ... }
});
 
// Inherited
class E$Extended extends E$ {
    handleE$() { ... }
}

E$ provides a clean way to interface with object instances.

emoney
    .$when('loading', (e, pct) => console.log('loading... (%s%)', pct))
    .$when('ready', () => console.log('ready!'))
    .$when('error', (e, err) => console.error(err.stack));

E$ instances can communicate via the handleE$ method.

const emitter = E$();
const watcher = E$({
    handleE$(e, str, obj) {
        expect(str).to.eql('awesome');
        expect(obj).to.eql({ rad: true });
    }
});
watcher.$watch(emitter);
emitter.$emit('gnarly', ['awesome', { rad: true }]);
expect(watcher.handleE$).to.have.been.called.once;

E$ can be used to create a DOM-like event tree.

const emitter = E$();
const watcher1 = E$();
const watcher2 = E$();
const spy = sinon.spy();
 
watcher2
    .$watch(watcher1)
    .$when('gnarly', spy);
 
watcher1
    .$watch(emitter)
    .$when('gnarly', e => e.stopPropagation());
 
emitter.$emit('gnarly', () => expect(spy).to.have.not.been.called);

Methods

(static) E$.is(subject) → {boolean}

Returns true if subject is E$-ish, false otherwise.

const emoney = E$();
const emoneyIsh = new E$Extended();
const somethingElse = new SomethingElse();
 
emoney instanceof E$;     // true
E$.is(emoney);            // true
 
emoneyIsh instanceof E$;  // false
E$.is(emoneyIsh);         // true
 
E$.is(somethingElse);     // false

.$when(events, args_opt, fn_opt) → {instance}

Adds an event listener.

Parameter	Type	Description	Required
events	string array	The event(s) to be handled.	yes
args	variant array	The argument(s) to be bound to the event handler.	no
fn	function E$	The event handler. If E$.is(fn) == true, the event will be bound to instance.handleE$. If fn is falsy, the event will be bound to emoney.handleE$.	no

// basic use
emoney.$when('gnarly', () => { ... });
 
// bind an argument to multiple events
emoney.$when(['gnarly', 'rad'], 'arg', () => { ... });

.$once(events, args_opt, fn_opt) → {instance}

Adds an event listener that is removed after the first time it is invoked.

Parameter	Type	Description	Required
events	string array	The event(s) to be handled.	yes
args	variant array	The argument(s) to be bound to the event fn.	no
fn	function E$	The event handler.	no

// basic use
emoney.$once('gnarly', () => { ... });
 
// bind an argument to multiple events
emoney.$once(['gnarly', 'rad'], 'arg', () => { ... });

.$emit(events, args_opt, callback_opt) → {instance}

Emits an event.

Parameter	Type	Description	Required
events	string array	The event(s) to be emitted.	yes
args	variant array	The argument(s) to be passed to the event handler.	no
callback	function	A function to be executed at the end of the event chain (see event behavior).	no

// basic use
emoney.$emit('gnarly', () => { ... });
 
// pass an argument to multiple event handlers
emoney.$emit(['gnarly', 'rad'], 'arg', () => { ... });
 
// pass multiple arguments to an event handler
emoney.$emit('gnarly', ['arg1', 'arg2'], () => { ... });

.$dispel(events, wild_opt, fn_opt) → {instance}

Removes an event listener.

Parameter	Type	Description	Required
events	string array null	The event(s) to be removed.	yes
wild	boolean	A boolean value denoting whether handlers bound to the wildcard event should be removed.	no
fn	function E$	The event handler.	no

// remove any gnarly listeners bound to fn
emoney.$dispel('gnarly', fn);
 
// remove all gnarly or rad listeners bound to any handler
emoney.$dispel(['gnarly', 'rad']);
 
// remove all listeners bound to fn except wildcard listeners
emoney.$dispel(null, fn);
 
// remove all listeners bound to fn
emoney.$dispel(null, true, fn);
 
// remove all listeners
emoney.$dispel(null, true);

.$watch(emitters) → {instance}

Starts watching E$ instance(s).

Parameter	Type	Description	Required
emitters	E$ array	The E$ instance(s) to watch.	yes

// watch a single emitter
listener.$watch(emitter1);
 
// watch multiple emitters
listener.$watch([emitter1, emitter2]);

.$unwatch(emitters) → {instance}

Stops watching E$ instance(s).

Parameter	Type	Description	Required
emitters	E$ array	The E$ instance(s) to stop watching.	yes

// stop watching a single emitter
listener.$unwatch(emitter1);
 
// stop watching multiple emitters
listener.$unwatch([emitter1, emitter2]);

Events

Properties

Property	Type	Default	Description
target	E$	n/a	The event target.
type	string	n/a	The event type.
defaultPrevented	boolean	false	A flag denoting whether default was prevented.
cancelBubble	boolean	false	A flag denoting whether propagation was stopped.
timeStamp	number	n/a	The time at which the event was first triggered.

Methods

.preventDefault()

Prevents the $emit callback from being executed.

emoney
    .$when('gnarly', (e) => {
        e.preventDefault();
        console.log('fn1');
    })
    .$when('gnarly', () => console.log('fn2'))
    .$emit('gnarly', () => console.log('cb'));
 
/**
 * > 'fn1'
 * > 'fn2'
 */

.stopPropagation()

Stops execution of the event chain and executes the emit callback.

emoney
    .$when('gnarly', (e) => {
        e.stopPropagation();
        console.log('fn1');
    })
    .$when('gnarly', () => console.log('fn2'))
    .$emit('gnarly', () => console.log('cb'));
 
/**
 * > 'fn1'
 * > 'cb'
 */

Behavior

Build & Test

npm i && npm run build