TaskEmitter

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

Import

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 result in only the first registration being effective; subsequent attempts will be 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 from .emit.

Return Value

None.

Example

The following example captures the “log” event and prints the values passed to the emitter 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 event listeners registered for the specified event name will be 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 will be removed.

Return Value

None.

.once() instance method

.once is similar to .on, but it only captures the event once. Instead of a callback function, it receives the value via the returned StatefulPromise.

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

Example

The following example captures the “log” event only once and prints the values passed to the emitter 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 (array) of .emit.

.emit() instance method

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

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

Arguments

event

The name of the event to send the values to.

args

The values to send to the event listener.

Return Value

Returns undefined if no event listeners are present. If event listeners exist, it returns an array of StatefulPromises that wait until they resolve/reject. Normally, there’s no need to handle this StatefulPromise; use it when you need to wait for side effects triggered by the event within the current context, or if you are interested in the resolution/rejection of the event listeners.

.idle() instance method

.idle is a function that waits for all currently running event listeners to complete.

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 abort.

Return Value

None.