AwaitQueue

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

Installation

$ npm install awaitqueue

Usage

In ES6:

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

In CommonJS:

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

Types

`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

`new AwaitQueue()`

Creates an AwaitQueue instance.

`awaitQueue.size: number`

Number of enqueued pending tasks.

`async awaitQueue.push(task: AwaitQueueTask<T>, name?: string): Promise<T>`

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

@param task: Asynchronous or asynchronous function.
@param name: Optional task name (useful for awaitQueue.dump() method).

`awaitQueue.stop(): void`

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

`awaitQueue.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.

`awaitQueue.dump(): AwaitQueueTaskDump[]`

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

Usage example

See test.ts file.

Author

Iñaki Baz Castillo [website|github]

License

ISC

versatica / awaitqueue