promise-sequencer

PromiseSequencer is a utility class that enables you to execute promises sequentially with concurrency and retry capabilities. It empowers you to manage promise execution order, concurrency, and handles retries and logging seamlessly.

Installation

Install PromiseSequencer using your preferred package manager:

1# Using npm
2npm install @triyanox/async-sequence
3
4# Using Bun
5bun add @triyanox/async-sequence
6
7# Using Yarn
8yarn add @triyanox/async-sequence
9
10# Using PNPM
11pnpm add @triyanox/async-sequence
12

Usage

1import createPromiseSequencer from '@triyanox/async-sequence';
2
3// Example usage
4const promiseSequencer = createPromiseSequencer(
5  // add your promises here
6  [() => Promise.resolve('foo'), () => Promise.reject('bar')],
7  {
8    // the maximum number of promises that can run at the same time
9    concurrency: 2,
10    // the maximum number of times a task can be retried
11    retryAttempts: 3,
12    // the delay between retries
13    retryDelay: 1000,
14    // a logger that logs the status of the PromiseSequencer
15    logger: {
16      log: (level, message) => {
17        console.log(`[${level.toUpperCase()}] ${message}`);
18      },
19    },
20    // callbacks for when a task is completed, failed or retried
21    onTaskCompleted: (result) => {
22      console.log(`Task completed with result: ${result()}`);
23    },
24    onTaskFailed: (error) => {
25      console.log(`Task failed with error: ${error()}`);
26    },
27    onTaskRetried: (task) => {
28      console.log(`Task retried: ${task}`);
29    },
30    // whether to disable logs
31    disableLogs: false,
32  },
33);
34
35// use a custom generator
36const promiseSequencer = createPromiseSequencer(
37  (function* custom() {
38    yield () => Promise.resolve('foo');
39    yield () => Promise.resolve('bar');
40    yield () => Promise.reject(new Error('baz'));
41  })(),
42);
43
44// start the PromiseSequencer
45promiseSequencer.start();
46
47// get the sequencer results
48const results = await promiseSequencer.getResults();
49
50// stop the PromiseSequencer
51promiseSequencer.stop();

API

Enum: LogLevel

Represents different log levels for logging messages.

• ERROR: Error log level.
• INFO: Information log level.
• DEBUG: Debug log level.

Interface: Logger

A logger interface to implement custom logging behavior.

• log(level: LogLevel, message: string): void: Logs a message at the specified log level.

Interface: PromiseSequencerOptions<T>

Options for configuring the PromiseSequencer.

• promiseGenerator: A generator that yields promises.
• concurrency (optional): The number of promises to run concurrently. Default: 1.
• retryAttempts (optional): The number of times to retry a failed task. Default: 0.
• retryDelay (optional): The delay in milliseconds between retries. Default: 0.
• logger (optional): A logger instance for custom logging. Default: console.
• disableLogs (optional): Whether to disable logging. Default: false.
• onTaskCompleted (optional): A callback for task completion.
• onTaskFailed (optional): A callback for task failure.
• onTaskRetried (optional): A callback for task retries.
• throwOnErrors (optional): Whether to throw an error when a task fails. Default: false.

Class: PromiseSequencer<T>

A class for executing promises sequentially with concurrency and retry capabilities.

• constructor(options: PromiseSequencerOptions<T>): Creates a new PromiseSequencer instance.
• start(): Promise<boolean>: Starts executing promises.
• stop(): Stops the PromiseSequencer.
• getQueue(): (() => Promise<T>)[]: Returns the current queue of tasks.
• getRunningTasks(): (() => Promise<T>)[]: Returns the current running tasks.
• getCompletedTasks(): (() => Promise<T>)[]: Returns the completed tasks.
• getFailedTasks(): (() => Promise<T>)[]: Returns the failed tasks.
• getRetryTasks(): (() => Promise<T>)[]: Returns the tasks that are currently being retried.
• getResults(): Promise<T[]>: Returns the results of the PromiseSequencer if the throwOnErrors option is set to false it will return null for the failed tasks if not it will throw an error.
• setCurrentConcurrency(concurrency: number): void: Sets the current concurrency.

Function: createPromiseSequencer<T>

Creates a new PromiseSequencer instance.

• promiseGenerator: A generator that yields promises.
• options (optional): Options for configuring the PromiseSequencer.

License

This project is licensed under the MIT License - see the LICENSE file for details.