@layerzerolabs/common-error-utils 0.2.8 → 0.2.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@layerzerolabs/common-error-utils",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "private": false,
   "license": "MIT",
   "type": "module",
@@ -13,11 +13,16 @@
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "dependencies": {
+    "exponential-backoff": "^3.1.1",
+    "ms": "^2.1.3"
+  },
   "devDependencies": {
+    "@types/ms": "^2.1.0",
     "tsup": "^8.4.0",
     "vitest": "^3.2.3",
-    "@layerzerolabs/tsup-configuration": "0.2.8",
-    "@layerzerolabs/typescript-configuration": "0.2.8"
+    "@layerzerolabs/tsup-configuration": "0.2.10",
+    "@layerzerolabs/typescript-configuration": "0.2.10"
   },
   "publishConfig": {
     "access": "restricted",

package/src/errors.ts

@@ -0,0 +1,145 @@
+const extractMessageFromJsonRpcError = (err: any): string => {
+    try {
+        if (typeof err.body === 'object' && err.body.message) {
+            return err.body.message;
+        }
+        const parsedBody = JSON.parse(err.body);
+        return parsedBody?.error?.message;
+    } catch {
+        return 'unknown';
+    }
+};
+
+export function convertErrorToObject(err: any): any {
+    return JSON.parse(JSON.stringify(err, Object.getOwnPropertyNames(err)));
+}
+
+export function normalizeError(err: any) {
+    const error = convertErrorToObject(err);
+    return {
+        // Normal Error properties
+        ...(error.name ? { name: error.name } : {}),
+        ...(error.message ? { message: error.message } : {}),
+        ...(error.stack ? { stack: error.stack } : {}),
+        // Rpc properties
+        ...(error.reason ? { reason: error.reason } : {}),
+        ...(error.code ? { code: error.code } : {}),
+        ...(error.event ? { event: error.event } : {}),
+        ...(error.body ? { body: extractMessageFromJsonRpcError(error) } : {}),
+    };
+}
+
+// Removes the last argument if it is an ErrorOptions
+type RemoveErrorOptions<T extends any[]> = T extends [...infer U, ErrorOptions?] ? U : never;
+
+/**
+ * Base class for all serializable errors.
+ * This class is designed to be extended by other error classes.
+ * It provides a way to wrap errors and a way to check if an error is in the stack of a specific error class.
+ * All errors that extend this class *must* have error options as the last argument in their constructor.
+ */
+export abstract class SerializableError extends Error {
+    details: string[];
+    /*
+     * The instance of the error that was wrapped, if any.
+     * Creates a linked list of error objects.
+     * Only exists if the error hasn't been serialized and deserialized.
+     */
+    cause: unknown;
+    constructor(message: string, options?: ErrorOptions) {
+        super(message, options);
+        // for some reason, we need to set the cause directly on the instance, even after calling super
+        this.cause = options?.cause;
+        this.name = this.constructor.name;
+        this.details = [this.constructor.name, 'SerializableError'];
+    }
+
+    /*
+     * Checks if the error is an instance of the current class or a subclass. Returns the error if it is.
+     * We can't type the error as more than SerializableError because it could have been serialized and deserialized,
+     * which could make it lose extra fields.
+     */
+    static inStackOf<T extends abstract new (...args: any) => any>(
+        this: T,
+        error: any,
+    ): SerializableError | undefined {
+        if (error?.details?.includes(this.name)) {
+            return error as SerializableError;
+        } else if (error?.cause?.details?.includes(this.name)) {
+            return error.cause as SerializableError;
+        }
+        return undefined;
+    }
+
+    // We could limit this to only wrap serializable errors, but that could limit the flexibility of the error system.
+    static wrap<T extends new (...args: any) => SerializableError>(
+        this: T,
+        error: any,
+        // Remove the optional error arguments
+        ...args: RemoveErrorOptions<ConstructorParameters<T>>
+    ): InstanceType<T> {
+        const wrappedError = new this(...args, { cause: error });
+
+        wrappedError.details = error?.details
+            ? [wrappedError.name, ...error.details]
+            : [wrappedError.name, 'SerializableError', error?.name ?? 'UnknownError'];
+
+        wrappedError.message = `${wrappedError.message} > ${error?.message ?? String(error)}`;
+
+        return wrappedError as InstanceType<T>;
+    }
+}
+
+export class NonRetryableError extends SerializableError {
+    constructor(message: string, options?: ErrorOptions) {
+        super(message, options);
+    }
+}
+
+export class NotFoundError extends SerializableError {
+    constructor(message?: string, options?: ErrorOptions) {
+        super(message ? `Not found: ${message}` : 'Not found', options);
+    }
+}
+
+// TODO: extend this for chain specific providers
+export class ProviderError extends SerializableError {
+    constructor(providerUri: string, options?: ErrorOptions) {
+        super(`Provider error at host '${ProviderError.parseHost(providerUri)}'`, options);
+    }
+
+    private static parseHost(providerUri: string): string {
+        try {
+            const url = new URL(providerUri);
+            return url.host;
+        } catch {
+            return 'UNKNOWN_HOST';
+        }
+    }
+}
+
+export class NonEmittableError extends SerializableError {
+    constructor(message: string, options?: ErrorOptions) {
+        super(message, options);
+        this.name = 'NonEmittableError';
+    }
+}
+
+export class QuorumNotAchievedYet extends SerializableError {
+    constructor(options?: ErrorOptions) {
+        super('The quorum was not achieved yet', options);
+    }
+}
+
+export class MultiError extends Error {
+    constructor(public readonly errs: any[]) {
+        super(errs.map((err) => err.message).join(', '));
+    }
+}
+
+export const throwError = <Err extends Error>(
+    message: string,
+    error?: (message: string) => Err,
+): never => {
+    throw error?.(message) ?? new Error(message);
+};

package/src/index.ts

@@ -1,145 +1,2 @@
-const extractMessageFromJsonRpcError = (err: any): string => {
-    try {
-        if (typeof err.body === 'object' && err.body.message) {
-            return err.body.message;
-        }
-        const parsedBody = JSON.parse(err.body);
-        return parsedBody?.error?.message;
-    } catch {
-        return 'unknown';
-    }
-};
-
-export function convertErrorToObject(err: any): any {
-    return JSON.parse(JSON.stringify(err, Object.getOwnPropertyNames(err)));
-}
-
-export function normalizeError(err: any) {
-    const error = convertErrorToObject(err);
-    return {
-        // Normal Error properties
-        ...(error.name ? { name: error.name } : {}),
-        ...(error.message ? { message: error.message } : {}),
-        ...(error.stack ? { stack: error.stack } : {}),
-        // Rpc properties
-        ...(error.reason ? { reason: error.reason } : {}),
-        ...(error.code ? { code: error.code } : {}),
-        ...(error.event ? { event: error.event } : {}),
-        ...(error.body ? { body: extractMessageFromJsonRpcError(error) } : {}),
-    };
-}
-
-// Removes the last argument if it is an ErrorOptions
-type RemoveErrorOptions<T extends any[]> = T extends [...infer U, ErrorOptions?] ? U : never;
-
-/**
- * Base class for all serializable errors.
- * This class is designed to be extended by other error classes.
- * It provides a way to wrap errors and a way to check if an error is in the stack of a specific error class.
- * All errors that extend this class *must* have error options as the last argument in their constructor.
- */
-export abstract class SerializableError extends Error {
-    details: string[];
-    /*
-     * The instance of the error that was wrapped, if any.
-     * Creates a linked list of error objects.
-     * Only exists if the error hasn't been serialized and deserialized.
-     */
-    cause: unknown;
-    constructor(message: string, options?: ErrorOptions) {
-        super(message, options);
-        // for some reason, we need to set the cause directly on the instance, even after calling super
-        this.cause = options?.cause;
-        this.name = this.constructor.name;
-        this.details = [this.constructor.name, 'SerializableError'];
-    }
-
-    /*
-     * Checks if the error is an instance of the current class or a subclass. Returns the error if it is.
-     * We can't type the error as more than SerializableError because it could have been serialized and deserialized,
-     * which could make it lose extra fields.
-     */
-    static inStackOf<T extends abstract new (...args: any) => any>(
-        this: T,
-        error: any,
-    ): SerializableError | undefined {
-        if (error?.details?.includes(this.name)) {
-            return error as SerializableError;
-        } else if (error?.cause?.details?.includes(this.name)) {
-            return error.cause as SerializableError;
-        }
-        return undefined;
-    }
-
-    // We could limit this to only wrap serializable errors, but that could limit the flexibility of the error system.
-    static wrap<T extends new (...args: any) => SerializableError>(
-        this: T,
-        error: any,
-        // Remove the optional error arguments
-        ...args: RemoveErrorOptions<ConstructorParameters<T>>
-    ): InstanceType<T> {
-        const wrappedError = new this(...args, { cause: error });
-
-        wrappedError.details = error?.details
-            ? [wrappedError.name, ...error.details]
-            : [wrappedError.name, 'SerializableError', error?.name ?? 'UnknownError'];
-
-        wrappedError.message = `${wrappedError.message} > ${error?.message ?? String(error)}`;
-
-        return wrappedError as InstanceType<T>;
-    }
-}
-
-export class NonRetryableError extends SerializableError {
-    constructor(message: string, options?: ErrorOptions) {
-        super(message, options);
-    }
-}
-
-export class NotFoundError extends SerializableError {
-    constructor(message?: string, options?: ErrorOptions) {
-        super(message ? `Not found: ${message}` : 'Not found', options);
-    }
-}
-
-// TODO: extend this for chain specific providers
-export class ProviderError extends SerializableError {
-    constructor(providerUri: string, options?: ErrorOptions) {
-        super(`Provider error at host '${ProviderError.parseHost(providerUri)}'`, options);
-    }
-
-    private static parseHost(providerUri: string): string {
-        try {
-            const url = new URL(providerUri);
-            return url.host;
-        } catch {
-            return 'UNKNOWN_HOST';
-        }
-    }
-}
-
-export class NonEmittableError extends SerializableError {
-    constructor(message: string, options?: ErrorOptions) {
-        super(message, options);
-        this.name = 'NonEmittableError';
-    }
-}
-
-export class QuorumNotAchievedYet extends SerializableError {
-    constructor(options?: ErrorOptions) {
-        super('The quorum was not achieved yet', options);
-    }
-}
-
-export class MultiError extends Error {
-    constructor(public readonly errs: any[]) {
-        super(errs.map((err) => err.message).join(', '));
-    }
-}
-
-export const throwError = <Err extends Error>(
-    message: string,
-    error?: (message: string) => Err,
-): never => {
-    throw error?.(message) ?? new Error(message);
-};
+export * from './errors';
+export * from './retry';

package/src/retry.ts

@@ -0,0 +1,101 @@
+import { backOff } from 'exponential-backoff';
+import type { StringValue } from 'ms';
+import ms from 'ms';
+
+const DEFAULT_NONRETRYABLE_ERRORS = ['NonRetryableError'];
+
+export interface RetryPolicy {
+    /**
+     * Maximum time of a single execution attempt.
+     * This timeout should be as short as the longest possible execution of the Activity body.
+     *
+     * @default 10 minutes
+     * @format {@link https://www.npmjs.com/package/ms | ms-formatted string}
+     */
+    startToCloseTimeout?: StringValue;
+
+    /**
+     * Coefficient used to calculate the next retry interval.
+     * The next retry interval is previous interval multiplied by this coefficient.
+     * @minimum 1
+     * @default 2
+     */
+    backoffCoefficient?: number;
+
+    /**
+     * Interval of the first retry.
+     * If coefficient is 1 then it is used for all retries
+     * @format {@link https://www.npmjs.com/package/ms | ms-formatted string}
+     * @default 1 second
+     */
+    initialInterval?: StringValue;
+
+    /**
+     * Maximum number of attempts. When exceeded, retries stop.
+     *
+     * @default Infinity
+     */
+    maximumAttempts?: number;
+
+    /**
+     * Maximum interval between retries.
+     * Exponential backoff leads to interval increase.
+     * This value is the cap of the increase.
+     *
+     * @default 100x of {@link initialInterval}
+     * @format {@link https://www.npmjs.com/package/ms | ms-formatted string}
+     */
+    maximumInterval?: StringValue;
+
+    /**
+     * List of application failures types to not retry.
+     */
+    nonRetryableErrorTypes?: string[];
+}
+
+/**
+ * Executes a function with a retry policy.
+ * @param fn - The function to execute.
+ * @param policy - The retry policy to apply.
+ * @param shouldRetry - A callback that determines if the error is retryable besides the nonRetryableErrorTypes.
+ * @return A promise that resolves to the result of the function or rejects with an error.
+ * @throws Error if the function fails after all retries.
+ */
+export const runWithRetryPolicy = <T = unknown>(
+    fn: () => Promise<T>,
+    policy?: RetryPolicy,
+    shouldRetry?: (err: any) => boolean,
+): Promise<T> => {
+    const perTryTimeout = ms(policy?.startToCloseTimeout ?? '10 minutes');
+    const numOfAttempts = policy?.maximumAttempts ?? Infinity;
+    const startingDelay = ms(policy?.initialInterval ?? '1s');
+    const maxDelay = policy?.maximumInterval ? ms(policy.maximumInterval) : startingDelay * 100;
+    const timeMultiple = Math.max(policy?.backoffCoefficient ?? 2, 1);
+    const nonRetryableErrorTypes = (policy?.nonRetryableErrorTypes ?? []).concat(
+        DEFAULT_NONRETRYABLE_ERRORS,
+    );
+
+    return backOff(
+        () =>
+            new Promise((resolve, reject) => {
+                fn().then(resolve).catch(reject);
+                setTimeout(() => {
+                    reject(new Error(`Execution timed out after ${perTryTimeout}ms`));
+                }, perTryTimeout);
+            }),
+        {
+            maxDelay,
+            startingDelay,
+            jitter: 'full',
+            timeMultiple,
+            numOfAttempts,
+            retry: async (error: any) => {
+                const errorType = error?.constructor?.name ?? error?.name;
+                return (
+                    !nonRetryableErrorTypes.includes(errorType) &&
+                    (shouldRetry ? shouldRetry(error) : true)
+                );
+            },
+        },
+    );
+};

package/tests/retry.test.ts

@@ -0,0 +1,110 @@
+import { backOff } from 'exponential-backoff';
+import { afterEach, describe, expect, test, vi } from 'vitest';
+
+import { runWithRetryPolicy } from '../src/retry';
+
+vi.mock('exponential-backoff', async (importOriginal) => {
+    const originalModule = await importOriginal<typeof import('exponential-backoff')>();
+    return {
+        ...originalModule,
+        backOff: vi.fn(originalModule.backOff),
+    };
+});
+
+const mockedBackOff = vi.mocked(backOff);
+
+describe('runWithRetryPolicy', () => {
+    afterEach(() => {
+        vi.clearAllMocks();
+    });
+
+    test('startToCloseTimeout', async () => {
+        const longRunningFn = () => new Promise(() => {}); // Never resolves
+
+        await expect(
+            runWithRetryPolicy(longRunningFn, {
+                startToCloseTimeout: '50ms',
+                maximumAttempts: 1,
+            }),
+        ).rejects.toThrow('Execution timed out after 50ms');
+    });
+
+    test('maximumAttempts', async () => {
+        const failingFn = vi.fn().mockRejectedValue(new Error('simulated failure'));
+
+        await expect(
+            runWithRetryPolicy(failingFn, {
+                maximumAttempts: 3,
+                initialInterval: '1ms',
+            }),
+        ).rejects.toThrow('simulated failure');
+
+        expect(mockedBackOff).toHaveBeenCalledWith(
+            expect.any(Function),
+            expect.objectContaining({ numOfAttempts: 3 }),
+        );
+        expect(failingFn).toHaveBeenCalledTimes(3);
+    });
+
+    test('initialInterval', async () => {
+        const fn = async () => {};
+
+        await runWithRetryPolicy(fn, {
+            initialInterval: '5s',
+        });
+
+        expect(mockedBackOff).toHaveBeenCalledWith(
+            expect.any(Function),
+            expect.objectContaining({ startingDelay: 5000 }),
+        );
+    });
+
+    test('maximumInterval', async () => {
+        const fn = async () => {};
+        await runWithRetryPolicy(fn, {
+            maximumInterval: '10s',
+        });
+        expect(mockedBackOff).toHaveBeenCalledWith(
+            expect.any(Function),
+            expect.objectContaining({ maxDelay: 10000 }),
+        );
+    });
+
+    test('backoffCoefficient', async () => {
+        const fn = async () => {};
+        await runWithRetryPolicy(fn, {
+            backoffCoefficient: 3,
+        });
+        expect(mockedBackOff).toHaveBeenCalledWith(
+            expect.any(Function),
+            expect.objectContaining({ timeMultiple: 3 }),
+        );
+    });
+
+    test('nonRetryableErrorTypes', async () => {
+        class CustomError extends Error {
+            constructor(message: string) {
+                super(message);
+                this.name = 'CustomError';
+            }
+        }
+
+        const retryableError = new Error('A retryable error');
+        const nonRetryableError = new CustomError('A non-retryable error');
+
+        const failingFn = vi
+            .fn()
+            .mockRejectedValueOnce(retryableError)
+            .mockRejectedValueOnce(nonRetryableError);
+
+        await expect(
+            runWithRetryPolicy(failingFn, {
+                maximumAttempts: 5,
+                initialInterval: '1ms',
+                nonRetryableErrorTypes: ['CustomError'],
+            }),
+        ).rejects.toThrow(nonRetryableError);
+
+        expect(failingFn).toHaveBeenCalledTimes(2);
+    });
+});