AwaitQueue

TypeScript utility to enqueue asynchronous tasks and run them sequentially one after another. For Node.js and the browser.

Installation

npm install awaitqueue

Usage

In ESM:

import {
	AwaitQueue,
	AwaitQueuePushOptions,
	AwaitQueueTask,
	AwaitQueueTaskDump,
	AwaitQueueStoppedError,
	AwaitQueueRemovedTaskError,
} from 'awaitqueue';

Using CommonJS:

const {
	AwaitQueue,
	AwaitQueuePushOptions,
	AwaitQueueTask,
	AwaitQueueTaskDump,
	AwaitQueueStoppedError,
	AwaitQueueRemovedTaskError,
} = require('awaitqueue');

Types

type AwaitQueuePushOptions

export type AwaitQueuePushOptions = {
	removeOngoingTasksWithSameName?: boolean;
};

Options given to awaitQueue.push().

• removeOngoingTasksWithSameName: If true, all previously enqueued tasks with same name will be removed and will reject with an instance of AwaitQueueRemovedTaskError.

type AwaitQueueTask

type AwaitQueueTask<T> = () => T | PromiseLike<T>;

TypeScript type representing a function that returns a value T or a Promise that resolves with T.

type AwaitQueueTaskDump

type AwaitQueueTaskDump = {
	idx: number;
	task: AwaitQueueTask<unknown>;
	name?: string;
	enqueuedTime: number;
	executionTime: number;
};

TypeScript type representing an item in the array returned by the awaitQueue.dump() method.

• idx: Index of the pending task in the queue (0 means the task being processed now).
• task: The function to be executed.
• name: The name of the given function (if any) or the name argument given to awaitQueue.push() method (if any).
• enqueuedTime: Time in milliseconds since the task was enqueued, this is, since awaitQueue.push() was called until its execution started or until now if not yet started.
• executionTime: Time in milliseconds since the task execution started (or 0 if not yet started).

API

Class AwaitQueue

const awaitQueue = new AwaitQueue();

Getter awaitQueue.size

size: number;

Number of enqueued pending tasks in the queue (including the running one if any).

Method awaitQueue.push()

async push<T>(task: AwaitQueueTask<T>, name?: string, options?: AwaitQueuePushOptions): Promise<T>

Accepts a task as argument and enqueues it after pending tasks. Once processed, the push() method resolves (or rejects) with the result (or error) returned by the given task.

• @param task: Asynchronous or asynchronous function.
• @param name: Optional task name.
• @param.options: Options.

Method awaitQueue.stop()

stop(): void

Makes all pending tasks reject with an instance of AwaitQueueStoppedError. The AwaitQueue instance is still usable for future tasks added via push() method.

Method awaitQueue.remove()

remove(taskIdx: number): void

Removes the pending task with given index. The task is rejected with an instance of AwaitQueueRemovedTaskError.

• @param taskIdx: Index of the pending task to be removed.

Method awaitQueue.dump()

dump(): AwaitQueueTaskDump[]

Returns an array with information about pending tasks in the queue. See the AwaitQueueTaskDump type above.

Class AwaitQueueStoppedError

Custom Error derived class used to reject pending tasks once awaitQueue.stop() method has been called.

Class AwaitQueueRemovedTaskError

Custom Error derived class used to reject pending tasks once awaitQueue.remove() method has been called.

Usage examples

See the unit tests.

Author

• Iñaki Baz Castillo [website|github]

License

ISC