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, argsopt, fnopt) → {instance}

Adds an event listener.

| Parameter | Type | Description | Required | | --------- | ---- | ----------- | -------- | | events | stringarray | The event(s) to be handled. | yes | | args | variantarray | The argument(s) to be bound to the event handler. | no | | fn | functionE$ | 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, argsopt, fnopt) → {instance}

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

| Parameter | Type | Description | Required | | --------- | ---- | ----------- | -------- | | events | stringarray | The event(s) to be handled. | yes | | args | variantarray | The argument(s) to be bound to the event fn. | no | | fn | functionE$ | The event handler. | no |

// basic use
emoney.$once('gnarly', () => { ... });

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

.$emit(events, argsopt, callbackopt) → {instance}

Emits an event.

| Parameter | Type | Description | Required | | --------- | ---- | ----------- | -------- | | events | stringarray | The event(s) to be emitted. | yes | | args | variantarray | 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, wildopt, fnopt) → {instance}

Removes an event listener.

| Parameter | Type | Description | Required | | --------- | ---- | ----------- | -------- | | events | stringarraynull | 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 | functionE$ | 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