/remitter

A TypeScript friendly event emitter with lazy re-emitting events

Primary LanguageTypeScriptMIT LicenseMIT

remitter

Docs Build Status Coverage Status

npm-version minified-size no-dependencies tree-shakable side-effect-free

A tiny TypeScript friendly event emitter that supports lazy re-emitting events from other sources.

Install

npm add remitter

Usage

import { Remitter } from "remitter";

interface EventData {
  event1: string;
  event2: void;
}

const remitter = new Remitter<EventData>();

const disposer = remitter.on("event1", value => {
  console.log("event1", value);
});

remitter.once("event1", value => {
  console.log("event1-once", value);
});

remitter.has("event1"); // true

remitter.emit("event1", "hello"); // logs "event1 hello" and "event1-once hello"

remitter.emit("event1", "hello"); // logs "event1 hello"

remitter.emit("event2"); // nothing logs

disposer();
remitter.emit("event1", "world"); // nothing logs

remitter.clear("event2"); // remove all listeners for event2

remitter.has(); // false

remitter.dispose(); // removes all listeners and dispose tapped events

Listen to any event

import { Remitter } from "remitter";

interface EventData {
  event1: string;
  event2: string;
}

const remitter = new Remitter<EventData>();

remitter.onAny(({ event, data }) => {
  console.log(event, data);
});

remitter.emit("event1", "hello"); // logs "event1 hello"
remitter.emit("event2", "world"); // logs "event2 world"

Listen to unhandled subscriber errors

import { Remitter } from "remitter";

interface EventData {
  event1: string;
  event2: string;
}

const remitter = new Remitter<EventData>();

remitter.onError(error => {
  console.log(error);
});

remitter.emit("event1", () => {
  throw new Error("error");
});

remitter.emit("event2", async () => {
  await new Promise(resolve => setTimeout(resolve, 100));
  throw new Error("async-error");
});

Remit

You may tap into other events easily with remit. It is lazy-executed when listener count of the event name grows from 0 to 1. It is disposed when listener count of the event name drops from 1 to 0.

remitter.remit("cursor", () => {
  const handler = ev => {
    remitter.emit("cursor", { x: ev.clientX, y: ev.clientY });
  };

  window.addEventListener("mousemove", handler);

  return () => {
    window.removeListener("mousemove", handler);
  };
});

// Remit callback does not execute until the first "cursor" listener is added
remitter.on("cursor", value => {
  console.log("cursor", value);
});

// Remit callback is disposed when no listener on the
// "cursor" event. (`window.removeListener` triggered)
remitter.clear("cursor");

The callback function can also be a pure function.

const myCursorEvent = remitter => {
  const handler = ev => {
    remitter.emit("cursor", { x: ev.clientX, y: ev.clientY });
  };

  window.addEventListener("mousemove", handler);

  return () => {
    window.removeListener("mousemove", handler);
  };
};

remitter.remit("cursor", myCursorEvent);

Acknowledgment

Huge thanks to @recursivefunk for giving away the NPM package name remitter.