An universal event (emitter) service for Browser / Node
Homepage Repository npm Download
npm install nb-event-service@1.8.2
A universal Event Service for Javascript.
$ npm install nb-event-service --save
This module works in browser as well as node.js The main different between this module and the other event emitter out there is this:
We don't care about the order of event registration and handling
Basically you can trigger an event that doesn't exist (well, sort of, its magic)
For example:
// other library like EventEmitter
ee.emitEvent('someEvent')
ee.addListener('someEvent', function() {
console.log('I am called')
})
The callback in the above example never works and you will never see the message. But our can do it:
es.$trigger('someEvent') // <-- not yet exist
ee.$on('someEvent', function() {
console.log('Hello world!')
})
The message will show.
Please note the new version is using ES6 features heavily (WeakMap, Set, Map, Array.from etc) if you need to use this module on older platform, please provide polyfill accordingly
params
that callReflect.apply(callback, context, args)
It will return the total number of events that get registered.
params
that call$once allow you to bind one or more listener to the same event. But once this event fired (triggered) it will remove itself from the event store, and no longer available. This behavior is changed in V1.3.0.
There is a potential problem with $once you can see below. It's no really a bug per se, but due to our own unique feature that can call event before even it existed (yeah, it's magic)
// trigger event before it register with a handler
ee.$trigger('someEvent')
// now it register with a regular $on
ee.$on('someEvent', function() {
console.log('call me second')
})
// but some where else you try to register it with $once
ee.$once('someEvent', function() {
console.log('call me first')
})
In v1.3.0 we change the behavior of $once, now you can register more than one handler.
But if you look at the above example, you register it with $on
then $once
.
What happen is, the $once
call execute the $trigger
from the earlier call, then it will
remove this event from the event handler store. Therefore, you $on
will never fire again.
So you have to make sure which event you REALLY want to register with what.
This is a new method in v1.3.0
params
that callExample:
es.$only('only-event', function(message) {
console.log('ONLY', message)
})
// now if you try to add another
es.$only('only-event', function(message) {
console.log('AGAIN', message)
})
// execute it
es.$trigger('only-event', 'A little cat jumping through the window')
You will only get ONLY A little cat jumping through the window
but the second callback never add to the event store.
Although we develop this feature purposely for our other library to use, but it has a lot real world usage.
Just like what it said on the tin; its $only
+ $once
. You should able to figure out what it does.
It will return
This is $off
+ event register function
Type can be on
, only
, once
, onlyOnce
default value is on
eventName
whether that actually exist or notReflect.apply
or default to nullon
, only
, once
, onlyOnce
this is for trigger event before it get register and prevent other type to register itThis method will return
This is breaking change in V1.6.0
eventName
whether that actually exist or noton
, only
, once
, onlyOnce
this is for trigger event before it get register and prevent other type to register itReflect.apply
or default to nullThis basically it's a shorthand of $trigger
if you know that your callback only execute in null
and purposely register a type to prevent
other to register it later
This is useful shorthand, also trigger event before its register
Example:
// call before event register
es.$call('some-event', 1001, 'only')
// now try to register it with a different event handler
es.$on('some-event', function(num) {
return ++num;
})
// it will throw Error that tells you it has been register with `only` type already
Or it will return false
if there is nothing
This is new in V1.8.0. We watch this property internally, when you set this to true, we suspend all the $trigger
and $call
action.
Then when you set this to false, all the previous suspended call will get release.
const evtSrv = new NBEventService()
evtSrv.$on('some-event', value => {
return value + 1;
})
evtSrv.$suspend = true;
evtSrv.$trigger('some-event', 100)
evtSrv.$done === null
evtSrv.$suspend = false;
evtSrv.$done === 101
If you don't like the $
, you can use the alias version.
For browser you can include the nb-event-service/dist/alias.js
for node you can require('nb-event-service/alias')
And that will gives you the following alias version:
This is a feature that you don't see in other Event Emitter library.
Whenever you execute the callback, the result will store in the internal $done
setter.
So you can call the $done
getter to get back the last result.
Example:
es.$on('add', function add(val) {
return val + 1;
})
es.$trigger('add', 1000)
console.log(es.$done)
You will get a 1001. This might be useful in some situation. Please note, it will get call whenever a event got trigger, if at the same time some other event trigger then your value might be different from what you expected. So use this with caution.
Coming soon with more update to date example.
$ npm test
We use ava for testing
$ npm run build
It will kick start the rollup building process
ISC
Joel Chu NEWBRAN LTD (c) 2019