@aligent/microservice-util-lib 1.3.4 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aligent/microservice-util-lib",
-  "version": "1.3.4",
+  "version": "1.4.0",
   "description": "A set of utility functions for Aligent Microservices",
   "type": "commonjs",
   "main": "./src/index.js",

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

@@ -1,40 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.logMiddleware = logMiddleware;
-/**
- * Parse request/response body based on Content-Type header
- */
-async function parseBody(source, contentType) {
-    const normalizedContentType = contentType ? contentType.toLowerCase() : 'application/json';
-    try {
-        if (!source.body) {
-            return 'null';
-        }
-        // JSON content
-        if (normalizedContentType.includes('application/json')) {
-            return await source.json();
-        }
-        // Text content
-        if (normalizedContentType.includes('text/') ||
-            normalizedContentType.includes('application/xml') ||
-            normalizedContentType.includes('application/x-www-form-urlencoded')) {
-            return await source.text();
-        }
-        // Binary or multipart content - don't parse
-        if (normalizedContentType.includes('multipart/form-data') ||
-            normalizedContentType.includes('application/octet-stream') ||
-            normalizedContentType.includes('image/') ||
-            normalizedContentType.includes('video/') ||
-            normalizedContentType.includes('audio/')) {
-            return `[Binary content: ${contentType}]`;
-        }
-        // Unknown content type, try TEXT as default
-        return await source.text();
-    }
-    catch (error) {
-        return `[Unable to parse ${contentType} body: ${error instanceof Error ? error.message : 'Unknown error'}]`;
-    }
-}
+const body_parser_1 = require("./utils/body-parser");
 /**
  * Creates a logging middleware for openapi-fetch clients.
  *
@@ -94,14 +61,14 @@ function logMiddleware(clientName, logLevel = 'INFO', logger = console) {
                 baseUrl: options.baseUrl,
                 url: request.url,
                 params: params,
-                body: await parseBody(request.clone(), contentType),
+                body: await (0, body_parser_1.parseBody)(request.clone(), contentType),
             });
         },
         async onResponse({ response }) {
             const contentType = response.headers.get('Content-Type');
             log(`Response from ${clientName}`, {
                 status: response.status,
-                body: await parseBody(response.clone(), contentType),
+                body: await (0, body_parser_1.parseBody)(response.clone(), contentType),
             });
         },
     };

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

@@ -1,6 +1,7 @@
 import type { Middleware } from 'openapi-fetch';
 import type { RetryConfig, RetryContext, RetryDelayFn } from './types/retry';
 import { HttpResponseError, isHttpResponseError } from './utils/http-response-error';
+export type { HttpRequestData, HttpResponseData } from './utils/http-response-error';
 /**
  * This middleware implements retry logic with support for:
  * - Configurable number of retry attempts
@@ -21,7 +22,7 @@ import { HttpResponseError, isHttpResponseError } from './utils/http-response-er
  * const middleware = retryMiddleware({
  *     retries: 5,
  *     retryDelay: 'linear',
- *     retryDelayBase: 200,
+ *     baseDelay: 200,
  *     retryOn: [500, 502, 503, 504],
  *     onRetry: (context) => {
  *         console.log(`Retrying request (attempt ${context.attemptNumber})`);

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

@@ -89,15 +89,17 @@ function shouldRetryOnStatus(status, retryOn) {
     return retryOn.includes(status);
 }
 /**
- * Checks the response status and throws HttpResponseError if it's not "ok".
+ * Checks the response status and throws HttpResponseError if it's not "ok"
+ * and throwOnNotOk is enabled.
  *
  * @param {Response} response - The HTTP response object.
  * @param {Request} request - The HTTP request object.
- * @throws {HttpResponseError} When the response is not an "ok" response.
+ * @param {boolean} throwOnNotOk - Whether to throw on non-ok responses.
+ * @throws {HttpResponseError} When throwOnNotOk is true and the response is not "ok".
  */
-function throwErrorIfNotOkResponse(response, request) {
-    if (!response.ok) {
-        throw new http_response_error_1.HttpResponseError(response, request);
+async function throwErrorIfNotOkResponse(response, request, throwOnNotOk) {
+    if (throwOnNotOk && !response.ok) {
+        throw await http_response_error_1.HttpResponseError.create(response, request);
     }
 }
 /**
@@ -120,7 +122,7 @@ function throwErrorIfNotOkResponse(response, request) {
  * const middleware = retryMiddleware({
  *     retries: 5,
  *     retryDelay: 'linear',
- *     retryDelayBase: 200,
+ *     baseDelay: 200,
  *     retryOn: [500, 502, 503, 504],
  *     onRetry: (context) => {
  *         console.log(`Retrying request (attempt ${context.attemptNumber})`);
@@ -157,6 +159,7 @@ function retryMiddleware(config) {
         retryDelay: getRetryDelayFn(config),
         idempotentOnly: config?.idempotentOnly ?? true,
         fetch: config?.fetch ?? fetch,
+        throwOnNotOk: config?.throwOnNotOk ?? true,
     };
     return {
         async onResponse({ request, response }) {
@@ -164,7 +167,7 @@ function retryMiddleware(config) {
             // If retryOn is specified, only use that list
             if (config?.retryOn && config.retryOn.length > 0) {
                 if (!shouldRetryOnStatus(response.status, config.retryOn)) {
-                    throwErrorIfNotOkResponse(response, request);
+                    await throwErrorIfNotOkResponse(response, request, normalisedConfig.throwOnNotOk);
                     return response;
                 }
                 return await performRetries(normalisedConfig, context);
@@ -172,7 +175,7 @@ function retryMiddleware(config) {
             // Otherwise, check if we should retry based on retry condition
             const shouldRetry = await normalisedConfig.retryCondition(context, normalisedConfig.idempotentOnly);
             if (!shouldRetry) {
-                throwErrorIfNotOkResponse(response, request);
+                await throwErrorIfNotOkResponse(response, request, normalisedConfig.throwOnNotOk);
                 return response;
             }
             return await performRetries(normalisedConfig, context);
@@ -221,18 +224,18 @@ async function performRetries(config, context) {
             continue;
         }
         if (config.retryOn && !shouldRetryOnStatus(response?.status, config.retryOn)) {
-            throwErrorIfNotOkResponse(response, context.request);
+            await throwErrorIfNotOkResponse(response, context.request, config.throwOnNotOk);
             return response;
         }
         const shouldRetry = await config.retryCondition(context, config.idempotentOnly);
         if (!shouldRetry) {
-            throwErrorIfNotOkResponse(response, context.request);
+            await throwErrorIfNotOkResponse(response, context.request, config.throwOnNotOk);
             return response;
         }
     } while (attempt <= maxRetries);
     if (!response) {
         throw context.error;
     }
-    throwErrorIfNotOkResponse(response, context.request);
+    await throwErrorIfNotOkResponse(response, context.request, config.throwOnNotOk);
     return response;
 }

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

@@ -18,7 +18,7 @@ export interface RetryContext {
  * 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.
+ * @param {boolean} idempotentOnly - Whether to retry only when the HTTP method is idempotent.
  * @returns {boolean | Promise<boolean>} Whether to retry the request.
  */
 export type RetryConditionFn = (context: RetryContext, idempotentOnly: boolean) => boolean | Promise<boolean>;
@@ -58,16 +58,21 @@ export type OnRetryFn = (context: RetryContext) => void | Promise<void>;
  *      - '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 {number} [baseDelay=100] - Base delay in milliseconds for built-in delay strategies.
+ * @property {number} [maxDelay=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.
+ * - Defaults to 5xx, 429, and 408 errors.
+ * @property {boolean} [idempotentOnly=true]
+ * - Whether to retry only when the HTTP method is idempotent.
+ * - Defaults to `true`, retrying only on GET, HEAD, OPTIONS, PUT, or DELETE methods.
+ * @property {boolean} [throwOnNotOk=true]
+ * - Whether to throw an `HttpResponseError` when the final response has a non-OK status (i.e. not 2xx).
+ * - Defaults to `true` for backward compatibility.
+ * - Set to `false` to return the response as-is, which allows downstream middlewares
+ *   (e.g. logging middleware) to inspect the response before the caller handles the error.
  * @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.
@@ -82,12 +87,14 @@ export interface RetryConfig {
     onRetry?: OnRetryFn;
     retryOn?: number[];
     idempotentOnly?: boolean;
+    throwOnNotOk?: boolean;
     fetch?: typeof fetch;
 }
-export type NormalisedConfig = Omit<RetryConfig, 'retries' | 'retryCondition' | 'retryDelay' | 'idempotentOnly' | 'fetch'> & {
+export type NormalisedConfig = Omit<RetryConfig, 'retries' | 'retryCondition' | 'retryDelay' | 'idempotentOnly' | 'throwOnNotOk' | 'fetch'> & {
     retries: number;
     retryCondition: RetryConditionFn;
     retryDelay: RetryDelayFn;
     idempotentOnly: boolean;
+    throwOnNotOk: boolean;
     fetch: typeof fetch;
 };

package/src/openapi-fetch-middlewares/utils/body-parser.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Parse request/response body based on Content-Type header
+ */
+export declare function parseBody(source: Request | Response, contentType: string | null): Promise<unknown>;

package/src/openapi-fetch-middlewares/utils/body-parser.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseBody = parseBody;
+/**
+ * Parse request/response body based on Content-Type header
+ */
+async function parseBody(source, contentType) {
+    const normalizedContentType = contentType ? contentType.toLowerCase() : 'application/json';
+    try {
+        if (!source.body) {
+            return 'null';
+        }
+        // JSON content
+        if (normalizedContentType.includes('application/json')) {
+            return await source.json();
+        }
+        // Text content
+        if (normalizedContentType.includes('text/') ||
+            normalizedContentType.includes('application/xml') ||
+            normalizedContentType.includes('application/x-www-form-urlencoded')) {
+            return await source.text();
+        }
+        // Binary or multipart content - don't parse
+        if (normalizedContentType.includes('multipart/form-data') ||
+            normalizedContentType.includes('application/octet-stream') ||
+            normalizedContentType.includes('image/') ||
+            normalizedContentType.includes('video/') ||
+            normalizedContentType.includes('audio/')) {
+            return `[Binary content: ${contentType}]`;
+        }
+        // Unknown content type, try TEXT as default
+        return await source.text();
+    }
+    catch (error) {
+        return `[Unable to parse ${contentType} body: ${error instanceof Error ? error.message : 'Unknown error'}]`;
+    }
+}

package/src/openapi-fetch-middlewares/utils/http-response-error.d.ts

@@ -1,15 +1,47 @@
+/**
+ * Serializable snapshot of an HTTP request.
+ * Captures all meaningful data at creation time so it can be
+ * logged, serialized, or inspected without stream-consumption issues.
+ */
+export interface HttpRequestData {
+    readonly method: string;
+    readonly url: string;
+    readonly params: Record<string, string>;
+    readonly headers: Record<string, string>;
+    readonly body: unknown;
+}
+/**
+ * Serializable snapshot of an HTTP response.
+ * Captures all meaningful data at creation time so it can be
+ * logged, serialized, or inspected without stream-consumption issues.
+ */
+export interface HttpResponseData {
+    readonly status: number;
+    readonly statusText: string;
+    readonly headers: Record<string, string>;
+    readonly body: unknown;
+}
 /**
  * Custom error class for HTTP response errors, similar to Axios Error.
  * Provides detailed information about the failed request and response.
+ *
+ * Stores pre-read, serializable snapshots of the request and response
+ * rather than raw Request/Response objects, ensuring bodies are always
+ * available for logging and debugging.
  */
 export declare class HttpResponseError extends Error {
     readonly name = "HttpResponseError";
     readonly status: number;
     readonly statusText: string;
-    readonly response: Response;
-    readonly request: Request;
+    readonly response: HttpResponseData;
+    readonly request: HttpRequestData;
     readonly isHttpResponseError = true;
-    constructor(response: Response, request: Request);
+    private constructor();
+    /**
+     * Creates an HttpResponseError with pre-read request and response bodies.
+     * Bodies are read eagerly so they are available for logging/serialization.
+     */
+    static create(response: Response, request: Request): Promise<HttpResponseError>;
     /**
      * Returns a JSON representation of the error for logging/debugging.
      */
@@ -18,8 +50,8 @@ export declare class HttpResponseError extends Error {
         message: string;
         status: number;
         statusText: string;
-        method: string;
-        url: string;
+        request: HttpRequestData;
+        response: HttpResponseData;
     };
 }
 /**

package/src/openapi-fetch-middlewares/utils/http-response-error.js

@@ -2,9 +2,14 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HttpResponseError = void 0;
 exports.isHttpResponseError = isHttpResponseError;
+const body_parser_1 = require("./body-parser");
 /**
  * Custom error class for HTTP response errors, similar to Axios Error.
  * Provides detailed information about the failed request and response.
+ *
+ * Stores pre-read, serializable snapshots of the request and response
+ * rather than raw Request/Response objects, ensuring bodies are always
+ * available for logging and debugging.
  */
 class HttpResponseError extends Error {
     name = 'HttpResponseError';
@@ -13,17 +18,42 @@ class HttpResponseError extends Error {
     response;
     request;
     isHttpResponseError = true;
-    constructor(response, request) {
+    constructor(request, response) {
         super(`${response.status}: ${response.statusText}`);
         this.status = response.status;
         this.statusText = response.statusText;
-        this.response = response;
         this.request = request;
+        this.response = response;
         // Maintains proper stack trace for where error was thrown (V8 engines)
         if (Error.captureStackTrace) {
             Error.captureStackTrace(this, HttpResponseError);
         }
     }
+    /**
+     * Creates an HttpResponseError with pre-read request and response bodies.
+     * Bodies are read eagerly so they are available for logging/serialization.
+     */
+    static async create(response, request) {
+        const url = new URL(request.url);
+        const [requestBody, responseBody] = await Promise.all([
+            (0, body_parser_1.parseBody)(request.clone(), request.headers.get('content-type')),
+            (0, body_parser_1.parseBody)(response.clone(), response.headers.get('content-type')),
+        ]);
+        const requestData = {
+            method: request.method,
+            url: request.url,
+            params: Object.fromEntries(url.searchParams.entries()),
+            headers: Object.fromEntries(request.headers.entries()),
+            body: requestBody,
+        };
+        const responseData = {
+            status: response.status,
+            statusText: response.statusText,
+            headers: Object.fromEntries(response.headers.entries()),
+            body: responseBody,
+        };
+        return new HttpResponseError(requestData, responseData);
+    }
     /**
      * Returns a JSON representation of the error for logging/debugging.
      */
@@ -33,8 +63,8 @@ class HttpResponseError extends Error {
             message: this.message,
             status: this.status,
             statusText: this.statusText,
-            method: this.request.method,
-            url: this.request.url,
+            request: this.request,
+            response: this.response,
         };
     }
 }