@sv443-network/coreutils
Version:
Cross-platform, general-purpose, JavaScript core library for Node, Deno and the browser. Intended to be used in conjunction with `@sv443-network/userutils` and `@sv443-network/djsutils`, but can be used independently as well.
72 lines (71 loc) • 3.7 kB
TypeScript
/**
* @module NanoEmitter
* This module contains the NanoEmitter class, which is a tiny event emitter powered by [nanoevents](https://www.npmjs.com/package/nanoevents) - [see the documentation for more info](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#nanoemitter)
*/
import { type DefaultEvents, type Emitter, type EventsMap, type Unsubscribe } from "nanoevents";
export interface NanoEmitterOptions {
/** If set to true, allows emitting events through the public method emit() */
publicEmit: boolean;
}
/**
* Class that can be extended or instantiated by itself to create a lightweight event emitter with helper methods and a strongly typed event map.
* If extended from, you can use `this.events.emit()` to emit events, even if the `emit()` method doesn't work because `publicEmit` is not set to true in the constructor.
*/
export declare class NanoEmitter<TEvtMap extends EventsMap = DefaultEvents> {
protected readonly events: Emitter<TEvtMap>;
protected eventUnsubscribes: Unsubscribe[];
protected emitterOptions: NanoEmitterOptions;
/** Creates a new instance of NanoEmitter - a lightweight event emitter with helper methods and a strongly typed event map */
constructor(options?: Partial<NanoEmitterOptions>);
/**
* Subscribes to an event and calls the callback when it's emitted.
* @param event The event to subscribe to. Use `as "_"` in case your event names aren't thoroughly typed (like when using a template literal, e.g. \`event-${val}\` as "_")
* @returns Returns a function that can be called to unsubscribe the event listener
* @example ```ts
* const emitter = new NanoEmitter<{
* foo: (bar: string) => void;
* }>({
* publicEmit: true,
* });
*
* let i = 0;
* const unsub = emitter.on("foo", (bar) => {
* // unsubscribe after 10 events:
* if(++i === 10) unsub();
* console.log(bar);
* });
*
* emitter.emit("foo", "bar");
* ```
*/
on<TKey extends keyof TEvtMap>(event: TKey | "_", cb: TEvtMap[TKey]): () => void;
/**
* Subscribes to an event and calls the callback or resolves the Promise only once when it's emitted.
* @param event The event to subscribe to. Use `as "_"` in case your event names aren't thoroughly typed (like when using a template literal, e.g. \`event-${val}\` as "_")
* @param cb The callback to call when the event is emitted - if provided or not, the returned Promise will resolve with the event arguments
* @returns Returns a Promise that resolves with the event arguments when the event is emitted
* @example ```ts
* const emitter = new NanoEmitter<{
* foo: (bar: string) => void;
* }>();
*
* // Promise syntax:
* const [bar] = await emitter.once("foo");
* console.log(bar);
*
* // Callback syntax:
* emitter.once("foo", (bar) => console.log(bar));
* ```
*/
once<TKey extends keyof TEvtMap>(event: TKey | "_", cb?: TEvtMap[TKey]): Promise<Parameters<TEvtMap[TKey]>>;
/**
* Emits an event on this instance.
* ⚠️ Needs `publicEmit` to be set to true in the NanoEmitter constructor or super() call!
* @param event The event to emit
* @param args The arguments to pass to the event listeners
* @returns Returns true if `publicEmit` is true and the event was emitted successfully
*/
emit<TKey extends keyof TEvtMap>(event: TKey, ...args: Parameters<TEvtMap[TKey]>): boolean;
/** Unsubscribes all event listeners from this instance */
unsubscribeAll(): void;
}