README.md

dush

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 and conventional commit messages, maintaining meaningful ChangeLog and commit history based on global conventions, following StandardJS code style through ESLint and having always up-to-date dependencies through integrations like GreenKeeper and David-DM service, this package has top quality.

Stability 💯

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

Support 👏

If you have any problems, consider opening an issue, ping me on twitter (@tunnckoCore), join the support chat room or queue a live session 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 at PayPal, since this is OPEN Open Source project made with love at Sofia, Bulgaria 🇧🇬.

Highlights ✨

• 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 arguments.

See JSBin Example.

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

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: Handle completion and errors with elegance! Support for streams, callbacks, promises, child processes, async/await and sync functions. A drop-in replacement… more | homepage
• dual-emitter: 🍹 EventEmitter done right and no dependencies. For nodejs and the browser (>= IE8). Can emit custom or DOM events. | homepage
• mich-h: Create HAST-compliant virtual trees of HTML using hyperscript compatible syntax, just in ~550 bytes. | homepage
• minibase: Minimalist alternative for Base. Build complex APIs with small units called plugins. Works well with most of the already existing… more | homepage
• mitt: Tiny 200b functional Event Emitter / pubsub. | homepage
• randomorg-js: Streaming Random.org JSON-RPC Javascript API - for node, command line (cli) and the browser. | homepage
• smitty: Tiny flux implementation built on mitt | homepage
• 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 | homepage
• unfetch: Bare minimum fetch polyfill in 500 bytes | homepage

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
Please read the contributing guidelines 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 too.

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

1. Please DO NOT edit README.md, CHANGELOG.md and .verb.md files. See "Building docs" section.
2. Ensure anything is okey by installing the dependencies and run the tests. See "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.

Running tests

Clone repository and run the following in that cloned directory

$ npm install && npm test

Author

Charlike Mike Reagent

• github/tunnckoCore
• twitter/tunnckoCore
• codementor/tunnckoCore

License

Copyright © 2015, 2017, Charlike Mike Reagent. Released under the MIT License.

---

This file was generated by verb-generate-readme, v0.4.3, on April 02, 2017.
Project scaffolded using charlike cli.