@line-8/announcer v1.2.0

Announcer 📣

Modern, high-performance event emitter

• 🏃 Blazing fast
  Micro-optimised to achieve high speeds, even with a large amount of listeners, often outperforming the competition.
• 💪 Strongly typed
  Easily add type safety when using TypeScript, catching potential errors during compilation and making development overall significantly more pleasant.
• 🏖 Incredibly convenient
  Provides a modern interface that makes subscription management a breeze — effortlessly remove listeners!
• 🧳 Portable everywhere
  ES3 compatible, dependency-free, supports all major module systems and can be used in browsers, workers and Node.js.

...now sugar-free!

Installation

• Node.js
  Install the announcer package from npm

  npm i -D announcer@npm:@line-8/announcer

• UMD
  Load the announcer module from a CDN

  https://cdn.jsdelivr.net/npm/@line-8/announcer/lib/index.min.js

Usage

After installation, simply import the module with whatever module system you are using. Be aware that Announcer provides named exports only.

import { Announcer } from "announcer";

Now you are ready to create your own emitters.

const emitter = new Announcer();

let listener = emitter.on("📣", console.log);

emitter.emit("📣", "Mind the gap");
// → "Mind the gap"

listener.dispose();

emitter.emit("📣", "Stand clear of the closing doors");
// Nothing happens

TypeScript

The Announcer class accepts a single record as a type argument, which is that maps all available topics to the type of data their events can carry. For topics whose events do not hold any data, the void type can be used.

interface Events {
  "🕳️": void;
  "🚏": { name: string };
  "🚇": { line: string } | void;
}

const emitter = new Announcer<Events>();

emitter.emit("🕳️", "Mind the gap");
// ✗: Expected 1 argument, but got 2.

emitter.emit("🚏", "Charing Cross");
// ✗: Argument of type 'string' is not assignable to parameter.

emitter.on("🚇", data => console.log(`This is a ${data.line} train`));
// ✗: Object is possibly 'undefined'.

emitter.on("🚏", data => console.log(`The next station is ${data.name}`));
// ✓

API

Classes

Announcer

A class that is responsible for transmitting events.

It has the following instance methods:

• on

  Parameters:
    topic: string | symbol
    handler: function

  Returns: Listener

  Creates a new listener that waits for events of the specified topic to occur, intercepts them, and invokes the given handler function. If the event holds additional data, it will be provided as an argument when the handler function is called.

• once

  Parameters:
    topic: string | symbol

  Returns: OneTimeListener

  Creates a new one-time listener in the form of a promise, which is resolved as soon as an event of the specified topic occurs. If the event holds additional data, it is provided as the resolved value.

• emit

  Parameters:
    topic: string | symbol
    data?: any

  Returns: boolean

  Triggers a new event for the specified topic, optionally with some data, notifying its subscribers.

  The return value indicates whether there were active subscriptions for the specified topic.

• count

  Parameters:
    topic: string | symbol

  Returns: boolean

  Returns the number of active subscriptions for the specified topic.

• clear

  Parameters:
    topic: string | symbol

  Returns: boolean

  Removes all subscriptions for the specified topic.

  The return value indicates whether there were active subscriptions for the specified topic.

Structures

Listener

An object that waits for events of a given topic to occur, intercepts them, and notifies its subscriber by calling a predefined handler function. If the event holds additional data, it will be provided as an argument when the handler function is called.

It has the following methods:

• cancel

  Parameters: ✗
  Returns: boolean

  Disposes the listener by canceling the corresponding subscription and removing the associated resources from the emitter. Subsequent method calls will have no effect.

  Call this method whenever a listener is no longer used in your application in order to prevent memory leaks. To completely free it from memory, remove all references to it.

  The return value indicates whether the state of the listener was affected by the method call.

OneTimeListener

A promise that is resolved as soon as an event related to a specific topic occurs. If the event holds additional data, it is provided as the resolved value.

All methods of the built-in promise object can be used, with the addition of the following:

• cancel

  Parameters: ✗
  Returns: boolean

  Cancels the promise by immediately rejecting it and removing the associated resources from the emitter. Subsequent method calls will have no effect.

  The return value indicates whether the state of the promise was affected by the method call.

FAQ

Is Announcer comptaible with Node's event module?

No. While the core concept is the same, Announcer provides a fundamentally different interface that focuses on being concise rather than implementing Node's cluttered and outdated API surface.

Does Announcer support multiple data arguments?

No. However, you can use deconstruction to accomplish the same thing.

emitter.on("🚇", ([line, terminal]) => {
  console.log(`This is a ${line} line train to ${terminal}`);
});

emitter.emit("🚇", ["District", "Upminster"]);