@aligent/microservice-util-lib 1.1.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aligent/microservice-util-lib",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "A set of utility functions for Aligent Microservices",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -11,11 +11,11 @@
     "directory": "packages/microservice-util-lib"
   },
   "dependencies": {
-    "@aws-sdk/client-s3": "^3.800.0",
-    "@aws-sdk/client-ssm": "^3.799.0",
+    "@aws-sdk/client-s3": "^3.922.0",
+    "@aws-sdk/client-ssm": "^3.922.0",
     "oauth-sign": "^0.9.0",
     "object-hash": "^3.0.0",
-    "openapi-fetch": "^0.13.5"
+    "openapi-fetch": "^0.15.0"
   },
   "author": "Aligent",
   "license": "MIT",

package/src/index.d.ts

@@ -3,8 +3,9 @@ import fetchSsmParams from './fetch-ssm-params/fetch-ssm-params';
 import getAwsIdFromArn from './get-aws-id-from-arn/get-aws-id-from-arn';
 import hasDefinedProperties from './has-properties-defined/has-properties-defined';
 import { ApiKey, Basic, OAuth10a, OAuth20, apiKeyAuthMiddleware, basicAuthMiddleware, oAuth10aAuthMiddleware, oAuth20AuthMiddleware } from './openapi-fetch-middlewares/authentications';
+import { RetryConfig as RetryMiddlewareConfig, retryMiddleware } from './openapi-fetch-middlewares/retry';
 import remap, { ObjectMap, Remap } from './remap/remap';
 import retryWrapper, { RetryConfig } from './retry-wrapper/retry-wrapper';
 import S3Dao from './s3/s3';
-export type { ApiKey, Basic, OAuth10a, OAuth20, ObjectMap, Remap, RetryConfig, S3Dao };
-export { apiKeyAuthMiddleware, basicAuthMiddleware, chunkBy, fetchSsmParams, getAwsIdFromArn, hasDefinedProperties, oAuth10aAuthMiddleware, oAuth20AuthMiddleware, remap, retryWrapper, };
+export type { ApiKey, Basic, OAuth10a, OAuth20, ObjectMap, Remap, RetryConfig, RetryMiddlewareConfig, S3Dao, };
+export { apiKeyAuthMiddleware, basicAuthMiddleware, chunkBy, fetchSsmParams, getAwsIdFromArn, hasDefinedProperties, oAuth10aAuthMiddleware, oAuth20AuthMiddleware, remap, retryMiddleware, retryWrapper, };

package/src/index.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.retryWrapper = exports.remap = exports.oAuth20AuthMiddleware = exports.oAuth10aAuthMiddleware = exports.hasDefinedProperties = exports.getAwsIdFromArn = exports.fetchSsmParams = exports.chunkBy = exports.basicAuthMiddleware = exports.apiKeyAuthMiddleware = void 0;
+exports.retryWrapper = exports.retryMiddleware = exports.remap = exports.oAuth20AuthMiddleware = exports.oAuth10aAuthMiddleware = exports.hasDefinedProperties = exports.getAwsIdFromArn = exports.fetchSsmParams = exports.chunkBy = exports.basicAuthMiddleware = exports.apiKeyAuthMiddleware = void 0;
 /* v8 ignore start */
 const chunk_by_1 = __importDefault(require("./chunk-by/chunk-by"));
 exports.chunkBy = chunk_by_1.default;
@@ -18,6 +18,8 @@ Object.defineProperty(exports, "apiKeyAuthMiddleware", { enumerable: true, get:
 Object.defineProperty(exports, "basicAuthMiddleware", { enumerable: true, get: function () { return authentications_1.basicAuthMiddleware; } });
 Object.defineProperty(exports, "oAuth10aAuthMiddleware", { enumerable: true, get: function () { return authentications_1.oAuth10aAuthMiddleware; } });
 Object.defineProperty(exports, "oAuth20AuthMiddleware", { enumerable: true, get: function () { return authentications_1.oAuth20AuthMiddleware; } });
+const retry_1 = require("./openapi-fetch-middlewares/retry");
+Object.defineProperty(exports, "retryMiddleware", { enumerable: true, get: function () { return retry_1.retryMiddleware; } });
 const remap_1 = __importDefault(require("./remap/remap"));
 exports.remap = remap_1.default;
 const retry_wrapper_1 = __importDefault(require("./retry-wrapper/retry-wrapper"));

package/src/openapi-fetch-middlewares/retry.d.ts

@@ -0,0 +1,54 @@
+import type { Middleware } from 'openapi-fetch';
+import type { RetryConfig, RetryContext, RetryDelayFn } from './types/retry';
+/**
+ * This middleware implements retry logic with support for:
+ * - Configurable number of retry attempts
+ * - Exponential backoff, linear backoff, or custom delay strategies
+ * - Custom retry conditions
+ * - Callbacks for retry events
+ * - Filtering by status codes
+ *
+ * @param {RetryConfig} [config={}] - The retry configuration.
+ * @returns {Middleware} The middleware for retry functionality.
+ *
+ * @example
+ * // Basic usage with defaults (3 retries, exponential backoff)
+ * const middleware = retryMiddleware();
+ *
+ * @example
+ * // Custom configuration
+ * const middleware = retryMiddleware({
+ *     retries: 5,
+ *     retryDelay: 'linear',
+ *     retryDelayBase: 200,
+ *     retryOn: [500, 502, 503, 504],
+ *     onRetry: (context) => {
+ *         console.log(`Retrying request (attempt ${context.attemptNumber})`);
+ *     },
+ * });
+ *
+ * @example
+ * // Custom retry condition
+ * const middleware = retryMiddleware({
+ *     retries: 3,
+ *     retryCondition: async (context) => {
+ *         // Only retry on 503 Service Unavailable
+ *         return context.response.status === 503;
+ *     },
+ * });
+ *
+ * @example
+ * // Custom delay function
+ * const middleware = retryMiddleware({
+ *     retries: 3,
+ *     retryDelay: (attemptNumber) => {
+ *         // Custom delay with jitter
+ *         const baseDelay = 100 * Math.pow(2, attemptNumber);
+ *         const jitter = Math.random() * 100;
+ *         return baseDelay + jitter;
+ *     },
+ * });
+ */
+declare function retryMiddleware(config?: RetryConfig): Middleware;
+export { retryMiddleware };
+export type { RetryConfig, RetryContext, RetryDelayFn };

package/src/openapi-fetch-middlewares/retry.js

@@ -0,0 +1,218 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.retryMiddleware = retryMiddleware;
+const is_network_error_1 = require("./utils/is-network-error");
+const IDEMPOTENT_HTTP_METHODS = ['GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE'];
+/**
+ * Default retry condition function.
+ * Retries on:
+ * - Network errors
+ * - 5xx server errors
+ * - 429 Too Many Requests
+ * - 408 Request Timeout
+ * - Idempotent methods only
+ *
+ * @param {RetryContext} context - The retry context.
+ * @param {boolean} idempotentOnly - Whether to retry only when the HTTP method is an idempotent methods.
+ * @returns {boolean} Whether the request should be retried.
+ */
+function defaultRetryCondition(context, idempotentOnly) {
+    const { request, response, error } = context;
+    if (!IDEMPOTENT_HTTP_METHODS.includes(request.method) && idempotentOnly) {
+        return false;
+    }
+    if ((0, is_network_error_1.isNetworkError)(error)) {
+        return true;
+    }
+    if (response) {
+        return response.status >= 500 || response.status === 429 || response.status === 408;
+    }
+    return false;
+}
+/**
+ * Calculates delay for exponential backoff strategy.
+ *
+ * @param {number} attempt - The current attempt number (1-indexed).
+ * @param {number} baseDelay - Base delay in milliseconds.
+ * @param {number} maxDelay - Maximum delay in milliseconds.
+ * @returns {number} The delay in milliseconds.
+ */
+function exponentialDelay(attempt, baseDelay, maxDelay) {
+    const delay = baseDelay * Math.pow(2, attempt - 1);
+    return Math.min(delay, maxDelay);
+}
+/**
+ * Calculates delay for linear backoff strategy.
+ *
+ * @param {number} attempt - The current attempt number (1-indexed).
+ * @param {number} baseDelay - Base delay in milliseconds.
+ * @param {number} maxDelay - Maximum delay in milliseconds.
+ * @returns {number} The delay in milliseconds.
+ */
+function linearDelay(attempt, baseDelay, maxDelay) {
+    const delay = baseDelay * attempt;
+    return Math.min(delay, maxDelay);
+}
+/**
+ * Gets the retry delay function based on the configuration.
+ *
+ * @param {RetryConfig} config - The retry configuration.
+ * @returns {RetryDelayFn} The retry delay function.
+ */
+function getRetryDelayFn(config) {
+    const baseDelay = config?.baseDelay ?? 100;
+    const maxDelay = config?.maxDelay ?? 30000;
+    const retryDelay = config?.retryDelay;
+    if (typeof retryDelay === 'function') {
+        return retryDelay;
+    }
+    switch (retryDelay) {
+        case 'linear':
+            return (attempt) => linearDelay(attempt, baseDelay, maxDelay);
+        case 'exponential':
+        default:
+            return (attempt) => exponentialDelay(attempt, baseDelay, maxDelay);
+    }
+}
+/**
+ * Checks if the response status should trigger a retry based on the retryOn configuration.
+ *
+ * @param {number} status - The HTTP status code.
+ * @param {number[]} retryOn - Array of status codes to retry on.
+ * @returns {boolean} Whether the status should trigger a retry.
+ */
+function shouldRetryOnStatus(status, retryOn) {
+    return retryOn.includes(status);
+}
+/**
+ * This middleware implements retry logic with support for:
+ * - Configurable number of retry attempts
+ * - Exponential backoff, linear backoff, or custom delay strategies
+ * - Custom retry conditions
+ * - Callbacks for retry events
+ * - Filtering by status codes
+ *
+ * @param {RetryConfig} [config={}] - The retry configuration.
+ * @returns {Middleware} The middleware for retry functionality.
+ *
+ * @example
+ * // Basic usage with defaults (3 retries, exponential backoff)
+ * const middleware = retryMiddleware();
+ *
+ * @example
+ * // Custom configuration
+ * const middleware = retryMiddleware({
+ *     retries: 5,
+ *     retryDelay: 'linear',
+ *     retryDelayBase: 200,
+ *     retryOn: [500, 502, 503, 504],
+ *     onRetry: (context) => {
+ *         console.log(`Retrying request (attempt ${context.attemptNumber})`);
+ *     },
+ * });
+ *
+ * @example
+ * // Custom retry condition
+ * const middleware = retryMiddleware({
+ *     retries: 3,
+ *     retryCondition: async (context) => {
+ *         // Only retry on 503 Service Unavailable
+ *         return context.response.status === 503;
+ *     },
+ * });
+ *
+ * @example
+ * // Custom delay function
+ * const middleware = retryMiddleware({
+ *     retries: 3,
+ *     retryDelay: (attemptNumber) => {
+ *         // Custom delay with jitter
+ *         const baseDelay = 100 * Math.pow(2, attemptNumber);
+ *         const jitter = Math.random() * 100;
+ *         return baseDelay + jitter;
+ *     },
+ * });
+ */
+function retryMiddleware(config) {
+    const normalisedConfig = {
+        ...config,
+        retries: config?.retries ?? 3,
+        retryCondition: config?.retryCondition ?? defaultRetryCondition,
+        retryDelay: getRetryDelayFn(config),
+        idempotentOnly: config?.idempotentOnly ?? true,
+        fetch: config?.fetch ?? fetch,
+    };
+    return {
+        async onResponse({ request, response }) {
+            const context = { attempt: 1, request, response, error: null };
+            // If retryOn is specified, only use that list
+            if (config?.retryOn && config.retryOn.length > 0) {
+                if (!shouldRetryOnStatus(response.status, config.retryOn)) {
+                    return context.response;
+                }
+                return await performRetries(normalisedConfig, context);
+            }
+            // Otherwise, check if we should retry based on retry condition
+            const shouldRetry = await normalisedConfig.retryCondition(context, normalisedConfig.idempotentOnly);
+            if (!shouldRetry) {
+                return context.response;
+            }
+            return await performRetries(normalisedConfig, context);
+        },
+        async onError({ request, error }) {
+            if (!(0, is_network_error_1.isNetworkError)(error)) {
+                throw error;
+            }
+            return await performRetries(normalisedConfig, {
+                attempt: 1,
+                request,
+                response: null,
+                error,
+            });
+        },
+    };
+}
+/**
+ * Performs the retry attempts.
+ */
+async function performRetries(config, context) {
+    const maxRetries = config.retries;
+    let response = context.response;
+    let attempt = 1;
+    do {
+        const delay = await config.retryDelay(attempt, { ...context, attempt, response });
+        await new Promise(resolve => setTimeout(resolve, delay));
+        if (config.onRetry) {
+            await config.onRetry({ ...context, attempt, response });
+        }
+        try {
+            const signal = config.shouldResetTimeout ? undefined : context.request.signal;
+            response = await config.fetch(new Request(context.request, { signal }));
+            context = { ...context, attempt: attempt + 1, response, error: null };
+            attempt++;
+        }
+        catch (err) {
+            // Network error occurred during retry
+            const error = err instanceof Error ? err : new Error(String(err));
+            context = { ...context, attempt: attempt + 1, response, error };
+            attempt++;
+        }
+        if (!response) {
+            continue;
+        }
+        if (config.retryOn && !shouldRetryOnStatus(response?.status, config.retryOn)) {
+            return response;
+        }
+        const shouldRetry = await config.retryCondition(context, config.idempotentOnly);
+        if (!shouldRetry) {
+            return response;
+        }
+    } while (attempt <= maxRetries);
+    if (!response) {
+        throw context.error;
+    }
+    if (!response.ok) {
+        throw new Error(`${response.status}: ${response.statusText}`);
+    }
+    return response;
+}

package/src/openapi-fetch-middlewares/types/retry.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Represents the context for a retry attempt.
+ *
+ * @interface RetryContext
+ * @property {number} attempt - The current attempt number (1-indexed).
+ * @property {Request} request - The original request being retried.
+ * @property {Response | null} response - The response that triggered the retry.
+ * @property {Error | null} error - The error that triggered the retry, if any.
+ */
+export interface RetryContext {
+    attempt: number;
+    request: Request;
+    response: Response | null;
+    error: Error | null;
+}
+/**
+ * Function type for custom retry condition.
+ * Returns true if the request should be retried.
+ *
+ * @param {RetryContext} context - The retry context containing attempt information.
+ * @param {boolean} idempotentOnly - Whether to retry only when the HTTP method is an idempotent methods.
+ * @returns {boolean | Promise<boolean>} Whether to retry the request.
+ */
+export type RetryConditionFn = (context: RetryContext, idempotentOnly: boolean) => boolean | Promise<boolean>;
+/**
+ * Function type for custom retry delay calculation.
+ * Returns the delay in milliseconds before the next retry attempt.
+ *
+ * @param {number} attempt - The current attempt number (1-indexed).
+ * @param {RetryContext} context - The retry context containing attempt information.
+ * @returns {number | Promise<number>} The delay in milliseconds.
+ */
+export type RetryDelayFn = (attempt: number, context: RetryContext) => number | Promise<number>;
+/**
+ * Function type for the onRetry callback.
+ * Called before each retry attempt.
+ *
+ * @param {RetryContext} context - The retry context containing attempt information.
+ * @returns {void | Promise<void>}
+ */
+export type OnRetryFn = (context: RetryContext) => void | Promise<void>;
+/**
+ * Configuration for the retry middleware.
+ *
+ * This interface provides options to configure retry behavior, including:
+ * - Number of retry attempts
+ * - Custom retry conditions
+ * - Retry delay strategies (exponential backoff, linear, custom)
+ * - Callbacks for retry events
+ *
+ * @interface RetryConfig
+ * @property {number} [retries=3] - The maximum number of retry attempts.
+ * @property {RetryConditionFn} [retryCondition]
+ * - Custom function to determine if a request should be retried.
+ * - Defaults to retrying on 5xx, 429, 408 errors and network errors.
+ * @property {RetryDelayFn | 'exponential' | 'linear'} [retryDelay='exponential']
+ * - Strategy for calculating delay between retries.
+ *      - 'exponential': Exponential backoff (100ms * 2^attemptNumber)
+ *      - 'linear': Linear backoff (100ms * attemptNumber)
+ *      - Custom function: Allows custom delay calculation
+ * @property {number} [retryDelayBase=100] - Base delay in milliseconds for built-in delay strategies.
+ * @property {number} [maxRetryDelay=30000] - Maximum delay in milliseconds between retry attempts.
+ * @property {boolean} [shouldResetTimeout=false] - Whether to reset the timeout between retries.
+ * @property {OnRetryFn} [onRetry] - Callback function executed before each retry attempt.
+ * @property {number[]} [retryOn]
+ * - Array of HTTP status codes that should trigger a retry.
+ * - If not specified, defaults to 5xx, 429 and 408 errors.
+ * @property {boolean} [idempotentOnly]
+ * - Whether to retry only when the HTTP method is an idempotent methods.
+ * - If not specified, defaults to true and retry only on GET, HEAD, OPTIONS, PUT or DELETE method.
+ * @property {typeof fetch} [fetch]
+ * - Custom fetch function to use for retries. Defaults to the global fetch function.
+ * - Useful for testing or using a custom fetch implementation.
+ */
+export interface RetryConfig {
+    retries?: number;
+    retryCondition?: RetryConditionFn;
+    retryDelay?: RetryDelayFn | 'exponential' | 'linear';
+    baseDelay?: number;
+    maxDelay?: number;
+    shouldResetTimeout?: boolean;
+    onRetry?: OnRetryFn;
+    retryOn?: number[];
+    idempotentOnly?: boolean;
+    fetch?: typeof fetch;
+}
+export type NormalisedConfig = Omit<RetryConfig, 'retries' | 'retryCondition' | 'retryDelay' | 'idempotentOnly' | 'fetch'> & {
+    retries: number;
+    retryCondition: RetryConditionFn;
+    retryDelay: RetryDelayFn;
+    idempotentOnly: boolean;
+    fetch: typeof fetch;
+};

package/src/openapi-fetch-middlewares/types/retry.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/src/openapi-fetch-middlewares/utils/is-network-error.d.ts

@@ -0,0 +1,5 @@
+/**
+ * This is a Typescript copy of the amazing work from Sindre Sorhus
+ * https://github.com/sindresorhus/is-network-error
+ */
+export declare function isNetworkError(error: unknown): error is TypeError;

package/src/openapi-fetch-middlewares/utils/is-network-error.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * This is a Typescript copy of the amazing work from Sindre Sorhus
+ * https://github.com/sindresorhus/is-network-error
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isNetworkError = isNetworkError;
+const ERROR_MESSAGES = new Set([
+    'network error', // Chrome
+    'Failed to fetch', // Chrome
+    'NetworkError when attempting to fetch resource.', // Firefox
+    'The Internet connection appears to be offline.', // Safari 16
+    'Network request failed', // `cross-fetch`
+    'fetch failed', // Undici (Node.js)
+    'terminated', // Undici (Node.js)
+    ' A network error occurred.', // Bun (WebKit)
+    'Network connection lost', // Cloudflare Workers (fetch)
+]);
+function isError(object) {
+    return Object.prototype.toString.call(object) === '[object Error]';
+}
+function isNetworkError(error) {
+    const isValid = error && isError(error) && error.name === 'TypeError' && typeof error.message === 'string';
+    if (!isValid) {
+        return false;
+    }
+    const { message, stack } = error;
+    // Safari 17+ has generic message but no stack for network errors
+    if (message === 'Load failed') {
+        return (stack === undefined ||
+            // Sentry adds its own stack trace to the fetch error, so also check for that
+            '__sentry_captured__' in error);
+    }
+    // Deno network errors start with specific text
+    if (message.startsWith('error sending request for url')) {
+        return true;
+    }
+    // Standard network error messages
+    return ERROR_MESSAGES.has(message);
+}