krmax44 / houk

A super simple event bus.

Houk

A safely typed, super simple, universal event bus with awesome IDE auto completions. Requires TypeScript 4+.

Installation

yarn add houk
# or using npm
npm i houk

Usage

Class-based

See the complete API below.

import Houk from 'houk';

class CoffeeShop extends Houk<{
	order: [name: string, type: string];
}> {
	makeMeACoffee() {
		const name = 'Max';
		const type = 'Cappuccino with oat milk';

		this.emit('order', name, type);
	}
}

const barista = new CoffeeShop();
barista.on('order', (name, type) => {
	console.log(`${name} would like a ${type}, please.`);
});

barista.makeMeACoffee();

// --> Max would like a Cappuccino with oat milk, please.

as an open bus

See the complete API below.

import { HoukBus } from 'houk';

const coffeeShop = new HoukBus<{
	order: [name: string, type: string];
}>();

coffeeShop.on('order', (name, type) => {
	console.log(`${name} would like a ${type}, please.`);
});

const name = 'Max';
const type = 'Cappuccino with oat milk';
coffeeShop.emit('order', name, type);

// --> Max would like a Cappuccino with oat milk, please.

API

Constructor

The Houk constructor requires one type argument:

class MyClass extends Houk<{
	eventName: [arg1: string, arg2: number];
}> {}

The object links the event names to the arguments the listener functions will receive. As labeled tuple types were introduced with TypeScript 4, make sure to be on the latest version. In the example above, the listener function for the event eventName must be called with arg1 of type string and arg2 with type number. Rest parameters and optional types are possible.

Houk.on

Listen to a particular event. Takes the event name, a listener function and whether the listener should only be called once (false by default).

on(eventName, listener, once?): void

Houk.off

Unregister an event listener. Returns true on success and false when the event listener didn't exist before.

off(eventName, listener) => boolean

Houk.awaitEvent

Returns a promise that will resolve, once the given event was triggered.

await houk.awaitEvent('myEvent');
console.log('myEvent was emitted');

Houk.emit

Only available to deriving classes. Trigger all listeners of a particular event. ...args will be passed along to the listeners.

The listeners will all be called at once. It returns a Promise, which will resolve once all listeners have reached completion.

emit(eventName, ...args) => Promise

Houk.emitSync

Only available to deriving classes. Trigger all listeners of a particular event. ...args will be passed along to the listeners.

The listeners will be called once at a time, in order of registration. It returns a Promise, which will resolve once all listeners have reached completion.

emit(eventName, ...args) => Promise

Houk.getListeners

Only available to deriving classes, returns a set of listener functions.

getListeners(eventName) => Set<() => {})>

HoukBus

You can also create an open bus, using HoukBus:

import { HoukBus } from 'houk';

const bus = new HoukBus<EventTypes>();

The same API from Houk applies to HoukBus, except that all methods are public.

v3 Breaking Changes

Houk used to be both an event and hook chain bus. The concept of combining those two into one is neat, but definitely janky at times, which paired together with type safety doesn't feel right. Therefore, I decided to drop hook chains and make Houk a super-simple, type-safe event bus only.