ubus
Version:
Micro message bus for the browser.
177 lines (118 loc) • 4.18 kB
Markdown
# μBus
[](https://travis-ci.org/ericmdantas/uBus)
[](https://badge.fury.io/js/ubus)
### Install
```shell
$ npm i --save ubus
```
### What is this?
μBus (micro bus) is a micro implementation of a message bus/event emitter in javascript. It was created to be light, fast and intuitive - it's less than `500 bytes` when gzipped *(es2015 module)*.
The API is minimal and straight forward. There's `one` class and `four` methods - nothing more, nothing less.
You can use it anywhere javascript is being used, both server and client side.
Also, given there are a lot of different projects out there, `μBus` has `five` different `module loaders` for you to play with:
- `es2015`;
- `commonjs`;
- `systemjs`;
- `amd`;
- `umd`.
Pick the one that fits your project and have fun!
### API
#### on
```ts
bus.on(token: string, callback: Function): () => void
```
```js
const {Bus} = require('ubus');
let bus = new Bus();
bus.on('my-event', () => {
console.log('yo!'); // logs 'yo!' every time this Bus instance emits 'my-event'
});
bus.on('my-other-event', (info) => {
console.log(info); // logs info every time this Bus instance emits 'my-other-event'
});
```
#### once
```ts
bus.once(token: string, callback: Function):void
```
```js
const {Bus} = require('ubus');
let bus = new Bus();
bus.once('my-event', () => {
console.log('yo!'); // logs 'yo!' only once per bus instance
});
bus.once('my-other-event', (info) => {
console.log(info); // logs 'yo!' only once per bus instance
});
```
#### emit
```ts
bus.emit(token: string, info?: any):void
```
```js
const {Bus} = require('ubus');
let bus = new Bus();
bus.on('my-event', () => {
console.log('yo!'); // logs 'yo!' when 'my-event' is called
});
bus.on('my-other-event', (info) => {
console.log(info); // logs { yo: true } when 'my-other-event' is called
});
bus.emit('my-event');
bus.emit('my-other-event', { yo: true });
```
#### off
```ts
bus.off(token: string | string[]):void
```
```js
const {Bus} = require('ubus');
let bus = new Bus();
bus.on('my-event', () => {
console.log('yo!'); // logs 'yo!' when 'my-event' is emitted
});
bus.on('my-other-event', (info) => {
console.log(info); // logs { yo: true } when 'my-other-event' is emitted
});
bus.emit('my-event'); // will trigger the event
bus.emit('my-other-event', { yo: true }); // will trigger the event
bus.off('my-event');
bus.off('my-other-event');
/* or
bus.off([
'my-event',
'my-other-event'
]);
*/
bus.emit('my-event'); // won't trigger the event, nobody listening
bus.emit('my-other-event', { yo: true }); // won't trigger the event, nobody listening
```
#### destroy function
```ts
let destroyFn = bus.on(token: string, cb: Function): () => void
```
```js
const {Bus} = require('ubus');
let bus = new Bus();
let _destroyMyEvent = bus.on('my-event', () => {
console.log('yo!'); // logs 'yo!' when 'my-event' is called
});
let _destroyMyOtherEvent = bus.on('my-other-event', (info) => {
console.log(info); // logs { yo: true } when 'my-other-event' is called
});
bus.emit('my-event'); // triggers the event
bus.emit('my-other-event', { yo: true }); // triggers the event
_destroyMyEvent(); // destroys 'my-event'
_destroyMyOtherEvent(); // destroys 'my-other-event'
bus.emit('my-event'); // triggers nothing, no one listening
bus.emit('my-other-event', { yo: true }); // triggers nothing, no one listening
```
### Wiki
For more information on how to integrate with existing projects, Benchmarks, FAQ, Troubleshooting and other stuff, take a look at the [wiki](https://github.com/ericmdantas/uBus/wiki).
### Inspired by
- [Node.js](https://github.com/nodejs/node)'s EventEmitter.
- [socket.io](https://github.com/socketio/socket.io)'s simple API;
- [angular (1.x)](https://github.com/angular/angular.js)'s implementation of `$emit/$broadcast` and `$on`;
- [minibus](https://github.com/axelpale/minibus)'s compact API.
### LICENSE
MIT