Notify Reference

Coverage License NPM Version Open Issues

📣 Minimalistic Pub/Sub implementation.

Usage

📦 Node

Install @lou.codes/notify as a dependency:

1
pnpm add @lou.codes/notify
2
# or
3
npm install @lou.codes/notify
4
# or
5
yarn add @lou.codes/notify

Import it and use it:

1
import { broadcast } from "@lou.codes/notify";
2

3
const { emit, on } = broadcast<{ event: string }>();
4

5
const onEvent = on("event");
6
const offEvent = onEvent(console.log);
7

8
const emitEvent = emit("event");
9
emitEvent("Hello world 1"); // Logs "Hello world 1"
10
emitEvent("Hello world 2"); // Logs "Hello world 2"
11
offEvent();
12
emitEvent("Nope"); // Nothing happens

🦕 Deno

Import @lou.codes/notify using the npm: prefix, and use it directly:

1
import { broadcast } from "npm:@lou.codes/notify";
2

3
const { emit, on } = broadcast<{ event: string }>();
4

5
const onEvent = on("event");
6
const offEvent = onEvent(console.log);
7

8
const emitEvent = emit("event");
9
emitEvent("Hello world 1"); // Logs "Hello world 1"
10
emitEvent("Hello world 2"); // Logs "Hello world 2"
11
offEvent();
12
emitEvent("Nope"); // Nothing happens

🌎 Browser

Import @lou.codes/notify using esm.sh, and use it directly:

1
<script type="module">
2
	import { broadcast } from "https://esm.sh/@lou.codes/notify";
3

4
	const { emit, on } = broadcast();
5

6
	const onEvent = on("event");
7
	const offEvent = onEvent(console.log);
8

9
	const emitEvent = emit("event");
10
	emitEvent("Hello world 1"); // Logs "Hello world 1"
11
	emitEvent("Hello world 2"); // Logs "Hello world 2"
12
	offEvent();
13
	emitEvent("Nope"); // Nothing happens
14
</script>

Useful links

📝 Documentation: TypeDoc generated documentation.
⏳ Changelog: List of changes between versions.
✅ Tests Coverage: Coveralls page with tests coverage.

Type Aliases

Emitter<Data>

1
type Emitter<Data>: Single<Data> extends Single<never> ? () => void : Unary<Data, void>;

Emitter function (when data is never it doesn’t take any arguments).

Type parameters

Type parameter	Description
`Data`	Data type.

View source

EventListener<Data>

1
type EventListener<Data>: Single<Data> extends Single<never> ? () => void : Unary<Data, void>;

Event listener unary function.

See

Unary

Type parameters

Type parameter	Description
`Data`	Data type.

View source

EventRegistry<Events>

1
type EventRegistry<Events>: { readonly [Event in keyof Events]?: ReadOnlyArray<EventListener<Readonly<Events[Event]>>> };

Registry of event names to array of listeners.

Example

1
const eventRegistry = {
2
	example: [() => console.log("example called")],
3
};

Type parameters

Type parameter	Description
`Events` extends `EventTypeDictionary`	Event registry.

View source

EventTypeDictionary

1
type EventTypeDictionary: ReadOnlyRecord<string>;

Dictionary of event name to event types.

Example

1
const example = {
2
	eventName: TypeOfEvent,
3
} satisfies EventTypeDictionary;

See

ReadOnlyRecord

View source

Functions

broadcast()

1
function broadcast<Events>(eventRegistry: EventRegistry<Events>): object;

Creates a new “broadcast” object, which has emit and on with a shared eventRegistry.

Type parameters

Type parameter	Description
`Events` extends `Readonly`<`Record`<`string`, `unknown`>>	Event registry.

Parameters

Parameter	Type	Description
`eventRegistry`	`EventRegistry`<`Events`>	Optional record of event names mapped to an array of listeners.

Returns

object

Object with emit and on functions.

Member	Type	Value
`emit`	<`Event`>(`event`: `Event`) => `Emitter`<`Events`[`Event`]>	…
`on`	<`Event`>(`event`: `Event`) => (`listener`: `EventListener`<`Events`[`Event`]>) => () => `undefined`	…

Example

1
const { emit, on } = broadcast<{ event: string }>();
2
const off = on("event")(console.log);
3
emit("event")("Hello world"); // Logs "Hello world"
4
off();
5
emit("event")("Nope"); // Nothing happens

View source

emit()

1
function emit<Events>(
2
	eventRegistry: EventRegistry<Events>,
3
): <Event>(event: Event) => Emitter<Events[Event]>;

Creates a curried function to emit events for listeners of the given eventRegistry.

Type parameters

Type parameter	Description
`Events` extends `Readonly`<`Record`<`string`, `unknown`>>	Event registry.

Parameters

Parameter	Type	Description
`eventRegistry`	`EventRegistry`<`Events`>	Record of event names mapped to an array of listeners.

Returns

Function

Curried function with eventRegistry in context.

Creates a curried function to emit an event of the eventRegistry in context.

Type parameters

Type parameter	Description
`Event` extends `string` \| `number` \| `symbol`	Event name.

Parameters

Parameter	Type	Description
`event`	`Event`	Event name (has to be a valid key of the `eventRegistry`).

Returns

Emitter<Events[Event]>

Curried function with eventRegistry and event in context.

Example

1
const eventRegistry = {};
2
const emitRegistry = emit(eventRegistry);
3
const emitEvent = emitRegistry("event"); // 👈🏻 You are here
4
emitEvent("data");

Example

1
const eventRegistry = {};
2
const emitRegistry = emit(eventRegistry); // 👈🏻 You are here
3
const emitEvent = emitRegistry("event");
4
emitEvent("data");

View source

on()

1
function on<Events>(
2
	eventRegistry: EventRegistry<Events>,
3
): <Event>(
4
	event: Event,
5
) => (listener: EventListener<Events[Event]>) => () => undefined;

Creates a curried function to listen for calls to an event in the passed eventRegistry.

Type parameters

Type parameter	Description
`Events` extends `Readonly`<`Record`<`string`, `unknown`>>	Event registry.

Parameters

Parameter	Type	Description
`eventRegistry`	`EventRegistry`<`Events`>	Record of event names mapped to an array of listeners.

Returns

Function

Curried function with eventRegistry in context.

Creates a curried function to listen for calls to an event of the eventRegistry in context.

Type parameters

Type parameter	Description
`Event` extends `string` \| `number` \| `symbol`	Event name.

Parameters

Parameter	Type	Description
`event`	`Event`	Event name (has to be a valid key of the `eventRegistry`).

Returns

Function

Curried function with eventRegistry and event in context.

Listens for calls of the event in context of the eventRegistry in context.

Parameters

Parameter	Type	Description
`listener`	`EventListener`<`Events`[`Event`]>	Listener to be called when the `event` is emitted.

Returns

Function

Function to remove the listener from the eventRegistry.

Returns

undefined

Example

1
const eventRegistry = {};
2
const onRegistry = on(eventRegistry);
3
const onEvent = onRegistry("event");
4
const offEvent = onEvent(() => console.log("event called")); // 👈🏻 You are here
5
emit(eventRegistry)("event")(); // Logs "event called"
6
offEvent();
7
emit(eventRegistry)("event")(); // Nothing happens

Example

1
const eventRegistry = {};
2
const onRegistry = on(eventRegistry);
3
const onEvent = onRegistry("event"); // 👈🏻 You are here
4
const offEvent = onEvent(() => console.log("event called"));
5
emit(eventRegistry)("event")(); // Logs "event called"
6
offEvent();
7
emit(eventRegistry)("event")(); // Nothing happens

Example

1
const eventRegistry = {};
2
const onRegistry = on(eventRegistry); // 👈🏻 You are here
3
const onEvent = onRegistry("event");
4
const offEvent = onEvent(() => console.log("event called"));
5
emit(eventRegistry)("event")(); // Logs "event called"
6
offEvent();
7
emit(eventRegistry)("event")(); // Nothing happens

View source