arbitrary-emitter

arbitrary-emitter

High performance event emitter for modern browsers in ~450 bytes.

Features

This event emitter was designed with 4 goals in mind:

• Be lightweight: ~450 bytes when gzipped
• Be fast: it's optimized for being quick even with lots of emitters
• Be conventional: with conventional api (on, off, once and emit)
• Be modern: it stores listeners in ES6 maps, so you can use any kind of value as key for the listeners (See usage example)

It's written in vanilla ES6, so you will have to transpile it before using it in old browsers or node.js < v5.9

Usage

Install with npm, clone the repo or download and extract the zip. Then import or insert it as script tag.

const emitter = arbitraryEmitter()
const key = {}
emitter.on(key, () => doSomething())
// will `doSomething`
emitter.emit(key)

Emitter API

• on
• off
• once
• emit
• listeners

on(eventKey, listener)

Adds the listener function to the end of the listeners array for the event tagged with eventKey. eventKey can be any type of value. A check is made to see if the listener has already been added so it won't be called multiple times. Event listeners are invoked in the order they are added.

const key = {}
emitter.on(key, () => doSomething())
emitter.emit(key) // will `doSomething`

once(eventKey, listener)

Same as on, but listener will be triggered just one time, then it will be removed.

const key = {}
emitter.once(key, () => doSomethingOnce())
emitter.emit(key) // will `doSomethingOnce`
emitter.emit(key) // won't do anything

emit(eventKey[, options])

Synchronously calls each of the listeners registered for the event tagged with eventKey, passing the supplied argument options to each

emitter.on('test', (opts) => console.log(opts.test))
const options = { test: 'Testing!' }
emitter.emit('test', options) // => 'Testing!'

off([eventKey[, listener]])

• When no argument is passed all the listeners and its eventKeys will be removed from the emitter
• If an eventKey but no listener is passed all the listeners and its key will be removed
• If eventKey and listener are passed as arguments just the listener will be removed from its group

emitter.off(key, action) // will remove action from listeners
emitter.off(key) // will remove all the listeners tagged with `key`, and the tag itself
emitter.off() // will remove all the listeners from all the eventKeys and the eventKeys themselves

listeners(eventKey)

Returns a copy of the array of listeners for the event tagged eventKey

const key = {}
const f1 = () => console.log('f1')
const f2 = () => console.log('f2')
emitter.on(key, f1)
emitter.on(key, f2)
emitter.listeners(key)[0] === f1 // true
emitter.listeners(key)[1] === f2 // true

Testing

Node

npm test

Browser

Build browser tests (npm run build-tests) and open test/test.html

Building

• Build UMD file: npm run build-umd
• Build browser tests: npm run build-tests
• Run both builds: npm run build

---

© 2016 Jacobo Tabernero - Released under MIT License