retry-promise-handler

About

retry-promise-handler is a package designed to facilitate retrying promises with various backoff strategies. It provides flexibility in configuring the number of retries, backoff strategies, and callbacks for success and failure.

Getting Started

Install with npm: npm install retry-promise-handler

Then you can import it with:

import { RetryPromiseHandler } from "retry-promise-handler";

const promise = () => Promise.resolve("Promise fulfilled");
const pHandler = new RetryPromiseHandler(promise, {
  retries: 3,
  backOff: "CUSTOM",
  backOffAmount: [500, 500, 1000],
});

To initiate the retry process, simply call pHandler.start() after configuring the RetryPromiseHandler.

pHandler.start();

Depending on your use case, you can manually stop the retry process if needed. If you choose to stop the retry process manually, you can call

pHandler.stop();

Configuration Options

retry-promise-handler offers two types of configurations: default and custom.

Default configuration

The default configuration provides a simpler approach to retrying promises. It allows you to specify the number of retries, the backoff strategy, and optional callback functions for different events.

export type DefaultBackOffConfiguration<T, R extends number> = {
  retries?: R | "INFINITE";
  backOff?: "FIXED" | "LINEAR" | "EXPONENTIAL";
  backOffAmount?: number;
  onSuccess?: (result: T) => void;
  onFailedRetry?: (error: RetryError) => void;
  onFailedRetryProcess?: (error: FinalError) => void;
  shouldRetryOnCondition?: (error: RetryError) => boolean;
};

• retries: specifies the number of retries or "INFINITE" for unlimited retries.
• backOff: defines the backoff strategy, which can be "FIXED", "LINEAR", or "EXPONENTIAL".
• backOffAmount: Specifies the amount of time to wait between retries.
• onSuccess: optional callback function executed upon successful promise fulfillment.
• onFailedRetry: optional callback function executed when a retry fails.
• onFailedRetryProcess: optional callback function executed when all retries fail.
• shouldRetryOnCondition: optional function that determines whether to retry. It should return a boolean value, indicating whether or not to retry, based on any relevant condition.

Custom configuration

The custom configuration allows for more fine-grained control over retry behavior. It specifies the exact number of retries and requires an array of custom backoff times, where each element in the array represents the amount of time to wait before each retry.

export type CustomBackOffConfiguration<T, R extends number> = {
  retries: R;
  backOff: "CUSTOM";
  backOffAmount: ArrayOfLength<R, number>;
  onSuccess?: (result: T) => void;
  onFailedRetry?: (error: RetryError) => void;
  onFailedRetryProcess?: (error: FinalError) => void;
  shouldRetryOnCondition?: (error: RetryError) => boolean;
};

• retries: specifies the exact number of retries.
• backOff: indicates the use of a custom backoff strategy, which is set to "CUSTOM".
• backOffAmount: Requires an array of length R containing custom backoff times. Each element in the array represents the amount of time to wait before retrying.
• onSuccess, onFailedRetry, onFailedRetryProcess, shouldRetryOnCondition: Optional callbacks, same as in the default configuration.

Error handling helpers

The package offers utility functions to identify custom errors, facilitating the distinction of error scenarios when the retry process fails:

• isErrorAllRetriesFailedError
• isErrorExitConditionMetError
• isErrorRetryManuallyStoppedError

Contributing

Whether you want to report a bug, request a feature or submit a pull request, your contribution is greatly appreciated.

Don't forget to show your support by giving the project a star!

License

Distributed under the MIT License. See LICENSE for more information.