minibus.jsv3.1.0
Minimal event bus a.k.a. message dispatcher for JavaScript.
Basic example
> var bus = Minibus.create()
> var route = bus.on('out-of-fuel', function () {
console.log('Hitchhike.')
});
> bus.emit('out-of-fuel')
Hitchhike.
> bus.off(route)
> bus.emit('out-of-fuel')
(nothing)
Features
- Lightweight, about 600 bytes when compressed.
- Compatible with browsers, Node, CommonJS and AMD.
- Create a message bus by
var bus = Minibus.create()
- Bind event handlers by
bus.on('myevent', function () { ... })
- Bind only once by
bus.once('myevent', function () { ... })
- Emit events by
bus.emit('myevent')
- Pass parameters to handlers by
bus.emit('myevent', param1, param2, ...)
- Unbind the handlers of an event by
bus.off('myevent')
- Unbind a route by first
var route = bus.on('myevent', function () { ... })
and then bus.off(route)
- Unbind everything by
bus.off()
Installation
Browsers
<script src="scripts/minibus.js"></script>
CommonJS & Node.js
$ npm install minibus
---
> var Minibus = require('minibus');
AMD & Require.js
define(['scripts/minibus'], function (Minibus) { ... });
API
Minibus.create
Create a new bus
. Takes no parameters.
>> var bus = Minibus.create()
>> bus.on('hello', function () { ...
bus.emit
alias bus.trigger
Emit an event to execute the event handlers. The event handlers are executed immediately. Takes in an event string. Returns nothing.
>> bus.emit('out-of-fuel')
Alternatively takes in an array of event strings.
>> bus.emit(['out-of-fuel', 'radio-on'])
Accepts also extra parameters to be given as parameters to the event handler.
>> bus.on('out-of-fuel', function (litersFuelLeft) { ... })
>> bus.emit('out-of-fuel', 0.5)
Another example:
>> bus.on('flat-tire', function (frontOrBack, side) {
console.log('The ' + frontOrBack + ' ' + side + ' tire blew out');
});
>> bus.emit('flat-tire', 'front', 'right');
The front right tire blew out.
Throws InvalidEventStringError
if given event string is not a string or an array of strings.
bus.on
alias bus.listen
On an event string being emitted, execute an event handler function. Returns a route that can be used with off
to cancel this binding.
>> var route = bus.on('out-of-fuel', function () {
console.log('Hitchhike.')
})
>> bus.off(route)
Takes in an event string or an array of event strings and an event handler function.
>> bus.on(['out-of-fuel', 'battery-dead'], function () {
console.log('Call home.')
})
Throws InvalidEventStringError
if given event string is not a string or array of strings. Throws InvalidEventHandlerError
if given event handler is not a function.
bus.once
Bind once. Just like bus.on
but the event handler function can be executed only once and is then forgotten.
>> bus.once('out-of-fuel', function () {
console.log('Smoke your last cigarette.')
})
>> bus.emit('out-of-fuel')
'Smoke your last cigarette.'
>> bus.emit('out-of-fuel')
(nothing)
bus.off
alias bus.removeListener
Unbind one or many event handlers. Returns nothing. With no parameters, unbinds all the event handlers for all the event strings.
>> bus.off()
Takes in a route an array of routes returned by an on
or once
.
>> var route = bus.on('out-of-fuel', function () {
console.log('Hitchhike.')
})
>> bus.off(route)
>> bus.emit('out-of-fuel')
(nothing)
Alternatively takes in an array of routes.
>> bus.off([route, otherRoute])
Throws InvalidRouteStringError
if given route is not a string or array of strings.
Customize Minibus
Customize bus
by:
Minibus.extension.myFunction = function (...) {...};
After that you can:
var bus = Minibus.create();
bus.myFunction();
Repository branches
master
is for production-ready releases.develop
is for feature development
This convention follows a successful git branching model.
History
The development of Minibus started in 2013-02-15 after hassling with EventBus and Socket.IO. They either had complex API or solved too much. The 1.x.x and 2.x.x were designed in 2013. Codebase was completely rewritten to 3.x.x in the end of 2014.
See also
Versioning
Semantic Versioning 2.0.0
License
MIT License