subscribe/README.md

A simple better event emitter

# [Kucukkanat's Emitter](https://kucukkanat.github.io/subscribe/)

## Table of Contents

-   [Install](#install)
-   [Usage](#usage)
-   [Examples & Demos](#examples--demos)
-   [API](#api)
-   [Contribute](#contribute)
-   [License](#license)

## Install
This project uses [node](http://nodejs.org) and [npm](https://npmjs.com). Go check them out if you don't have them locally installed.

```sh
$ npm install --save subscribe
```


```javascript
// using ES6 modules
import { Emitter } from 'subscribe'

// using CommonJS modules
var { Emitter } = require('subscribe')
```

The [UMD](https://github.com/umdjs/umd) build is also available on [unpkg](https://unpkg.com/@hackdonalds/emitter@0.5.1/dist/index.js):

```html
<script src="https://esm.sh/subscribe"></script>
```

You can find the library on `window.__Emitter__`.

## Usage

```js
import {Emitter} from 'subscribe'
// OR
const {Emitter} = require('subscribe')

const eventbus = new Emitter()

// listen to an event
eventbus.on('foo', e => console.log('foo', e) )

// listen to all events
// This will fire first the 'type' event if it exists
eventbus.on('*', (type, e) => console.log(type, e) )

// fire an event
eventbus.emit('foo', { a: 'b' })

// working with handler references:
function onFoo() {}
eventbus.on('foo', onFoo)   // listen
eventbus.off('foo', onFoo)  // unlisten

// remove all listeners for specific event
eventbus.off('foo')

// Fire event listener only once
eventbus.once('knock knock', (data) => console.log("I will be fired only once"))
eventbus.emit('knock knock', null)
// This will not fire
eventbus.emit('knock knock', null)
```

## Typescript

For better autocompletion Emitter class takes parameters for possible event names : 

```js
import {Emitter} from 'subscribe'
const emitter = new Emitter<'foo' | 'bar'>()
emitter.on('foo', e => console.log('foo', e) )
emitter.on('bar', e => console.log('foo', e) )
// Will throw an error: (on typescript typecheck NOT ON RUNTIME!)
emitter.on('bar2', e => console.log('foo', e) )
```

* * *

## API
<!-- Generated by documentation.js. Update this documentation by updating the source code. -->

### Table of Contents

*   [constructor][1]
    *   [Parameters][2]
*   [on][3]
    *   [Parameters][4]
*   [off][5]
    *   [Parameters][6]
*   [emit][7]
    *   [Parameters][8]

## constructor

Use the constructor to initiate the eventbus with handlers

### Parameters

*   `` &#x20;
*   `listeners` **EventHandlerMap**&#x20;

## on

Register an event handler for the given type.

### Parameters

*   `type` **[String][9]** Type of event to listen for, or `"*"` for all events
*   `handler` **[Function][10]** Function to call in response to given event

## off

Remove an event handler for the given type.

### Parameters

*   `type` **[String][9]** Type of event to unregister `handler` from, or `"*"`
*   `handler` **[Function][10]** Handler function to remove

## emit

Invoke this.listeners handlers for the given type.
If present, `"*"` handlers are invoked after type-matched handlers.

Note: Manually firing "\*" handlers is not supported.

### Parameters

*   `type` **[String][9]** The event type to invoke
*   `evt` **Any?** Any value (object is recommended and powerful), passed to each handler

[1]: #constructor

[2]: #parameters

[3]: #on

[4]: #parameters-1

[5]: #off

[6]: #parameters-2

[7]: #emit

[8]: #parameters-3

[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String

[10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function


### Reporting Issues

Found a problem? Want a new feature? First of all see if your issue or idea has [already been reported](../../issues).
If don't, just open a [new clear and descriptive issue](../../issues/new).


## License

[MIT License](https://opensource.org/licenses/MIT) © [Kucukkanat](https://github.com/kucukkanat)