tunnckoCore/dush

# dush [![npm version][npmv-img]][npmv-url] [![github tags][ghtag-img]][ghtag-url] [![mit license][license-img]][license-url]

> Microscopic & functional event emitter in ~350 bytes, extensible through plugins

_You might also be interested in [mitt][] - a 200 bytes event emitter. It has strict policy 
to stay exactly below 200b with no compromises, so has lack of support
for few things and that's why `dush` exists._

## Quality 👌

> By using [commitizen][czfriendly-url] and [conventional commit messages][conventional-messages-url], 
maintaining meaningful [ChangeLog][changelogmd-url] 
and commit history based on [global conventions][conventions-url], 
following [StandardJS][standard-url] code style through [ESLint][eslint-url] and
having always up-to-date dependencies through integrations
like [GreenKeeper][gk-integration-url] and [David-DM][daviddm-url] service,
this package has top quality.

[![code climate][codeclimate-img]][codeclimate-url] 
[![code style][standard-img]][standard-url] 
[![commitizen friendly][czfriendly-img]][czfriendly-url] 
[![greenkeeper friendly][gkfriendly-img]][gkfriendly-url] 
[![dependencies][daviddm-deps-img]][daviddm-deps-url] 
<!-- uncomment when need -->
<!-- [![develop deps][daviddm-devdeps-img]][daviddm-devdeps-url] -->

## Stability 💯

> By following [Semantic Versioning][semver-url] through [standard-version][] releasing tool, 
this package is very stable and its tests are passing both on [Windows (AppVeyor)][appveyor-ci-url] 
and [Linux (CircleCI)][circle-ci-url] with results 
from 100% to [400%][absolute-coverage-url] test coverage, reported respectively
by [CodeCov][codecov-coverage-url] and [nyc (istanbul)][nyc-istanbul-url].

[![following semver][following-semver-img]][following-semver-url] 
[![semantic releases][strelease-img]][strelease-url] 
[![linux build][circle-img]][circle-url] 
[![windows build][appveyor-img]][appveyor-url] 
[![code coverage][codecov-img]][codecov-url] 
[![nyc coverage][istanbulcov-img]][istanbulcov-url] 

## Support :clap:

> If you have any problems, consider opening [an issue][open-issue-url],
ping me on twitter ([@tunnckoCore][tunnckocore-twitter-url]),
join the [support chat][supportchat-url] room
or queue a [live session][codementor-url] on CodeMentor with me.
If you don't have any problems, you're using it somewhere or
you just enjoy this product, then please consider [donating some cash][paypalme-url] at PayPal,
since this is [OPEN Open Source][opensource-project-url] project made
with love at [Sofia, Bulgaria][bulgaria-url] 🇧🇬.

[![tunnckoCore support][supportchat-img]][supportchat-url] 
[![code mentor][codementor-img]][codementor-url] 
[![paypal donate][paypalme-img]][paypalme-url] 
[![NPM monthly downloads](https://img.shields.io/npm/dm/dush.svg?style=flat)](https://npmjs.org/package/dush) 
[![npm total downloads][downloads-img]][downloads-url] 

## Highlights :sparkles:

- **Microscopic:** Around ~400 bytes gzip + minify, including the UMD wrapper.
- **Functional:** Methods don't rely on `this` context.
- **Modern:** Work on latest JavaScript versions, but on Node.js 0.10 too.
- **Extensible:** Through simple plugins, for more customizations.
- **Compatibility:** Almost like Node's EventEmitter.
- **Compliant:** Can `.emit` events with multiple params.
- **Chaining:** Support all methods to be chainable.
- **Useful:** A wildcard `'*'` event type listens to all events.
- **Friendly:** Plays well with [browserify][], [webpack][] and browser users.
- **Bundled:** Available as ES6 Module, CommonJS and UMD.
- **Meaning:** [Hear it](https://translate.google.com/?hl=bg&tab=wT#en/bg/dush). It just means `shower` in Bulgarian.
- **Clean:** Does not mess with DOM or anything.

## Plugins

- [dush-router][] - Simple regex-based router with Express-like routing, for browser and nodejs
- [dush-promise][] - Makes `dush` a Deferred promise, centralized error handling
- [dush-methods][] - Adds `.define` and `.delegate` methods for defining non-enumerables
- [dush-options][] - Adds `.option` method and `app.options` property
- [dush-plugins](https://github.com/tunnckoCore/dush-plugins) - Upgrades the current plugin system with support for smart plugins
- [dush-tap-report][] - Produces TAP report, based on events such as `pass`, `fail`, `start` and `finish`
- [dush-better-use][] - Adds support for named plugins and better error handling
- [dush-no-chaining][] - Removes the support for chaining methods

## Table of Contents
- [Install](#install)
- [Usage](#usage)
- [API](#api)
  * [dush()](#dush)
  * [._allEvents](#_allevents)
  * [.use](#use)
  * [.on](#on)
  * [.once](#once)
  * [.off](#off)
  * [.emit](#emit)
- [Related](#related)
- [Contributing](#contributing)
- [Building docs](#building-docs)
- [Running tests](#running-tests)
- [Author](#author)
- [License](#license)

_(TOC generated by [verb](https://github.com/verbose/verb) using [markdown-toc](https://github.com/jonschlinkert/markdown-toc))_

## Install
Install with [npm](https://www.npmjs.com/)

```
$ npm install dush --save
```

or install using [yarn](https://yarnpkg.com)

```
$ yarn add dush
```

or using [unpkg](https://unpkg.com) CDN

```html
<script src="https://unpkg.com/dush/dist/dush.umd.js"></script>
```
> **Note:** Don't use Unpkg's short-hand endpoint `https://unpkg.com/dush`, 
since it points to CommonJS bundle.

or using [jsDelivr](https://www.jsdelivr.com/package/npm/dush) CDN

```html
<script src="https://cdn.jsdelivr.net/npm/dush/dist/dush.umd.js">
```

## Usage

Modern `import`ing, using [rollup][] or [webpack][] bundler

```js
import dush from 'dush'
```

Node.js `require` as CommonJS module

```js
var dush = require('dush')
```

Old school in browsers, available at global scope

```html
<script>
  var emitter = dush()
</script>
```

## API

### [dush()](src/index.js#L34)
> A constructor function that returns an object with a few methods.

See [JSBin Example](http://jsbin.com/mepemeluhi/edit?js,console).

* `returns` **{Object}**: methods  

**Example**

```js
const dush = require('dush')
const emitter = dush()

console.log(emitter._allEvents) // => {}
console.log(emitter.on) // => Function
console.log(emitter.once) // => Function
console.log(emitter.off) // => Function
console.log(emitter.emit) // => Function
```

### [._allEvents](src/index.js#L66)
> An listeners map of all registered events and their listeners. A key/value store, where 1) value is an array of event listeners for the key and 2) key is the name of the event.

See [JSBin Example](http://jsbin.com/fakajazafu/edit?js,console).

**Example**

```js
const emitter = dush()

emitter.on('foo', () => {})
emitter.on('foo', () => {})
emitter.on('bar', () => {})

console.log(emitter._allEvents)
// => { foo: [Function, Function], bar: [Functon] }

console.log(emitter._allEvents.foo.length) // => 2
console.log(emitter._allEvents.bar.length) // => 1
```

### [.use](src/index.js#L99)
> Invokes `plugin` function immediately, which is passed with `app` instance. You can use it for adding more methods or properties to the instance. Useful if you want to make dush to work with DOM for example.

**Params**

* `plugin` **{Function}**: A function passed with `(app, options)` signature    
* `options` **{Object}**: optional, passed as second argument to `plugin` function    
* `returns` **{Object}**: self "app" for chaining  

**Example**

```js
const app = dush()

app.on('hi', (str) => {
  console.log(str) // => 'Hello World!!'
})

app.use((app) => {
  app.foo = 'bar'
  app.hello = (place) => app.emit('hi', `Hello ${place}!!`)
})

console.log(app.foo) // => 'bar'
app.hello('World')
```

### [.on](src/index.js#L134)
> Add `handler` for `name` event.

See [JSBin Example](http://jsbin.com/xeketuruto/edit?js,console).

**Params**

* `name` **{String}**: Type of event to listen for, or `'*'` for all events    
* `handler` **{Function}**: Function to call in response to given event    
* `once` **{Boolean}**: Make `handler` be called only once, the `.once` method use this internally    
* `returns` **{Object}**: self "app" for chaining  

**Example**

```js
const emitter = dush()

emitter
  .on('hi', (place) => {
    console.log(`hello ${place}!`) // => 'hello world!'
  })
  .on('hi', (place) => {
    console.log(`hi ${place}, yeah!`) // => 'hi world, yeah!'
  })

emitter.emit('hi', 'world')
```

### [.once](src/index.js#L184)
> Add `handler` for `name` event that will be called only one time.

See [JSBin Example](http://jsbin.com/teculorima/edit?js,console).

**Params**

* `name` **{String}**: Type of event to listen for, or `'*'` for all events    
* `handler` **{Function}**: Function to call in response to given event    
* `returns` **{Object}**: self "app" for chaining  

**Example**

```js
const emitter = dush()
let called = 0

emitter.once('foo', () => {
  console.log('called only once')
  called++
})

emitter
  .emit('foo', 111)
  .emit('foo', 222)
  .emit('foo', 333)

console.log(called) // => 1
```

### [.off](src/index.js#L224)
> Remove `handler` for `name` event. If `handler` not passed will remove **all** listeners for that `name` event.

See [JSBin Example](http://jsbin.com/nujucoquvi/3/edit?js,console).

**Params**

* `name` **{String}**: Type of event to listen for, or `'*'` for all events    
* `handler` **{Function}**: Function to call in response to given event    
* `returns` **{Object}**: self "app" for chaining  

**Example**

```js
const emitter = dush()

const handler = () => {
  console.log('not called')
}

emitter.on('foo', handler)
emitter.off('foo', handler)

emitter.on('foo', (abc) => {
  console.log('called', abc) // => 'called 123'
})
emitter.emit('foo', 123)

// or removing all listeners of `foo`
emitter.off('foo')
emitter.emit('foo')
```

### [.emit](src/index.js#L270)
> Invoke all handlers for given `name` event. If present, `'*'` listeners are invoked too with `(type, ...rest)` signature, where the `type` argument is a string representing the name of the called event; and all of the rest arguments.

See [JSBin Example](http://jsbin.com/muqujavolu/edit?js,console).

**Params**

* `name` **{String}**: The name of the event to invoke    
* `args` **{any}**: Any number of arguments of any type of value, passed to each listener    
* `returns` **{Object}**: self "app" for chaining  

**Example**

```js
const emitter = dush()

emitter.on('foo', (a, b, c) => {
  console.log(`${a}, ${b}, ${c}`) // => 1, 2, 3
})

emitter.on('*', (name, a, b, c) => {
  console.log(`name is: ${name}`)
  console.log(`rest args are: ${a}, ${b}, ${c}`)
})

emitter.emit('foo', 1, 2, 3)
emitter.emit('bar', 555)
```

## Related
- [always-done](https://www.npmjs.com/package/always-done): Handle completion and errors with elegance! Support for streams, callbacks, promises, child processes, async/await and sync functions. A drop-in replacement… [more](https://github.com/hybridables/always-done#readme) | [homepage](https://github.com/hybridables/always-done#readme "Handle completion and errors with elegance! Support for streams, callbacks, promises, child processes, async/await and sync functions. A drop-in replacement for [async-done][] - pass 100% of its tests plus more")
- [dual-emitter](https://www.npmjs.com/package/dual-emitter): :tropical_drink: EventEmitter done right and no dependencies. For nodejs and the browser (>= IE8). Can emit custom or DOM events. | [homepage](https://github.com/tunnckocore/dual-emitter#readme ":tropical_drink: EventEmitter done right and no dependencies. For nodejs and the browser (>= IE8). Can emit custom or DOM events.")
- [mich-h](https://www.npmjs.com/package/mich-h): Create HAST-compliant virtual trees of HTML using [hyperscript][] compatible syntax, just in ~550 bytes. | [homepage](https://github.com/tunnckocore/mich-h#readme "Create HAST-compliant virtual trees of HTML using [hyperscript][] compatible syntax, just in ~550 bytes.")
- [minibase](https://www.npmjs.com/package/minibase): Minimalist alternative for Base. Build complex APIs with small units called plugins. Works well with most of the already existing… [more](https://github.com/node-minibase/minibase#readme) | [homepage](https://github.com/node-minibase/minibase#readme "Minimalist alternative for Base. Build complex APIs with small units called plugins. Works well with most of the already existing [base][] plugins.")
- [mitt](https://www.npmjs.com/package/mitt): Tiny 200b functional Event Emitter / pubsub. | [homepage](https://github.com/developit/mitt "Tiny 200b functional Event Emitter / pubsub.")
- [randomorg-js](https://www.npmjs.com/package/randomorg-js): Streaming Random.org JSON-RPC Javascript API - for node, command line (cli) and the browser. | [homepage](https://github.com/tunnckoCore/randomorg-js "Streaming Random.org JSON-RPC Javascript API - for node, command line (cli) and the browser.")
- [smitty](https://www.npmjs.com/package/smitty): Tiny flux implementation built on mitt | [homepage](https://github.com/tkh44/smitty#readme "Tiny flux implementation built on mitt")
- [try-catch-core](https://www.npmjs.com/package/try-catch-core): Low-level package to handle completion and errors of sync or asynchronous functions, using [once][] and [dezalgo][] libs. Useful for and… [more](https://github.com/hybridables/try-catch-core#readme) | [homepage](https://github.com/hybridables/try-catch-core#readme "Low-level package to handle completion and errors of sync or asynchronous functions, using [once][] and [dezalgo][] libs. Useful for and used in higher-level libs such as [always-done][] to handle completion of anything.")
- [unfetch](https://www.npmjs.com/package/unfetch): Bare minimum fetch polyfill in 500 bytes | [homepage](https://github.com/developit/unfetch "Bare minimum fetch polyfill in 500 bytes")

## Contributing
Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue][open-issue-url].  
Please read the [contributing guidelines][contributing-url] for advice on opening issues, pull requests, and coding standards.  
If you need some help and can spent some cash, feel free to [contact me at CodeMentor.io][codementor-url] too.

**In short:** If you want to contribute to that project, please follow these things

1. Please DO NOT edit [README.md](README.md), [CHANGELOG.md][changelogmd-url] and [.verb.md](.verb.md) files. See ["Building docs"](#building-docs) section.
2. Ensure anything is okey by installing the dependencies and run the tests. See ["Running tests"](#running-tests) section.
3. Always use `npm run commit` to commit changes instead of `git commit`, because it is interactive and user-friendly. It uses [commitizen][] behind the scenes, which follows Conventional Changelog idealogy.
4. Do NOT bump the version in package.json. For that we use `npm run release`, which is [standard-version][] and follows Conventional Changelog idealogy.

Thanks a lot! :)

## Building docs
Documentation and that readme is generated using [verb-generate-readme][], which is a [verb][] generator, so you need to install both of them and then run `verb` command like that

```
$ npm install verbose/verb#dev verb-generate-readme --global && verb
```

_Please don't edit the README directly. Any changes to the readme must be made in [.verb.md](.verb.md)._

## Running tests
Clone repository and run the following in that cloned directory

```
$ npm install && npm test
```

## Author
**Charlike Mike Reagent**

+ [github/tunnckoCore](https://github.com/tunnckoCore)
+ [twitter/tunnckoCore](https://twitter.com/tunnckoCore)
+ [codementor/tunnckoCore](https://codementor.io/tunnckoCore)

## License
Copyright © 2015, 2017, [Charlike Mike Reagent](https://i.am.charlike.online). Released under the [MIT License](LICENSE).

***

_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.4.3, on April 02, 2017._  
_Project scaffolded using [charlike][] cli._

[always-done]: https://github.com/hybridables/always-done
[async-done]: https://github.com/gulpjs/async-done
[base]: https://github.com/node-base/base
[browserify]: https://github.com/substack/node-browserify
[charlike]: https://github.com/tunnckocore/charlike
[commitizen]: https://github.com/commitizen/cz-cli
[dezalgo]: https://github.com/npm/dezalgo
[dush-better-use]: https://github.com/tunnckocore/dush-better-use
[dush-methods]: https://github.com/tunnckocore/dush-methods
[dush-no-chaining]: https://github.com/tunnckocore/dush-no-chaining
[dush-options]: https://github.com/tunnckocore/dush-options
[dush-promise]: https://github.com/tunnckocore/dush-promise
[dush-router]: https://github.com/tunnckocore/dush-router
[dush-tap-report]: https://github.com/tunnckocore/dush-tap-report
[hyperscript]: https://github.com/dominictarr/hyperscript
[mitt]: https://github.com/developit/mitt
[once]: https://github.com/isaacs/once
[rollup]: https://github.com/rollup/rollup
[standard-version]: https://github.com/conventional-changelog/standard-version
[verb-generate-readme]: https://github.com/verbose/verb-generate-readme
[verb]: https://github.com/verbose/verb
[webpack]: https://github.com/webpack/webpack

[license-url]: https://github.com/tunnckoCore/dush/blob/master/LICENSE
[license-img]: https://img.shields.io/npm/l/dush.svg

[downloads-url]: https://www.npmjs.com/package/dush
[downloads-img]: https://img.shields.io/npm/dt/dush.svg

[codeclimate-url]: https://codeclimate.com/github/tunnckoCore/dush
[codeclimate-img]: https://img.shields.io/codeclimate/github/tunnckoCore/dush.svg

[circle-url]: https://circleci.com/gh/tunnckoCore/dush
[circle-img]: https://img.shields.io/circleci/project/github/tunnckoCore/dush/master.svg?label=linux

[appveyor-url]: https://ci.appveyor.com/project/tunnckoCore/dush
[appveyor-img]: https://img.shields.io/appveyor/ci/tunnckoCore/dush/master.svg?label=windows

[codecov-url]: https://codecov.io/gh/tunnckoCore/dush
[codecov-img]: https://img.shields.io/codecov/c/github/tunnckoCore/dush/master.svg?label=codecov

[daviddm-deps-url]: https://david-dm.org/tunnckoCore/dush
[daviddm-deps-img]: https://img.shields.io/david/tunnckoCore/dush.svg

[daviddm-devdeps-url]: https://david-dm.org/tunnckoCore/dush?type=dev
[daviddm-devdeps-img]: https://img.shields.io/david/dev/tunnckoCore/dush.svg

[ghtag-url]: https://github.com/tunnckoCore/dush/tags
[ghtag-img]: https://img.shields.io/github/tag/tunnckoCore/dush.svg?label=github%20tag

[npmv-url]: https://www.npmjs.com/package/dush
[npmv-img]: https://img.shields.io/npm/v/dush.svg?label=npm%20version

[standard-url]: https://github.com/feross/standard
[standard-img]: https://img.shields.io/badge/code%20style-standard-brightgreen.svg

[paypalme-url]: https://www.paypal.me/tunnckoCore
[paypalme-img]: https://img.shields.io/badge/paypal-donate-brightgreen.svg

[czfriendly-url]: http://commitizen.github.io/cz-cli
[czfriendly-img]: https://img.shields.io/badge/commitizen-friendly-brightgreen.svg

[gkfriendly-url]: https://greenkeeper.io/
[gkfriendly-img]: https://img.shields.io/badge/greenkeeper-friendly-brightgreen.svg

[codementor-url]: https://www.codementor.io/tunnckocore?utm_source=github&utm_medium=button&utm_term=tunnckocore&utm_campaign=github
[codementor-img]: https://img.shields.io/badge/code%20mentor-live%20session-brightgreen.svg

[istanbulcov-url]: https://twitter.com/tunnckoCore/status/841768516965568512
[istanbulcov-img]: https://img.shields.io/badge/istanbul-400%25-brightgreen.svg

[following-semver-url]: http://semver.org
[following-semver-img]: https://img.shields.io/badge/following-semver-brightgreen.svg

[strelease-url]: https://github.com/conventional-changelog/standard-version
[strelease-img]: https://img.shields.io/badge/using-standard%20version-brightgreen.svg

[supportchat-url]: https://gitter.im/tunnckoCore/support
[supportchat-img]: https://img.shields.io/gitter/room/tunnckoCore/support.svg

[bulgaria-url]: https://www.google.bg/search?q=Sofia%2C+Bulgaria "One of the top 10 best places for start-up business in the world, especially in IT technologies"

[changelogmd-url]: https://github.com/tunnckoCore/dush/blob/master/CHANGELOG.md
[conventions-url]: https://github.com/bcoe/conventional-changelog-standard/blob/master/convention.md
[tunnckocore-twitter-url]: https://twitter.com/tunnckoCore
[opensource-project-url]: http://openopensource.org
[nyc-istanbul-url]: https://istanbul.js.org
[circle-ci-url]: https://circleci.com
[appveyor-ci-url]: https://appveyor.com
[codecov-coverage-url]: https://codecov.io
[semver-url]: http://semver.org
[eslint-url]: http://eslint.org
[conventional-messages-url]: https://github.com/conventional-changelog/conventional-changelog
[gk-integration-url]: https://github.com/integration/greenkeeper
[daviddm-url]: https://david-dm.org
[open-issue-url]: https://github.com/tunnckoCore/dush/issues/new
[contributing-url]: https://github.com/tunnckoCore/dush/blob/master/CONTRIBUTING.md
[absolute-coverage-url]: https://github.com/tunnckoCore/dush/blob/master/package.json