README.md

Knot.js

A browser-based event emitter, for tying things together.

Usage

Knot was developed with a modern JavaScript workflow in mind. To use it, it's recommended you have a build system in place that can transpile ES6, and bundle modules. For a minimal boilerplate that does so, check out outset.

Follow these steps to get started:

• Install
• Call

Then dig into the API.

Install

Using NPM, install Knot.js, and add it to your package.json dependencies.

$ npm install knot.js --save

Call

Simply import Knot, then call it.

• Passed no parameters, Knot will return a new emitter
• Passed an object, Knot will extend it to include the emitter methods

Note that the this context in the event handlers:

• Is the object passed in, if one was provided
• Otherwise, it is the emitter itself

// import Knot

import knot from 'knot.js'

// create a new emitter
// in the handlers, 'this' refers to the emitter

const emitter = knot()

// extend an existing object, transforming it into an emitter
// in the handlers, 'this' refers to the Class

const object = new Class()
const extended = knot(object)

API

All methods are chainable.

Knot exposes the following API:

• on
• once
• off
• emit

.on(name, handler)

Add a handler to a new or existing event.

// add an anonymous function as a handler

emitter.on('name', () => {
  // ...
})

// add a named function as a handler

const handler = () => {
  // ...
}

emitter.on('name', handler)

.once(name, handler)

Add a handler, that fires only once, to a new or existing event.

// add an anonymous function as a handler

emitter.once('name', () => {
  // ...
})

// add a named function as a handler

const handler = () => {
  // ...
}

emitter.once('name', handler)

.off(name[, handler])

Remove a specific handler from an event.

// handler must be a named function

const handler = () => {
  // ...
}

emitter.off('name', handler)

Remove all of an event's handlers.

emitter.off('name')

.emit(name[, arguments])

Emit an event, firing all of its handlers.

emitter.emit('name')

Optionally, include arguments that will be passed to each handler.

// accept arguments in handler

emitter.on('name', (a, b, c, d) => console.log(a, b, c, d))

// include arguments in call to emit

emitter.emit('name', 1, '2', [3], {})

// LOG: 1 '2' [3] {}

Browser Support

Tested in all modern browsers and IE10+.

License

MIT. © 2017 Michael Cavalea