Prefix Emitter
Simple Event Emitter for ES6 and TypeScript based on Prefix Tree
Prefix Emitter is a small library (1.3KB min+gz) with functionality like Node's Event Emitter. But event listeners can be subscribed to any predefined sequence of anguments (topic) instead of single event name.
Key Features
- Hierarchical event system (topics)
- Subscribing to and unsubscribing from events by using Decorators
- Typed events for usage with TypeScript
- Small size
- Zero dependencies
Example
; let emitter = ; // subscribe to eventslet subscription1 = emitter;let subscription2 = emitter;let subscription3 = emitter; // emit an eventemitter;// ➜ global interceptor: ["/topic", "/event", 123]// ➜ topic interceptor: "/event", 123// ➜ event listener: 123 // unsubscribe from eventssubscription1;subscription2;subscription3;
Installation and Requirements
Package supports installation as ES6 module or simply with <script>
tag (through global variable named PrefixEmitter
).
Prefix Emitter can be used with NodeJS 4 and above or any ES5 compatible browser including IE9+ and Safari 7. But internally it uses ES6 Map with simple fallback based on object for ES5. So if ES6 Map is not supported (and polyfill is not used) then event prefixes should be strings or numbers. Otherwise event prefix could be an object (if you need such strange case).
Documentation
Basic usage
We can choose any sequence of arguments (even empty) and subscribe event handler to it:
PrefixEmitter.on()
const emitter = ;const subscription = emitter;
Then we could trigger any events:
PrefixEmitter.emit()
emitter; // ➜ "foo"emitter; // ➜ "bar"emitter; // ➜
And then we should unsubscribe from events:
Subscription.dispose()
subscription;
Or we could use self-disposing subscription that will be destroyed after one call:
PrefixEmitter.once()
const subscription = emitter; emitter; // ➜ [subscription is dispoised], "foo"emitter; // ➜
Decorators
Methods of some class can be marked as event listeners by using @on
and @once
Method Decprators.
Then subscriptions will be created by injectSubscriptions
utility function and disposed by disposeSubscriptions
function.
See example:
; const emitter = ; { ; } { ; } @ { } @ { }
Also existing subscriptions can be passed to injectSubscriptions
function as second parameter:
const emitter = ; { ; } { ; } { } { }
Typed Emitters
For TypeScript there are three predefined generic Event Emitter interfaces:
VoidEmitter
Emitter without any arguments. Can simply trigger subscriptions.
; const emitter: VoidEmitter = ; const sub = emitter;
SingleEmitter
Emitter with one argument (or event).
; const emitter: SingleEmitter<string> = ; const sub1 = emitter;const sub2 = emitter;
DoubleEmitter
Emitter with two arguments (or prefixes).
; const emitter: DoubleEmitter<string number> = ; const sub2 = emitter;const sub2 = emitter;const sub3 = emitter;
Tips
PrefixEmitter calls all listeners synchronously.
If you want define asynchronous listener, you could wrap its body to setImmediate()
or some asap()
function.
emitter;
If you want emit some event asynchronously, you can do such thing:
let a = 1 b = 2 c = 3;// store argument valuesconst args = a b c;;// arguments can be changed like after synchronous `emit`a = 4; b = 5;
Usage in global scope
For usage in browser (without module loaders) the package registers global variable named PerfixEmitter
.
And the class PerfixEmitter
has an alias named Emitter
.
const Emitter on once injectSubscriptions disposeSubscriptions = PrefixEmitter; const myEmitter = ;
Benchmarks
To run benchmarks please type npm run benchmarks
in console or open ./benchmark.html
in browser.