kilo-emitter
v0.1.8
Published
A sub 1Kb event emitter class with broader functionality.
Downloads
15
Maintainers
Readme
What & Why
A sub 1Kb event emitter class with broader functionality.
Why another one ?
I needed some specific but not unheard of features of event emitter and all the lightweight implementations I founds were all missing one or the other, so I ended up making my own with set of features that I needed. It's not better or worse than other ones, it just combines a specific set.
So here's what I needed from event emitter and ended up implementing in this one:
- Small footprint, 1Kb or less.
- Chainalbe methods.
- Instantiate with
new
as well as extend existing object. - Reliable listener removal (usually
once
were implemented as wrappers so you couldn't remove them by same listener reference). - Ability to remove all listeners for given event. See
.off(event)
- Ability to remove all listeners for all events. See
.off(event)
- Priority listeners (added to the start of the queue instead of end). See
.on()
- Ability to pass context to the listener as this keyword. See
.on()
- Ability to stop propagation of current event, smth like
preventDefaults
. See.emit()
- Ability to pass arguments together with event. See
.emit()
- Ability to check whether specific listener is subscribed for a specific event. See
.triggers()
- Ability to check whether emitter has any listeners subscribed for specified event or any listeners at all. See
.triggers()
- Available under diferent formats (ES3, ES5, ES6, Browser, inlined)
Stats
Coverage
Type | Coverage --- | --- Statements | 100% (130/130) Branches | 100% (84/84) Functions | 100% (18/18) Lines | 100% (126/126)
dist
directory size listing
Name | Bytes | Gzip | % --- | --- | --- | --- Emitter.es3.browser.js | 3289 | 813 | 24% Emitter.es3.browser.min.js | 1022 | 501 | 49% Emitter.es3.inlined.js | 3286 | 810 | 24% Emitter.es3.inlined.min.js | 1019 | 499 | 48% Emitter.es3.umd.js | 4120 | 976 | 23% Emitter.es3.umd.min.js | 1276 | 607 | 47% Emitter.es6.inlined.js | 3069 | 789 | 25% Emitter.es6.inlined.min.js | 883 | 481 | 54% Emitter.es6.js | 3076 | 794 | 25% Emitter.es6.min.js | 899 | 493 | 54% Emitter.js | 3161 | 843 | 26% Emitter.min.js | 975 | 535 | 54%
Usage
Package manager
npm i kilo-emitter
yarn add kilo-emitter
Browser tag
<script src="https://unpkg.com/kilo-emitter/dist/Emitter.es3.browser.min.js"></script>
Inlined
Or you can just grab this compiled inlined version and copy-paste it in your code.
ES3, 1019 Bytes
var Emitter=function(){function t(){this.$evt={}}return t.extend=function(e){var n;return e&&"object"==typeof e&&(n=new t,["$evt","on","off","once","emit","triggers"].forEach(function(t){e[t]=n[t]})),e},t.prototype.on=function(t,e,n,o){var i,r=this.$evt;return t&&e&&("boolean"==typeof n?(o=n,n=null):e.$ctx=n,(i=r[t])?(this.off(t,e),o?i.unshift(e):i.push(e)):i=[e],r[t]=i),this},t.prototype.once=function(t,e,n,o){return t&&e&&(e.$once=!0,this.on(t,e,n,o)),this},t.prototype.off=function(t,e){var n,o,i=arguments.length,r=this.$evt;return 0===i?this.$evt={}:1===i?delete r[t]:-1<(n=(o=r[t])?o.indexOf(e):-1)&&(o.splice(n,1),o.length||delete r[t]),this},t.prototype.emit=function(t,e){var n,o,i,r=this.$evt[t];if(r&&(i=r.length))for(r=r.slice(),n=0;n<i;n++)"stopEmit"===(o=r[n]).apply(o.$ctx,e)&&(n=i),o.$once&&(this.off(t,o),delete o.$once);return this},t.prototype.triggers=function(t,e){var n,o=arguments.length,i=this.$evt;return o?!!(n=i[t])&&(!(1<o)||-1<n.indexOf(e)):!!Object.getOwnPropertyNames(i).length},t}();
ES6, 883 Bytes
class Emitter{static extend(t){let e;return t&&"object"==typeof t&&(e=new Emitter,["$evt","on","off","once","emit","triggers"].forEach(n=>{t[n]=e[n]})),t}constructor(){this.$evt={}}on(t,e,n,i){let s,r=this.$evt;return t&&e&&("boolean"==typeof n?(i=n,n=null):e.$ctx=n,(s=r[t])?(this.off(t,e),i?s.unshift(e):s.push(e)):s=[e],r[t]=s),this}once(t,e,n,i){return t&&e&&(e.$once=!0,this.on(t,e,n,i)),this}off(t,e){let n,i,s=arguments.length,r=this.$evt;return 0===s?this.$evt={}:1===s?delete r[t]:(n=(i=r[t])?i.indexOf(e):-1)>-1&&(i.splice(n,1),i.length||delete r[t]),this}emit(t,e){let n,i,s,r=this.$evt[t];if(r&&(s=r.length))for(r=r.slice(),n=0;n<s;n++)"stopEmit"===(i=r[n]).apply(i.$ctx,e)&&(n=s),i.$once&&(this.off(t,i),delete i.$once);return this}triggers(t,e){let n,i=arguments.length,s=this.$evt;return i?!!(n=s[t])&&(!(i>1)||n.indexOf(e)>-1):!!Object.getOwnPropertyNames(s).length}}
Node
const Emitter = require('kilo-emitter')
let cb = (World) => { console.log(`Hello ${World}!`) }
let myEmitter = new Emitter()
myEmitter.on('evt', cb)
myEmitter.emit('evt', ['World']) // `Hello World!`
console.log(myEmitter.triggers('evt', cb)) // true
myEmitter.off('evt')
console.log(myEmitter.triggers('evt', cb)) // false
ES6/TypeScript
import Emitter from 'kilo-emitter'
let myEmitter = new Emitter()
myEmitter.once('evt', console.log)
myEmitter.once('evt2', console.log)
myEmitter.emit('evt', ['hey there']) // 'hey there'
console.log(myEmitter.triggers('evt', console.log)) // false
console.log(myEmitter.triggers()) // true
myEmitter.off()
console.log(myEmitter.triggers()) // false
Browser
<script src="https://unpkg.com/kilo-emitter/dist/Emitter.es3.browser.min.js"></script>
<script>
var myEmitter = new Emitter()
myEmitter.once('evt', (param) => {
console.log(`Hey ${param}!`)
}, ['there'])
myEmitter.emit('evt')
</script>
API
static
extend(target)
Extends target object that is passed to it with Emitter class methods. It creates new Emitter class and assigns all of it's fields and methods (including $evt) to target object. Note that those methods will override existing fields with same names and also should now be invoked on target since they rely on this
keyword.
function extend<T extends object>(target: T): T & Emitter
- target object An object that will be extended.
let someObject = {someField: 'someValue'}
Emitter.extend(someObject)
someObject.on('evt', function (someParam) {
console.log(someParam) // 'otherValue'
console.log(this.someField) // 'someValue'
})
someObject.emit('evt', ['otherValue'])
on(event, listener, context, priority)
Subscribes a listener to an event. Listener will persist until removed with .off(). Subscribing an existing listener again will move it to the end (or start, if priority specified) of the queue. Unique listener is considered a combo of an event name and a reference to a function. If a same callback added with a different context it will be considered as a same listener. Context parameter is skipable, if you pass boolean as 3rd argument it will be used as priority.
function on(event: string, listener: Listener, context?: object|boolean, priority?:Boolean) : this
- event string Event name you want to subscribe to.
- listener Listener Listener callback to be invoked.
- context object|boolean
optional
Context to invoke callback with (pass as this) OR a boolean value for priority if you want to skip context - priority Boolean
optional
If true will add listener to the start of the queue.
let em = new Emitter()
em.on('evt', (val) => {}) // regular listener
em.on('evt', (val) => {}, {someField: 'someValue'}) // listener with context
em.on('evt', (val) => {}, null, true) // listener with priority (added to the start of queue)
em.on('evt', (val) => {}, true) // same
em.emit('evt', ['otherValue'])
once(event, listener, context, priority)
Same as .on()
but listener will be automatically removed after first invocation.
function once(event: string, listener: Listener, context?: object, priority?:Boolean) : this
- event string Event name you want to subscribe to.
- listener Listener Listener callback to be invoked.
- context object|boolean
optional
Context to invoke callback with (pass as this) OR a boolean value for priority if you want to skip context - priority Boolean
optional
If true will add listener to the start of the queue.
let em = new Emitter()
let cb = () => {}
em.once('evt', cb)
console.log( em.triggers('evt', cb) ) // true
em.emit('evt')
console.log( em.triggers('evt', cb) ) // false
off(event, listener)
If both arguments are passed it removes the listener if such exists. If only event name is passed it will remove all the listeners for that event. If no arguments passed it will purge all the listeners for current emitter. Distinction is made by the length of the arguments
variable to avoid undesired behaviour when null
or undefined
are passed due to an error. This means that off('init')
will try to remove all listeners for 'init' event and off(null)
will try to remove all events for 'null' event.
function off(event?: string, listener?: Function) : this
- event string
optional
Event name you want to unsubscribe from. - listener Listener
optional
Listener callback you want to remove.
let em = new Emitter()
let cb = () => {}
em.on('evt', cb) // removed on 1sk off
em.on('evt', () => {}) // removed on 2sk off
em.on('evt2', () => {}) // removed on 3sk off
// removes specific listener
em.off('evt', cb)
// removes all listeners for event
em.off('evt')
// removes all listeners completely
em.off()
emit(event, args)
If both arguments are passed it removes the listener if such exists. If only event name is passed it will remove all the listeners for that event. If no arguments passed it will purge all the listeners for current emitter. Distinction is made by the length of the arguments
variable to avoid undesired behaviour when null
or undefined
are passed due to an error. This means that off('init')
will try to remove all listeners for 'init' event and off(null)
will try to remove all events for 'null' event.
function emit(event: string, args?:any[]) : this
- event string Event name whose listeners should be invoked.
- args any[]
optional
Array of arguments that should be passed to each listener callback.
let em = new Emitter()
// this listeners stops propagation and removes itself
em.once('evt', (arg1, arg2) => {
console.log(arg1) // 'a'
console.log(arg2) // 'b'
return 'stopEmit'
})
// this listener is triggered on second emit
em.on('evt', () => {
// never triggered
})
em.emit('evt', ['a', 'b'])
em.emit('evt')
triggers(event, listener)
If both arguments are passed then it will check whether specific listener is subscribed for specific event. If only event name is passed it will check if there are any listeners subscribed for that event. If no arguments passed it will check if emitter has any listeners at all. Distinction is made by the length of the arguments
variable to avoid undesired behaviour when null
or undefined
are passed due to an error. This means that triggers('init')
will check if there are any listeners fot the event 'init' and triggers(null)
will check if there are any listeners fot the event 'null'.
function triggers(event?: string, listener?: Function): boolean
- event string
optional
Event name for which to look. - listener Function
optional
Reference to a function instance that was used when subscribing.
let em = new Emitter()
let cb = () => {}
em.on('evt', cb)
em.on('evt', () => {})
em.on('evt3', () => {})
console.log( em.triggers('evt', cb) ) // true
em.off('evt', cb)
console.log( em.triggers('evt', cb) ) // false
console.log( em.triggers('evt') ) // true
em.off('evt')
console.log( em.triggers('evt') ) // false
console.log( em.triggers() ) // true
em.off()
console.log( em.triggers() ) // false