# Event PubSub
npm info :
  
GitHub info :
  
***Super light and fast*** Extensible PubSub events and EventEmitters for Node and the browser with support for ES6 by default, and ES5 versions for older verions of node and older IE/Safari versions.
For older versions of node and io.js the latest versions of `event-pubsub` may work with the --harmony flag. Officially though, we support node v4 and newer with es5 and es6
Easy for any developer level. No frills, just high speed events following the publisher subscriber pattern!
[Pretty GitHub.io site](http://riaevangelist.github.io/event-pubsub/)
[See NPM stats for event-pubsub](http://npm-stat.com/charts.html?package=event-pubsub&author=&from=&to=)
**EXAMPLE FILES**
1. [Node Event PubSub Examples](https://github.com/RIAEvangelist/event-pubsub/tree/master/examples/node)
2. [Browser Event PubSub Examples](https://github.com/RIAEvangelist/event-pubsub/tree/master/examples/browser)
**Node Install**
`npm i --save event-pubsub`
By default the correct version (ES5/ES6) will be included. You can force the es5/6 version by requiring `event-pubsub/es5` or `event-pubsub/es6`.
**Browser Install**
*see browser examples above or below*
```html
<script src='path/to/event-pubsub-browser.js'></script>
<!-- OR ES5 for older browser support
<script src='path/to/event-pubsub-browser-es5.js'></script>
-->
```
# Methods
|Method|Arguments|Description|
|------|---------|-----------|
|subscribe|type (string), handler(function), once (bool/optional)|will bind the `handler` function to the the `type` event. Just like `addEventListener` in the browser. If once is set to true the hander will be removed after being called once.|
|on|same as above|same as above|
|once|type (string), handler(function)| will bind the `handler` function to the the `type` event and unbind it after ***one*** execution. Just like `addEventListener` in the browser withe the `once` option set|
|unSubscribe|type (string), handler(function or *)|will ***un***bind the `handler` function from the the `type` event. If the `handler` is `*`, all handlers for the event type will be removed. Just like `removeEventListener` in the browser, but also can remove all event handlers for the type.|
|off|same as above|same as above|
|publish|type (string), ...data arguments|will call all `handler` functions bound to the event `type` and pass all `...data arguments` to those handlers|
|emit|same as above|same as above|
|trigger|same as above|same as above|
While `publish`, `subscribe`, and `unSubscribe` are the proper method names for the publisher/subscriber model, we have included `on`, `off`, and `emit` as well because these are the most common event method names, and shorter. We have also kept the `trigger` method as an alias for `publish` and `emit` for backwards compatability with earlier versions of `event-pubsub`.
# The ` * ` type
The ` * ` type is a special event type that will be triggered by ***any publish or emit*** the handlers for these should expect the first argument to be the type and all arguments after to be data arguments.
## Basic Examples
***NOTE - the only difference between node and browser code is how the `events` variable is created***
* node ` const events = new Events `
* browser `const events = new window.EventPubSub;`
#### Node
```javascript
// ES5/ES6 now automatically chosen based on node version
const Events = new require('event-pubsub');
const events=new Events;
events.on(
'hello',
function(data){
console.log('hello event recieved ', data);
events.emit(
'world',
{
type:'myObject',
data:{
x:'YAY, Objects!'
}
}
)
}
);
events.on(
'world',
function(data){
console.log('World event got',data);
events.off('*','*');
console.log('Removed all events');
}
);
events.emit(
'hello',
'world'
);
```
#### Basic Chaining
```javascript
events.on(
'hello',
someFunction
).on(
'goodbye',
anotherFunction
).emit(
'hello',
'world'
);
events.emit(
'goodbye',
'complexity'
).off(
'hello',
'*'
);
```
#### Browser
##### HTML
```html
<!DOCTYPE html>
<html>
<head>
<title>PubSub Example</title>
<script src='../../event-pubsub-browser.js'></script>
<!-- OR ES5 for older browser support
<script src='../../event-pubsub-browser-es5.js'></script>
-->
<script src='yourAmazingCode.js'></script>
</head>
<body>
...
</body>
</html>
```
##### Inside Your Amazing Code
```javascript
var events = new window.EventPubSub();
events.on(
'hello',
function(data){
console.log('hello event recieved ', data);
events.emit(
'world',
{
type:'myObject',
data:{
x:'YAY, Objects!'
}
}
)
}
);
events.emit(
'hello',
'world'
);
events.emit(
'hello',
'again','and again'
);
```
### Basic Event Emitter and/or Extending Event PubSub
```javascript
// ES5/ES6 now automatically chosen based on node version
const Events = require('event-pubsub');
// manually include es6
// const Events = require('event-pubsub/es6');
class Book extends Events{
constructor(){
super();
//now Book has .on, .off, and .emit
this.words=[];
}
add(...words){
this.words.push(...words);
this.emit(
'added',
...words
);
}
read(){
this.emit(
'reading'
);
console.log(this.words.join(' '));
}
}
const book=new Book;
book.on(
'added',
function(...words){
console.log('words added : ',words);
this.read();
}
);
book.add(
'once','upon','a','time','in','a','cubicle'
);
```
##### ES5 extention example
```javascript
// manually include es5
const Events = require('event-pubsub/es5.js');
function Book(){
//extend happens below
Object.assign(this,new Events);
//now Book has .on, .off, and .emit
this.words=[];
this.add=add;
this.erase=erase;
this.read=read;
function add(){
arguments.slice=Array.prototype.slice;
this.words=this.words.concat(
arguments.slice()
);
this.emit(
'added',
arguments.slice()
);
}
function read(){
this.emit(
'reading'
);
console.log(this.words.join(' '));
}
return this;
};
const book=new Book;
book.on(
'added',
function(...words){
console.log('words added : ',words);
this.read();
}
);
book.add(
'once','upon','a','time','in','a','cubicle'
);
```
![[ICO]](/icons/blank.gif){kind=icon}
![[PARENTDIR]](/icons/back.gif){kind=icon}
![[ ]](/icons/unknown.gif){kind=icon}
![[TXT]](/icons/text.gif){kind=icon}