typed-emitter

Strongly typed simple event emitter with zero dependencies. It works on arbitrary JS engines.

Support

| Env | Version | Status | |---------|---------|:------:| | Node.js | 12.x | never | | Node.js | 14.x | ok | | Node.js | 16.x | ok | | Browser | latest | ok |

Install

npm i @kotofurumiya/typed-emitter

API Reference

See API Document.

Overview

Without types.

import { Emitter } from '@kotofurumiya/typed-emitter';

const emitter = new Emitter();
const listener = (event) => console.log(event);
emitter.listen('myevent', listener);
emitter.listen('myawesomeevent', listener, { once: true });
emitter.emit('myevent', { name: 'John' });
emitter.unlisten(listener);

With types.

import { Emitter } from '@kotofurumiya/typed-emitter';

// define `eventName: eventType` record type.
type MyEventMap = {
  foo: string;
  bar: {
    name: string;
  }
};

// apply it
const emitter = new Emitter<MyEventMap>();

// ok and types are inferred automatically
emitter.listen('foo', (val) => console.log(val));
emitter.listen('bar', ({name}) => console.log(name));

// type mismatch error
emitter.listen('foo', ({ zzz }) => console.log(zzz));
emitter.listen('bar', ({name}) => console.log(name));

// type error('awesome' event does not exists)
emitter.listen('awesome', (event) => console.log(event));

// ok to emit event
emitter.emit('foo', 'hello!');
emitter.emit('bar', { name: 'John' });

// type mismatch error
emitter.emit('foo', 123);
emitter.emit('bar', true);

Basic Usage

Usually, you want to use a emitter with extends. It's possible of course.

class GameEnemy extends Emitter<GameEvent> {
  constructor() {
    // `super()` in constructor is required. Don't forget.
    super();
  }
};

But to simplify explanation, I'll use bare Emitter here.

It's very simple to use Emitter. Just listen and emit, it's all.

import { Emitter } from '@kotofurumiya/typed-emitter';

const emitter = new Emitter();
const listener = (event) => console.log(event);
emitter.listen('myevent', listener);
emitter.listen('myawesomeevent', listener, { once: true });
emitter.emit('myevent', { name: 'John' });
emitter.unlisten(listener);

These methods are strongly typed. If you give definition of "events" to Emitter, your text editor can suggest and lint wisely.

import { Emitter } from '@kotofurumiya/typed-emitter';

const emitter = new Emitter<{ foo: string }>();

// error! 'foo' must emit `string`
emitter.emit('foo', 123);

If you don't need type checks, you can omit it.

// with type check
const emitter = new Emitter<{ foo: string }>();

// without type check
const emitter = new Emitter();

Advanced Usage

Once listener

You can register a listener as "once" listener by passing { once: true } to listen method.

"once" listener will be automatically removed after event is fired.

emitter.listen('myevent', listener, { once: true });

once listeners can be removed with emitter.unlisten.

emitter.listen('myevent', listener, { once: true });
emitter.unlisten('myevent', listener);

Unlisten function

listen method returns a unlitening function. This function is same as emitter.unlisten(eventName, listener).

const unlisten = emitter.listen('myevent', listener);
unlisten(); // same as `emitter.unlisten('myevent', listener)`

If you want to prune all listeners, you can use unlistenAllOf.

// Remove all 'myevent' listeners, includes once listeners.
emitter.unlistenAllOf('myevent');