TaskEmitter

TaskEmitter is an event emitter class for asynchronous tasks managed by TaskQueue.

Importing

import { TaskEmitter } from "@tai-kun/surrealdb/utils";

.constructor()

new TaskEmitter<T>();

Arguments

T

A type representing event names and their corresponding argument types (arrays) as key-value pairs.

Return Value

When called with new, TaskEmitter returns its instance.

.on() instance method

.on is a function that registers an event listener to the event emitter. Attempting to register the same function multiple times for the same event will only register it once; subsequent registrations are ignored.

on(event: string | number, listener: TaskListener): void;

Arguments

event

The name of the event to register the listener for.

listener

The event listener to register. This function receives the same arguments as the TaskQueue task runner, followed by a variable number of arguments passed to .emit.

Return Value

None.

Example

The following example listens for the “log” event and prints the emitted values to standard output:

import { TaskEmitter } from "@tai-kun/surrealdb/utils";

type Events = {
  log: string[];
};

const emitter = new TaskEmitter<Events>();

emitter.on("log", (_, ...args) => {
  console.log(...args);
});

emitter.emit("log", "Hello");
emitter.emit("log", "World", "!!!");

await emitter.idle();

Output:

Hello
World !!!

.off() instance method

.off is a function that removes an event listener from the event emitter. If the listener is omitted, all listeners registered for the specified event name are removed.

off(event: string | number, listener?: TaskListener): void;

Arguments

event

The name of the event to remove the listener from.

listener

The event listener to remove. If omitted, all event listeners registered for the specified event are removed.

Return Value

None.

.once() instance method

.once is similar to .on, but it listens for an event only once. It returns a StatefulPromise instead of a callback function to receive the value.

once(
  event: string | Number,
  options?: TaskListenerOptions,
): StatefulPromise<unknown[]>;

Example

The following example listens for the “log” event only once and prints the emitted values to standard output:

import { TaskEmitter } from "@tai-kun/surrealdb/utils";

type Events = {
  log: string[];
};

const emitter = new TaskEmitter<Events>();

const promise = emitter.once("log");

emitter.emit("log", "Hello");
emitter.emit("log", "World", "!!!");

const received = await promise;
console.log(received);

await emitter.idle();

Output:

[ 'Hello' ]

Arguments

event

The name of the event to wait for.

options

Options for the event listener. An abort signal can be passed.

Return Value

Returns a StatefulPromise that resolves with the arguments (an array) passed to .emit.

.emit() instance method

.emit is a function that sends a value to event listeners.

emit(
  event: string | number,
  ...args: unknown[]
): undefined | StatefulPromise<unknown>[];

Arguments

event

The name of the event to send the value to.

args

The value(s) to send to the event listener(s).

Return Value

Returns undefined if no event listeners exist. If event listeners exist, it returns an array of StatefulPromises that await resolution/rejection. Normally, you don’t need to handle this StatefulPromise; use it only when you need to wait for side effects caused by the event in the current context or are interested in the resolution/rejection of the event listeners.

.idle() instance method

.idle is a function that waits for the completion of all currently running event listeners.

idle(): StatefulPromise<void>;

Arguments

None.

Return Value

Returns a StatefulPromise that resolves with void.

.abort() instance method

.abort is a function that sends an abort signal to the signal of all event listeners.

abort(reason?: unknown): void;

Arguments

reason

The reason for the abortion.

Return Value

None.