emitting v1.1.0

Emitting

[Github | NPM | Typedoc]

Emitting is a simple event emitter designed for TypeScript and Promises. There are some differences from other emitters:

• Exactly typing for event payloads new EventEmitter<Events>()
• Waiting for event with .take("event"): Promise<Payload> and same
• Do not throw an error when you emit an error event and nobody is listening
• Functional — methods don't rely on this
• Small size. No dependencies. Size Limit controls the size.

Table of contents

• Installation
• Polyfills
• Usage
  • JavaScript
  • TypeScript
• API
  • Constructor
  • .on(eventName, handler) — add event listener
  • .once(eventName, handler) — listen event once
  • .emit(eventName, payload) — send event to listeners
  • .emitCallback(eventName) — create emitter function
  • .take(event): Promise — wait for event
  • .takeTimeout(event, ms): Promise — wait for event or reject
  • .takeEither(successEvent, failureEvent): Promise — resolve or reject promise with events
  • Unsubscribe from events
  • .off(eventName) — remove all listeners
• Roadmap
• License

Installation

# NPM
npm instal --save emitting

# Yarn
yarn add emitting

Polyfills

Module built to ECMAScript 5.

Be sure to add polyfills if neccessary for:

• Promise
• Set
• Map

Usage

JavaScript

After installation the only thing you need to do is require the module:

const { EventEmitter } = require("emitting")

const emitter = new EventEmitter()

TypeScript

After installation you need to import module and define events:

import { EventEmitter } from "emitting"

type Events = {
  hello: { name: string }
  bye: void
}

const emitter = new EventEmitter<Events>()
// Now you have typed event emitter 🚀 yay!

API

Documentation for API generated by TypeDOC — emitting.sova.dev

Constructor

Receives type parameter Events that should be object type or interface, where key is an event name and value is an payload as a single parameter type.

type Events = {
  eventName: PayloadType
}

Pass Events to constructor generic parameter:

import { EventEmitter } from "emitting"

type Events = {
  hello: { name: string }
  bye: void
}

const emitter = new EventEmitter<Events>()

Now you can emit events and subscribe to.

.on(eventName, handler) — add event listener

.on() receives an event name and an event handler. Event handler should be a function that receives a payload. .on() returns unsubscribe function to remove created subscribtion.

function helloHandler(payload: { name: string }) {
  console.log(payload.name)
}

function byeHandler() {
  console.log("Goodbye!")
}

emitter.on("hello", helloHandler)
emitter.on("bye", byeHandler)

.once(eventName, handler) — listen event once

Subscribes to event, and when it received immediately unsubscribe. Subscribtion can be canceled at any time.

const cancel = emitter.on("hello", helloHandler)

cancel() // subscription cancelled

.emit(eventName, payload) — send event to listeners

Executes all listeners with passed payload. Accepts only one payload parameter. Use object type or tuple type to pass multiple payloads. If no listeners nothing happens.

emitter.emit("hello", { name: "world" })

.emitCallback(eventName) — create emitter function

Create function that emit event when called. Payload should be passed to returned callback.

const hello = emitter.emitCallback("hello")

hello({ name: "world" }) // emitted "hello" event

.take(event): Promise — wait for event

Creates promise that resolves when specified event is received. Returns Promise resolved with payload of the passed event. Listeners removed after event is received.

type Events = {
  example: number
}
const emitter = new EventEmitter<Events>()

emitter.take("example").then((payload) => {
  console.log("Received", payload)
})

emitter.emit("example", 10) // Received 10

With async/await:

const payload: number = await emitter.take("example")

.takeTimeout(event, ms): Promise — wait for event or reject

Creates a promise that resolves when specified event is received. Promise resolves with payload of the received event. Promise is rejected when timeout is reached. Listeners removed after timeout is reached, and event is received.

try {
  const { name } = await emitter.takeTimeout("hello", 300)
} catch (_) {
  console.info("Event `hello` is not emitted in 300 ms after subscribing to")
}

.takeEither(successEvent, failureEvent): Promise — resolve or reject promise with events

Returns promise that resolves when successEvent is emitted with the payload of event. Promise rejected when failureEvent is emitted, as error passed payload of the failureEvent. Listeners removed when successEvent or failureEvent is received and promise resolves just once.

emitter
  .takeEither("success", "failure")
  .then((payload) => console.log("Yeeah", payload))
  .catch((error) => console.log("Noooo", error))

emitter.emit("success", 500) // Yeeah 500
// or
emitter.emit("failure", "Vader is my father!") // Noooo Vader is my father

Unsubscribe from events

The .on(), .once() and same returns unsubscribe function, that can be called multiple times at any time.

const unsubscribeHello = emitter.on("hello", helloHandler)
const unsubscribeBye = emitter.on("bye", helloHandler)

unsubscribeHello() // now helloHandler will not be called when "hello" is emitted

.off(eventName) — remove all listeners

Note: destructive operation

The method removes all listeners from emitter. Use it with caution, if called .take methods, promises will never be fullfilled.

emitter.off("hello") // all listeners removed

Roadmap

• Add emitter.off(eventName, handler)
• Add * event to listen all events
• Add emitter.events(): string[]
• Add emitting::listenerAdded, emitting::listenerRemoved
• Add support for reactive (.subscribe)
• Add async iterators (.iterate(eventName))
• Add benchmarks
• Add .public(): PublicEmitter and .private(): PrivateEmitter

License

MIT