@infra-blocks/retry 0.1.0-alpha.0

package/README.md

@@ -0,0 +1,7 @@
+# ts-retry
+[![Build](https://github.com/infra-blocks/ts-retry/actions/workflows/build.yml/badge.svg)](https://github.com/infra-blocks/ts-retry/actions/workflows/build.yml)
+[![Release](https://github.com/infra-blocks/ts-retry/actions/workflows/release.yml/badge.svg)](https://github.com/infra-blocks/ts-retry/actions/workflows/release.yml)
+[![Update From Template](https://github.com/infra-blocks/ts-retry/actions/workflows/update-from-template.yml/badge.svg)](https://github.com/infra-blocks/ts-retry/actions/workflows/update-from-template.yml)
+
+This repository exports generic retry utilities. The main function returns a `PromiseLike` object that also has a small `Emitter` API, allowing client code to
+be notified every time their function is attempted.

package/lib/cjs/index.d.ts

@@ -0,0 +1,84 @@
+import { EmitterLike, Predicate } from "@infra-blocks/types";
+/**
+ * Default retry configuration.
+ *
+ * The default configuration retries 60 times, with a factor of 1 and a minimum interval of 1000ms.
+ * The maximum interval is set to Infinity, meaning that there is no upper bound on the wait time.
+ *
+ * When no field is overridden, this config will result in retrying the function every second
+ * for a minute. Note that retries don't include the first attempt, so the inner function is
+ * called 61 times in total.
+ */
+export declare const DEFAULT_RETRY_CONFIG: Required<RetryConfig<unknown>>;
+/**
+ * Configuration for the retry function.
+ */
+export interface RetryConfig<E = Error> {
+    /**
+     * The amount of retries that will be attempted. Note that the first attempt
+     * doest not count as a retry. In total, the amount of retries plus one
+     * attempts will be made, in the worst case scenario.
+     */
+    retries?: number;
+    /**
+     * The exponential backoff factor that will be used between retries.
+     * The actual wait time can be calculated as such:
+     * wait time = min((factor ^ retry) * minIntervalMs, maxIntervalMs)
+     */
+    factor?: number;
+    /**
+     * The minimum wait time, in milliseconds, before the first retry.
+     * When the factor is 1, the wait time between retries is constant and
+     * equal to this value.
+     */
+    minIntervalMs?: number;
+    /**
+     * The maximum wait time between retries can be bound using this option.
+     */
+    maxIntervalMs?: number;
+    /**
+     * A predicate used to determine if an error should warrant a retry or not.
+     *
+     * When the function returns true, a retry will be attempted. When it returns
+     * false, the process immediately fails and throws the error.
+     *
+     * @param err - The error received from the inner function.
+     * @returns True if the function should be retried, false otherwise.
+     */
+    isRetryableError?: Predicate<E>;
+}
+/**
+ * Events and their handler types for the {@link Retry}.
+ */
+export type RetryEvents<E = Error> = {
+    /**
+     * This event is emitted at the beginning of every attempt.
+     *
+     * @param attempt - The attempt number. Starts with 1, and the first attempt does not count as a retry.
+     */
+    attempt: (params: {
+        attempt: number;
+        retryConfig: Required<RetryConfig<E>>;
+    }) => void;
+};
+/**
+ * Type returned by the {@link retry} function.
+ *
+ * This type is both a promise and an event emitter, where the events are described as in
+ * {@link RetryEvents}.
+ */
+export interface Retry<T, E = Error> extends EmitterLike<RetryEvents<E>>, PromiseLike<T> {
+}
+/**
+ * The type of the inner function that is wrapped by the {@link retry} function.
+ */
+export type RetryFunction<R> = () => Promise<R>;
+/**
+ * Returns a {@link Retry} object that wraps the provided function.
+ *
+ * @param fn - The inner function that will be retried.
+ * @param options - The configuration for the retry process, such as defined in {@link RetryConfig}.
+ *
+ * @returns A {@link Retry} that is configured with the provided arguments.
+ */
+export declare function retry<T, E = Error>(fn: RetryFunction<T>, options?: RetryConfig<E>): Retry<T, E>;

package/lib/cjs/index.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.retry = exports.DEFAULT_RETRY_CONFIG = void 0;
+const promiseRetry = require("promise-retry");
+const types_1 = require("@infra-blocks/types");
+/**
+ * Default retry configuration.
+ *
+ * The default configuration retries 60 times, with a factor of 1 and a minimum interval of 1000ms.
+ * The maximum interval is set to Infinity, meaning that there is no upper bound on the wait time.
+ *
+ * When no field is overridden, this config will result in retrying the function every second
+ * for a minute. Note that retries don't include the first attempt, so the inner function is
+ * called 61 times in total.
+ */
+exports.DEFAULT_RETRY_CONFIG = {
+    retries: 60,
+    factor: 1,
+    minIntervalMs: 1000,
+    maxIntervalMs: Infinity,
+    isRetryableError: () => true,
+};
+class RetryImpl extends types_1.EmitterLikeBase {
+    promise;
+    retryConfig;
+    constructor(fn, options) {
+        super();
+        this.retryConfig = { ...exports.DEFAULT_RETRY_CONFIG, ...options };
+        const wrapper = (attempt) => {
+            this.emit("attempt", {
+                attempt,
+                retryConfig: { ...this.retryConfig },
+            });
+            return fn();
+        };
+        this.promise = retryPromise(wrapper, this.retryConfig);
+    }
+    then(onfulfilled, onrejected) {
+        return this.promise.then(onfulfilled, onrejected);
+    }
+}
+/**
+ * Returns a {@link Retry} object that wraps the provided function.
+ *
+ * @param fn - The inner function that will be retried.
+ * @param options - The configuration for the retry process, such as defined in {@link RetryConfig}.
+ *
+ * @returns A {@link Retry} that is configured with the provided arguments.
+ */
+function retry(fn, options) {
+    return new RetryImpl(fn, options);
+}
+exports.retry = retry;
+/**
+ * The wraps a function into a retry promise.
+ *
+ * The promise resolves when the function resolves, or when the retry configuration determines so.
+ * The promise will reject is the inner function throws an error that is not retryable, or
+ * if the maximum amount of retries has been reached.
+ *
+ * @param fn - The inner function that will be retried.
+ * @param options - The retry configuration, such as defined in {@link RetryConfig}.
+ *
+ * @returns A promise wrapping the inner function with retry logic.
+ */
+async function retryPromise(fn, options) {
+    const { retries, factor, minIntervalMs, maxIntervalMs, isRetryableError } = {
+        ...exports.DEFAULT_RETRY_CONFIG,
+        ...options,
+    };
+    return await promiseRetry({ retries, factor, minTimeout: minIntervalMs, maxTimeout: maxIntervalMs }, async (retryInner, attempt) => {
+        try {
+            return await fn(attempt);
+        }
+        catch (err) {
+            if (isRetryableError(err)) {
+                return retryInner(err);
+            }
+            throw err;
+        }
+    });
+}
+//# sourceMappingURL=index.js.map

package/lib/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAAA,8CAA+C;AAC/C,+CAA8E;AAE9E;;;;;;;;;GASG;AACU,QAAA,oBAAoB,GAAmC;IAClE,OAAO,EAAE,EAAE;IACX,MAAM,EAAE,CAAC;IACT,aAAa,EAAE,IAAI;IACnB,aAAa,EAAE,QAAQ;IACvB,gBAAgB,EAAE,GAAY,EAAE,CAAC,IAAI;CACtC,CAAC;AAsEF,MAAM,SACJ,SAAQ,uBAA+B;IAGpB,OAAO,CAAiB;IACxB,WAAW,CAA2B;IAEzD,YAAY,EAAoB,EAAE,OAAwB;QACxD,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,WAAW,GAAG,EAAE,GAAG,4BAAoB,EAAE,GAAG,OAAO,EAAE,CAAC;QAE3D,MAAM,OAAO,GAAG,CAAC,OAAe,EAAE,EAAE;YAClC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE;gBACnB,OAAO;gBACP,WAAW,EAAE,EAAE,GAAG,IAAI,CAAC,WAAW,EAAE;aACrC,CAAC,CAAC;YACH,OAAO,EAAE,EAAE,CAAC;QACd,CAAC,CAAC;QACF,IAAI,CAAC,OAAO,GAAG,YAAY,CAAC,OAAO,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IACzD,CAAC;IAED,IAAI,CACF,WAGQ,EACR,UAGQ;QAER,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC;IACpD,CAAC;CACF;AAED;;;;;;;GAOG;AACH,SAAgB,KAAK,CACnB,EAAoB,EACpB,OAAwB;IAExB,OAAO,IAAI,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;AACpC,CAAC;AALD,sBAKC;AAED;;;;;;;;;;;GAWG;AACH,KAAK,UAAU,YAAY,CACzB,EAAmC,EACnC,OAAwB;IAExB,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,aAAa,EAAE,gBAAgB,EAAE,GAAG;QAC1E,GAAG,4BAAoB;QACvB,GAAG,OAAO;KACX,CAAC;IAEF,OAAO,MAAM,YAAY,CACvB,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,aAAa,EAAE,EACzE,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,EAAE;QAC5B,IAAI;YACF,OAAO,MAAM,EAAE,CAAC,OAAO,CAAC,CAAC;SAC1B;QAAC,OAAO,GAAG,EAAE;YACZ,IAAI,gBAAgB,CAAC,GAAQ,CAAC,EAAE;gBAC9B,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC;aACxB;YACD,MAAM,GAAG,CAAC;SACX;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/lib/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/lib/esm/index.d.ts

@@ -0,0 +1,84 @@
+import { EmitterLike, Predicate } from "@infra-blocks/types";
+/**
+ * Default retry configuration.
+ *
+ * The default configuration retries 60 times, with a factor of 1 and a minimum interval of 1000ms.
+ * The maximum interval is set to Infinity, meaning that there is no upper bound on the wait time.
+ *
+ * When no field is overridden, this config will result in retrying the function every second
+ * for a minute. Note that retries don't include the first attempt, so the inner function is
+ * called 61 times in total.
+ */
+export declare const DEFAULT_RETRY_CONFIG: Required<RetryConfig<unknown>>;
+/**
+ * Configuration for the retry function.
+ */
+export interface RetryConfig<E = Error> {
+    /**
+     * The amount of retries that will be attempted. Note that the first attempt
+     * doest not count as a retry. In total, the amount of retries plus one
+     * attempts will be made, in the worst case scenario.
+     */
+    retries?: number;
+    /**
+     * The exponential backoff factor that will be used between retries.
+     * The actual wait time can be calculated as such:
+     * wait time = min((factor ^ retry) * minIntervalMs, maxIntervalMs)
+     */
+    factor?: number;
+    /**
+     * The minimum wait time, in milliseconds, before the first retry.
+     * When the factor is 1, the wait time between retries is constant and
+     * equal to this value.
+     */
+    minIntervalMs?: number;
+    /**
+     * The maximum wait time between retries can be bound using this option.
+     */
+    maxIntervalMs?: number;
+    /**
+     * A predicate used to determine if an error should warrant a retry or not.
+     *
+     * When the function returns true, a retry will be attempted. When it returns
+     * false, the process immediately fails and throws the error.
+     *
+     * @param err - The error received from the inner function.
+     * @returns True if the function should be retried, false otherwise.
+     */
+    isRetryableError?: Predicate<E>;
+}
+/**
+ * Events and their handler types for the {@link Retry}.
+ */
+export type RetryEvents<E = Error> = {
+    /**
+     * This event is emitted at the beginning of every attempt.
+     *
+     * @param attempt - The attempt number. Starts with 1, and the first attempt does not count as a retry.
+     */
+    attempt: (params: {
+        attempt: number;
+        retryConfig: Required<RetryConfig<E>>;
+    }) => void;
+};
+/**
+ * Type returned by the {@link retry} function.
+ *
+ * This type is both a promise and an event emitter, where the events are described as in
+ * {@link RetryEvents}.
+ */
+export interface Retry<T, E = Error> extends EmitterLike<RetryEvents<E>>, PromiseLike<T> {
+}
+/**
+ * The type of the inner function that is wrapped by the {@link retry} function.
+ */
+export type RetryFunction<R> = () => Promise<R>;
+/**
+ * Returns a {@link Retry} object that wraps the provided function.
+ *
+ * @param fn - The inner function that will be retried.
+ * @param options - The configuration for the retry process, such as defined in {@link RetryConfig}.
+ *
+ * @returns A {@link Retry} that is configured with the provided arguments.
+ */
+export declare function retry<T, E = Error>(fn: RetryFunction<T>, options?: RetryConfig<E>): Retry<T, E>;

package/lib/esm/index.js

@@ -0,0 +1,81 @@
+import { createRequire as _createRequire } from "module";
+const __require = _createRequire(import.meta.url);
+const promiseRetry = __require("promise-retry");
+import { EmitterLikeBase } from "@infra-blocks/types";
+/**
+ * Default retry configuration.
+ *
+ * The default configuration retries 60 times, with a factor of 1 and a minimum interval of 1000ms.
+ * The maximum interval is set to Infinity, meaning that there is no upper bound on the wait time.
+ *
+ * When no field is overridden, this config will result in retrying the function every second
+ * for a minute. Note that retries don't include the first attempt, so the inner function is
+ * called 61 times in total.
+ */
+export const DEFAULT_RETRY_CONFIG = {
+    retries: 60,
+    factor: 1,
+    minIntervalMs: 1000,
+    maxIntervalMs: Infinity,
+    isRetryableError: () => true,
+};
+class RetryImpl extends EmitterLikeBase {
+    promise;
+    retryConfig;
+    constructor(fn, options) {
+        super();
+        this.retryConfig = { ...DEFAULT_RETRY_CONFIG, ...options };
+        const wrapper = (attempt) => {
+            this.emit("attempt", {
+                attempt,
+                retryConfig: { ...this.retryConfig },
+            });
+            return fn();
+        };
+        this.promise = retryPromise(wrapper, this.retryConfig);
+    }
+    then(onfulfilled, onrejected) {
+        return this.promise.then(onfulfilled, onrejected);
+    }
+}
+/**
+ * Returns a {@link Retry} object that wraps the provided function.
+ *
+ * @param fn - The inner function that will be retried.
+ * @param options - The configuration for the retry process, such as defined in {@link RetryConfig}.
+ *
+ * @returns A {@link Retry} that is configured with the provided arguments.
+ */
+export function retry(fn, options) {
+    return new RetryImpl(fn, options);
+}
+/**
+ * The wraps a function into a retry promise.
+ *
+ * The promise resolves when the function resolves, or when the retry configuration determines so.
+ * The promise will reject is the inner function throws an error that is not retryable, or
+ * if the maximum amount of retries has been reached.
+ *
+ * @param fn - The inner function that will be retried.
+ * @param options - The retry configuration, such as defined in {@link RetryConfig}.
+ *
+ * @returns A promise wrapping the inner function with retry logic.
+ */
+async function retryPromise(fn, options) {
+    const { retries, factor, minIntervalMs, maxIntervalMs, isRetryableError } = {
+        ...DEFAULT_RETRY_CONFIG,
+        ...options,
+    };
+    return await promiseRetry({ retries, factor, minTimeout: minIntervalMs, maxTimeout: maxIntervalMs }, async (retryInner, attempt) => {
+        try {
+            return await fn(attempt);
+        }
+        catch (err) {
+            if (isRetryableError(err)) {
+                return retryInner(err);
+            }
+            throw err;
+        }
+    });
+}
+//# sourceMappingURL=index.js.map

package/lib/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;AAAA,gDAA+C;AAC/C,OAAO,EAAe,eAAe,EAAa,MAAM,qBAAqB,CAAC;AAE9E;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAmC;IAClE,OAAO,EAAE,EAAE;IACX,MAAM,EAAE,CAAC;IACT,aAAa,EAAE,IAAI;IACnB,aAAa,EAAE,QAAQ;IACvB,gBAAgB,EAAE,GAAY,EAAE,CAAC,IAAI;CACtC,CAAC;AAsEF,MAAM,SACJ,SAAQ,eAA+B;IAGpB,OAAO,CAAiB;IACxB,WAAW,CAA2B;IAEzD,YAAY,EAAoB,EAAE,OAAwB;QACxD,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,WAAW,GAAG,EAAE,GAAG,oBAAoB,EAAE,GAAG,OAAO,EAAE,CAAC;QAE3D,MAAM,OAAO,GAAG,CAAC,OAAe,EAAE,EAAE;YAClC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE;gBACnB,OAAO;gBACP,WAAW,EAAE,EAAE,GAAG,IAAI,CAAC,WAAW,EAAE;aACrC,CAAC,CAAC;YACH,OAAO,EAAE,EAAE,CAAC;QACd,CAAC,CAAC;QACF,IAAI,CAAC,OAAO,GAAG,YAAY,CAAC,OAAO,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IACzD,CAAC;IAED,IAAI,CACF,WAGQ,EACR,UAGQ;QAER,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC;IACpD,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,KAAK,CACnB,EAAoB,EACpB,OAAwB;IAExB,OAAO,IAAI,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,KAAK,UAAU,YAAY,CACzB,EAAmC,EACnC,OAAwB;IAExB,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,aAAa,EAAE,gBAAgB,EAAE,GAAG;QAC1E,GAAG,oBAAoB;QACvB,GAAG,OAAO;KACX,CAAC;IAEF,OAAO,MAAM,YAAY,CACvB,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,aAAa,EAAE,EACzE,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,EAAE;QAC5B,IAAI;YACF,OAAO,MAAM,EAAE,CAAC,OAAO,CAAC,CAAC;SAC1B;QAAC,OAAO,GAAG,EAAE;YACZ,IAAI,gBAAgB,CAAC,GAAQ,CAAC,EAAE;gBAC9B,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC;aACxB;YACD,MAAM,GAAG,CAAC;SACX;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@infra-blocks/retry",
+  "version": "0.1.0-alpha.0",
+  "description": "This repository exports utilities for generic retry logic.",
+  "keywords": [
+    "retry",
+    "promise"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/infra-blocks/ts-retry.git"
+  },
+  "license": "ISC",
+  "author": "",
+  "type": "module",
+  "exports": {
+    "import": "./lib/esm/index.js",
+    "require": "./lib/cjs/index.js",
+    "default": "./lib/esm/index.js"
+  },
+  "files": [
+    "lib/**/*.{js,cjs,mjs,json,d.ts,map}"
+  ],
+  "scripts": {
+    "prebuild": "npm run clean",
+    "build": "tsc -b tsconfig.build.esm.json tsconfig.build.cjs.json",
+    "postbuild": "scripts/post-build.sh",
+    "clean": "rm -rf lib && rm -f infra-blocks-*.tgz",
+    "compile": "tsc",
+    "lint": "eslint --ext .js,.cjs,.mjs,.json,.ts --max-warnings 0 .",
+    "prepack": "npm run build",
+    "test": "npm run test:unit",
+    "test:coverage": "c8 npm run test",
+    "test:coverage:lcov": "c8 --reporter=lcov npm run test",
+    "test:integration": "mocha --config test/integration/.mocharc.js 'test/integration/**/*.spec.ts'",
+    "test:unit": "mocha --config test/unit/.mocharc.cjs 'test/unit/**/*.spec.ts'"
+  },
+  "dependencies": {
+    "@infra-blocks/types": "^0.6.0",
+    "promise-retry": "^2.0.1"
+  },
+  "devDependencies": {
+    "@infra-blocks/iter": "^0.2.7",
+    "@infra-blocks/test": "^0.4.0",
+    "@types/mocha": "^10.0.1",
+    "@types/node": "^20.10.3",
+    "@types/promise-retry": "^1.1.6",
+    "@types/verror": "^1.10.11",
+    "@typescript-eslint/eslint-plugin": "^5.59.8",
+    "@typescript-eslint/parser": "^5.59.8",
+    "c8": "^8.0.0",
+    "eslint": "^8.41.0",
+    "eslint-config-prettier": "^8.8.0",
+    "eslint-plugin-json-format": "^2.0.1",
+    "eslint-plugin-prettier": "^4.2.1",
+    "mocha": "^10.2.0",
+    "prettier": "^2.8.8",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.0.4",
+    "verror": "^1.10.1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}