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 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. 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 - 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
• Usage
• API
  • dush()
  • ._allEvents
  • .use
  • .on
  • .once
  • .off
  • .emit
• Related
• Contributing
• Building docs
• Running tests
• Author
• License

(TOC generated by verb using markdown-toc)

Install

Install with npm

$ npm install dush --save

or install using yarn

$ yarn add dush

or using unpkg CDN

<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 CDN

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

Usage

Modern importing, using [rollup][] or [webpack][] bundler

import dush from 'dush'

Node.js require as CommonJS module

var dush = require('dush')

Old school in browsers, available at global scope

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

API

dush()

A constructor function that returns an object with a few methods.

See JSBin Example.

• returns {Object}: methods

Example

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

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.

Example

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

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

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

Add handler for name event.

See JSBin Example.

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

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

Add handler for name event that will be called only one time.

See JSBin Example.

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

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

Remove handler for name event. If handler not passed will remove all listeners for that name event.

See JSBin Example.

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

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

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 argume