@nimbus-cqrs/core 2.2.0 → 2.3.0

package/esm/_dnt.polyfills.d.ts

@@ -0,0 +1,7 @@
+declare global {
+    interface Error {
+        cause?: unknown;
+    }
+}
+export {};
+//# sourceMappingURL=_dnt.polyfills.d.ts.map

package/esm/_dnt.polyfills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_dnt.polyfills.d.ts","sourceRoot":"","sources":["../src/_dnt.polyfills.ts"],"names":[],"mappings":"AAAA,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,KAAK;QACb,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;CACF;AAED,OAAO,EAAE,CAAC"}

package/esm/_dnt.polyfills.js

@@ -0,0 +1 @@
+export {};

package/esm/index.d.ts

@@ -1,3 +1,5 @@
+import "./_dnt.polyfills.js";
+export * from './lib/env/getEnv.js';
 export * from './lib/eventBus/eventBus.js';
 export * from './lib/exception/exception.js';
 export * from './lib/exception/forbiddenException.js';
@@ -6,6 +8,7 @@ export * from './lib/exception/invalidInputException.js';
 export * from './lib/exception/notFoundException.js';
 export * from './lib/exception/unauthorizedException.js';
 export * from './lib/log/logFormatter.js';
+export * from './lib/log/logTruncator.js';
 export * from './lib/log/logger.js';
 export * from './lib/log/logLevel.js';
 export * from './lib/log/options.js';
@@ -14,5 +17,6 @@ export * from './lib/message/event.js';
 export * from './lib/message/message.js';
 export * from './lib/message/query.js';
 export * from './lib/message/router.js';
+export * from './lib/retry/withRetry.js';
 export * from './lib/tracing/withSpan.js';
 //# sourceMappingURL=index.d.ts.map

package/esm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,uCAAuC,CAAC;AACtD,cAAc,qCAAqC,CAAC;AACpD,cAAc,0CAA0C,CAAC;AACzD,cAAc,sCAAsC,CAAC;AACrD,cAAc,0CAA0C,CAAC;AACzD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,uCAAuC,CAAC;AACtD,cAAc,qCAAqC,CAAC;AACpD,cAAc,0CAA0C,CAAC;AACzD,cAAc,sCAAsC,CAAC;AACrD,cAAc,0CAA0C,CAAC;AACzD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC"}

package/esm/index.js

@@ -1,3 +1,5 @@
+import "./_dnt.polyfills.js";
+export * from './lib/env/getEnv.js';
 export * from './lib/eventBus/eventBus.js';
 export * from './lib/exception/exception.js';
 export * from './lib/exception/forbiddenException.js';
@@ -6,6 +8,7 @@ export * from './lib/exception/invalidInputException.js';
 export * from './lib/exception/notFoundException.js';
 export * from './lib/exception/unauthorizedException.js';
 export * from './lib/log/logFormatter.js';
+export * from './lib/log/logTruncator.js';
 export * from './lib/log/logger.js';
 export * from './lib/log/logLevel.js';
 export * from './lib/log/options.js';
@@ -14,4 +17,5 @@ export * from './lib/message/event.js';
 export * from './lib/message/message.js';
 export * from './lib/message/query.js';
 export * from './lib/message/router.js';
+export * from './lib/retry/withRetry.js';
 export * from './lib/tracing/withSpan.js';

package/esm/lib/env/getEnv.d.ts

@@ -0,0 +1,15 @@
+type GetEnvInput = {
+    variables: string[];
+};
+/**
+ * Get environment variables from the process.env object.
+ * Throws an exception if any of the variables are not defined
+ * and logs the missing variable names.
+ *
+ * @param variables - The list of environment variables to get
+ * @returns {Record<string, string>} Object of the environment variables
+ * @throws {GenericException} Thrown if any of the requested variables are not defined
+ */
+export declare const getEnv: ({ variables, }: GetEnvInput) => Record<string, string>;
+export {};
+//# sourceMappingURL=getEnv.d.ts.map

package/esm/lib/env/getEnv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getEnv.d.ts","sourceRoot":"","sources":["../../../src/lib/env/getEnv.ts"],"names":[],"mappings":"AAIA,KAAK,WAAW,GAAG;IACf,SAAS,EAAE,MAAM,EAAE,CAAC;CACvB,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,MAAM,GAAI,gBAEpB,WAAW,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CA2BrC,CAAC"}

package/esm/lib/env/getEnv.js

@@ -0,0 +1,35 @@
+import process from 'node:process';
+import { GenericException } from '../exception/genericException.js';
+import { getLogger } from '../log/logger.js';
+/**
+ * Get environment variables from the process.env object.
+ * Throws an exception if any of the variables are not defined
+ * and logs the missing variable names.
+ *
+ * @param variables - The list of environment variables to get
+ * @returns {Record<string, string>} Object of the environment variables
+ * @throws {GenericException} Thrown if any of the requested variables are not defined
+ */
+export const getEnv = ({ variables, }) => {
+    const envVars = {};
+    const missingEnvVars = [];
+    for (const variable of variables) {
+        if (!process.env[variable]) {
+            missingEnvVars.push(variable);
+        }
+        envVars[variable] = process.env[variable];
+    }
+    if (missingEnvVars.length > 0) {
+        getLogger().error({
+            category: 'Nimbus',
+            message: 'Undefined environment variables',
+            data: {
+                undefinedVariables: missingEnvVars,
+            },
+        });
+        throw new GenericException('Undefined environment variables', {
+            undefinedVariables: missingEnvVars,
+        });
+    }
+    return envVars;
+};

package/esm/lib/eventBus/eventBus.d.ts

@@ -240,7 +240,6 @@ export declare class NimbusEventBus {
     private _processEvent;
     private _recordDeliveryMetrics;
     private _handleFinalFailure;
-    private _calculateRetryDelay;
     /**
      * Validate the size of the event and return the size in bytes.
      *

package/esm/lib/eventBus/eventBus.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"eventBus.d.ts","sourceRoot":"","sources":["../../../src/lib/eventBus/eventBus.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AA0CjD;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAChC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CACvC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,mBAAmB,CAAC,MAAM,SAAS,KAAK,IAAI;IACpD;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAChD;;OAEG;IACH,OAAO,CAAC,EAAE,IAAI,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;CACjD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,qBAAa,cAAc;IACvB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAe;IAC7C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAU;IACrC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAyB;IAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;gBACS,OAAO,CAAC,EAAE,qBAAqB;IAU3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACI,QAAQ,CAAC,MAAM,SAAS,KAAK,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAqD1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiDG;IACI,cAAc,CAAC,MAAM,SAAS,KAAK,EAAE,EACxC,IAAI,EACJ,OAAO,EACP,OAAO,EACP,OAAO,GACV,EAAE,mBAAmB,CAAC,MAAM,CAAC,GAAG,IAAI;IAqCrC,OAAO,CAAC,aAAa;IAmFrB,OAAO,CAAC,sBAAsB;IAY9B,OAAO,CAAC,mBAAmB;IAwC3B,OAAO,CAAC,oBAAoB;IAW5B;;;;;;;;OAQG;IACH,OAAO,CAAC,kBAAkB;CAmB7B;AAOD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,aAAa,GACtB,MAAM,MAAM,EACZ,UAAU,IAAI,CAAC,qBAAqB,EAAE,MAAM,CAAC,KAC9C,IAEF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,WAAW,GAAI,OAAM,MAAkB,KAAG,cAStD,CAAC"}
+{"version":3,"file":"eventBus.d.ts","sourceRoot":"","sources":["../../../src/lib/eventBus/eventBus.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AA2CjD;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAChC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CACvC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,mBAAmB,CAAC,MAAM,SAAS,KAAK,IAAI;IACpD;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAChD;;OAEG;IACH,OAAO,CAAC,EAAE,IAAI,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;CACjD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,qBAAa,cAAc;IACvB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAe;IAC7C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAU;IACrC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAyB;IAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;gBACS,OAAO,CAAC,EAAE,qBAAqB;IAU3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACI,QAAQ,CAAC,MAAM,SAAS,KAAK,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAqD1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiDG;IACI,cAAc,CAAC,MAAM,SAAS,KAAK,EAAE,EACxC,IAAI,EACJ,OAAO,EACP,OAAO,EACP,OAAO,GACV,EAAE,mBAAmB,CAAC,MAAM,CAAC,GAAG,IAAI;IAqCrC,OAAO,CAAC,aAAa;IA4ErB,OAAO,CAAC,sBAAsB;IAY9B,OAAO,CAAC,mBAAmB;IAwC3B;;;;;;;;OAQG;IACH,OAAO,CAAC,kBAAkB;CAmB7B;AAOD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,aAAa,GACtB,MAAM,MAAM,EACZ,UAAU,IAAI,CAAC,qBAAqB,EAAE,MAAM,CAAC,KAC9C,IAEF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,WAAW,GAAI,OAAM,MAAkB,KAAG,cAStD,CAAC"}

package/esm/lib/eventBus/eventBus.js

@@ -2,6 +2,7 @@ import { metrics, SpanKind, SpanStatusCode, trace } from '@opentelemetry/api';
 import EventEmitter from 'node:events';
 import { GenericException } from '../exception/genericException.js';
 import { getLogger } from '../log/logger.js';
+import { withRetry } from '../retry/withRetry.js';
 const tracer = trace.getTracer('nimbus');
 const meter = metrics.getMeter('nimbus');
 const eventsPublishedCounter = meter.createCounter('eventbus_events_published_total', {
@@ -301,35 +302,38 @@ export class NimbusEventBus {
                 }),
             },
         }, async (span) => {
-            let attempt = 0;
-            while (attempt <= maxRetries) {
-                try {
+            try {
+                await withRetry(async () => {
                     await handler(event);
-                    this._recordDeliveryMetrics(metricLabels, 'success', startTime);
-                    span.end();
-                    return;
-                }
-                catch (error) {
-                    attempt++;
-                    if (attempt > maxRetries) {
-                        this._handleFinalFailure({
-                            error,
-                            event,
-                            span,
-                            metricLabels,
-                            startTime,
-                            retryConfig: {
-                                maxRetries,
-                                baseDelay,
-                                maxDelay,
-                            },
+                }, {
+                    maxRetries,
+                    initialDelayMs: baseDelay,
+                    maxDelayMs: maxDelay,
+                    jitterFactor: useJitter ? 0.1 : 0,
+                    onRetry: ({ attempt, delayMs }) => {
+                        retryAttemptsCounter.add(1, metricLabels);
+                        span.addEvent('retry', {
+                            attempt,
+                            delay_ms: delayMs,
                         });
-                    }
-                    retryAttemptsCounter.add(1, metricLabels);
-                    const delayMs = this._calculateRetryDelay(attempt, baseDelay, maxDelay, useJitter);
-                    span.addEvent('retry', { attempt, delay_ms: delayMs });
-                    await new Promise((resolve) => setTimeout(resolve, delayMs));
-                }
+                    },
+                });
+                this._recordDeliveryMetrics(metricLabels, 'success', startTime);
+                span.end();
+            }
+            catch (error) {
+                this._handleFinalFailure({
+                    error,
+                    event,
+                    span,
+                    metricLabels,
+                    startTime,
+                    retryConfig: {
+                        maxRetries,
+                        baseDelay,
+                        maxDelay,
+                    },
+                });
             }
         });
     }
@@ -355,11 +359,6 @@ export class NimbusEventBus {
         }
         throw exception;
     }
-    _calculateRetryDelay(attempt, baseDelay, maxDelay, useJitter) {
-        const delay = Math.min(baseDelay * Math.pow(2, attempt - 1), maxDelay);
-        const jitter = useJitter ? Math.random() * delay * 0.1 : 0;
-        return delay + jitter;
-    }
     /**
      * Validate the size of the event and return the size in bytes.
      *

package/esm/lib/log/logTruncator.d.ts

@@ -0,0 +1,96 @@
+import type { LogInput } from './logger.js';
+/**
+ * Truncates a {@link LogInput} before it is turned into a log record.
+ *
+ * Use with {@link setupLogger} via the `truncator` option, or provide a custom
+ * implementation. The built-in factory is {@link createLogTruncator}.
+ */
+export type LogTruncator = (logInput: LogInput) => LogInput;
+/**
+ * Options for {@link createLogTruncator}.
+ *
+ * All fields are optional; omitted fields use the built-in defaults.
+ */
+export type LogTruncatorOptions = {
+    /**
+     * Maximum serialized byte size of `data` after structural truncation.
+     * If still over budget (or not JSON-serializable), `data` is replaced
+     * with a size marker. Defaults to 16_384 (16 KB).
+     */
+    maxBytes?: number;
+    /**
+     * Maximum number of array items kept inside `data` (also applies when
+     * converting `Map` / `Set` to arrays). Defaults to 50.
+     */
+    maxArrayItems?: number;
+    /**
+     * Maximum number of own enumerable keys kept on plain objects inside
+     * `data`. Defaults to 50.
+     */
+    maxObjectKeys?: number;
+    /**
+     * Maximum object nesting depth inside `data`, and maximum depth when
+     * walking `error.cause` / aggregate error chains.
+     * Defaults to 8. Values below 1 are clamped to 1 so root `data` stays
+     * an object.
+     */
+    maxDepth?: number;
+    /**
+     * Maximum length of `category`.
+     * Defaults to 50.
+     */
+    maxCategoryLength?: number;
+    /**
+     * Maximum length of `message` and `error.message`.
+     * Defaults to 200.
+     */
+    maxMessageLength?: number;
+    /**
+     * Maximum length of `error.stack`.
+     * Defaults to 200.
+     */
+    maxStackLength?: number;
+    /**
+     * Maximum length of string values inside `data`.
+     * Defaults to 200.
+     */
+    maxDataStringLength?: number;
+};
+/**
+ * Creates a {@link LogTruncator} that truncates each {@link LogInput} field
+ * separately (except `correlationId`, which is left untouched).
+ *
+ * - `message` / `category`: string length caps
+ * - `data`: structural truncation (arrays, objects, strings, depth, circular
+ *   refs, common JS types) plus a byte-size cliff that replaces oversized or
+ *   unserializable payloads with a size marker
+ * - `error`: stays `Error`-shaped; truncates `message` / `stack`, copies
+ *   enumerable custom fields, and walks `cause` / aggregate errors up to
+ *   `maxDepth`
+ *
+ * @param options - Optional limits; omitted fields use built-in defaults.
+ *
+ * @example
+ * ```ts
+ * import { createLogTruncator, setupLogger } from '@nimbus-cqrs/core';
+ *
+ * setupLogger({
+ *     truncator: createLogTruncator(),
+ * });
+ *
+ * setupLogger({
+ *     truncator: createLogTruncator({
+ *         maxBytes: 8_192,
+ *         maxArrayItems: 50,
+ *         maxObjectKeys: 50,
+ *         maxDepth: 8,
+ *         maxCategoryLength: 50,
+ *         maxMessageLength: 100,
+ *         maxStackLength: 200,
+ *         maxDataStringLength: 200,
+ *     }),
+ * });
+ * ```
+ */
+export declare const createLogTruncator: (options?: LogTruncatorOptions) => LogTruncator;
+//# sourceMappingURL=logTruncator.d.ts.map

package/esm/lib/log/logTruncator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logTruncator.d.ts","sourceRoot":"","sources":["../../../src/lib/log/logTruncator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,QAAQ,EAAE,QAAQ,KAAK,QAAQ,CAAC;AAE5D;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAChC,CAAC;AAsDF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,kBAAkB,GAC3B,UAAS,mBAAwB,KAClC,YA+TF,CAAC"}

package/esm/lib/log/logTruncator.js

@@ -0,0 +1,254 @@
+const DEFAULT_MAX_BYTES = 16_384;
+const DEFAULT_MAX_ARRAY_ITEMS = 50;
+const DEFAULT_MAX_OBJECT_KEYS = 50;
+const DEFAULT_MAX_DEPTH = 8;
+const DEFAULT_MAX_CATEGORY_LENGTH = 50;
+const DEFAULT_MAX_MESSAGE_LENGTH = 200;
+const DEFAULT_MAX_STACK_LENGTH = 200;
+const DEFAULT_MAX_DATA_STRING_LENGTH = 200;
+const serializedByteSize = (value) => {
+    try {
+        return new TextEncoder().encode(JSON.stringify(value)).byteLength;
+    }
+    catch {
+        return undefined;
+    }
+};
+const TRUNCATED_STRING_SUFFIX = ' [... __truncated]';
+const truncateString = (value, maxLength) => {
+    if (value.length <= maxLength) {
+        return value;
+    }
+    return `${value.slice(0, maxLength)}${TRUNCATED_STRING_SUFFIX}`;
+};
+/**
+ * Creates a {@link LogTruncator} that truncates each {@link LogInput} field
+ * separately (except `correlationId`, which is left untouched).
+ *
+ * - `message` / `category`: string length caps
+ * - `data`: structural truncation (arrays, objects, strings, depth, circular
+ *   refs, common JS types) plus a byte-size cliff that replaces oversized or
+ *   unserializable payloads with a size marker
+ * - `error`: stays `Error`-shaped; truncates `message` / `stack`, copies
+ *   enumerable custom fields, and walks `cause` / aggregate errors up to
+ *   `maxDepth`
+ *
+ * @param options - Optional limits; omitted fields use built-in defaults.
+ *
+ * @example
+ * ```ts
+ * import { createLogTruncator, setupLogger } from '@nimbus-cqrs/core';
+ *
+ * setupLogger({
+ *     truncator: createLogTruncator(),
+ * });
+ *
+ * setupLogger({
+ *     truncator: createLogTruncator({
+ *         maxBytes: 8_192,
+ *         maxArrayItems: 50,
+ *         maxObjectKeys: 50,
+ *         maxDepth: 8,
+ *         maxCategoryLength: 50,
+ *         maxMessageLength: 100,
+ *         maxStackLength: 200,
+ *         maxDataStringLength: 200,
+ *     }),
+ * });
+ * ```
+ */
+export const createLogTruncator = (options = {}) => {
+    // Clamp so root `data` stays an object and string/array limits stay usable.
+    const maxBytes = Math.max(0, options.maxBytes ?? DEFAULT_MAX_BYTES);
+    const maxArrayItems = Math.max(0, options.maxArrayItems ?? DEFAULT_MAX_ARRAY_ITEMS);
+    const maxObjectKeys = Math.max(0, options.maxObjectKeys ?? DEFAULT_MAX_OBJECT_KEYS);
+    const maxDepth = Math.max(1, options.maxDepth ?? DEFAULT_MAX_DEPTH);
+    const maxCategoryLength = Math.max(0, options.maxCategoryLength ?? DEFAULT_MAX_CATEGORY_LENGTH);
+    const maxMessageLength = Math.max(0, options.maxMessageLength ?? DEFAULT_MAX_MESSAGE_LENGTH);
+    const maxStackLength = Math.max(0, options.maxStackLength ?? DEFAULT_MAX_STACK_LENGTH);
+    const maxDataStringLength = Math.max(0, options.maxDataStringLength ?? DEFAULT_MAX_DATA_STRING_LENGTH);
+    const truncateDataValue = (value, depth, seen) => {
+        if (typeof value === 'bigint') {
+            return truncateString(`${value}n`, maxDataStringLength);
+        }
+        if (value === null || typeof value !== 'object') {
+            if (typeof value === 'string' &&
+                value.length > maxDataStringLength) {
+                return truncateString(value, maxDataStringLength);
+            }
+            return value;
+        }
+        if (seen.has(value)) {
+            return '[Circular]';
+        }
+        if (depth >= maxDepth) {
+            return '[Max depth]';
+        }
+        seen.add(value);
+        try {
+            if (value instanceof Date) {
+                return truncateString(value.toISOString(), maxDataStringLength);
+            }
+            if (value instanceof RegExp) {
+                return truncateString(value.toString(), maxDataStringLength);
+            }
+            if (value instanceof ArrayBuffer) {
+                return {
+                    __truncated: true,
+                    reason: 'arrayBuffer',
+                    byteLength: value.byteLength,
+                };
+            }
+            if (ArrayBuffer.isView(value)) {
+                return {
+                    __truncated: true,
+                    reason: 'typedArray',
+                    type: value.constructor.name,
+                    byteLength: value.byteLength,
+                };
+            }
+            if (value instanceof Error) {
+                return truncateErrorAsData(value, depth, seen);
+            }
+            if (value instanceof Map) {
+                return truncateDataValue(Array.from(value.entries()), depth + 1, seen);
+            }
+            if (value instanceof Set) {
+                return truncateDataValue(Array.from(value.values()), depth + 1, seen);
+            }
+            if (Array.isArray(value)) {
+                if (value.length > maxArrayItems) {
+                    return [
+                        ...value
+                            .slice(0, maxArrayItems)
+                            .map((item) => truncateDataValue(item, depth + 1, seen)),
+                        {
+                            __truncated: true,
+                            omittedCount: value.length - maxArrayItems,
+                        },
+                    ];
+                }
+                return value.map((item) => truncateDataValue(item, depth + 1, seen));
+            }
+            const entries = Object.entries(value);
+            const limited = entries.length > maxObjectKeys
+                ? entries.slice(0, maxObjectKeys)
+                : entries;
+            const result = {};
+            for (const [key, entry] of limited) {
+                result[key] = truncateDataValue(entry, depth + 1, seen);
+            }
+            if (entries.length > maxObjectKeys) {
+                result.__truncated = true;
+                result.omittedKeyCount = entries.length - maxObjectKeys;
+            }
+            return result;
+        }
+        finally {
+            // Recursion stack: allow shared refs, still detect true cycles.
+            seen.delete(value);
+        }
+    };
+    const truncateErrorAsData = (error, depth, seen) => {
+        const result = {
+            name: error.name,
+            message: truncateString(error.message, maxMessageLength),
+        };
+        if (typeof error.stack === 'string') {
+            result.stack = truncateString(error.stack, maxStackLength);
+        }
+        for (const [key, entry] of Object.entries(error)) {
+            if (key === 'name' ||
+                key === 'message' ||
+                key === 'stack' ||
+                key === 'cause' ||
+                key === 'errors') {
+                continue;
+            }
+            result[key] = truncateDataValue(entry, depth + 1, seen);
+        }
+        if ('cause' in error && error.cause !== undefined) {
+            result.cause = truncateDataValue(error.cause, depth + 1, seen);
+        }
+        if (typeof AggregateError !== 'undefined' &&
+            error instanceof AggregateError) {
+            result.errors = truncateDataValue(error.errors, depth + 1, seen);
+        }
+        return result;
+    };
+    const truncateData = (data) => {
+        const truncated = truncateDataValue(data, 0, new WeakSet());
+        const byteSize = serializedByteSize(truncated);
+        if (byteSize !== undefined && byteSize <= maxBytes) {
+            return truncated;
+        }
+        return {
+            __truncated: true,
+            reason: byteSize === undefined ? 'unserializable' : 'size',
+            ...(byteSize !== undefined ? { serializedByteSize: byteSize } : {}),
+            maxBytes,
+        };
+    };
+    const copyCustomErrorFields = (source, target, depth) => {
+        for (const [key, entry] of Object.entries(source)) {
+            if (key === 'name' ||
+                key === 'message' ||
+                key === 'stack' ||
+                key === 'cause' ||
+                key === 'errors') {
+                continue;
+            }
+            target[key] =
+                entry instanceof Error
+                    ? truncateError(entry, depth + 1)
+                    : truncateDataValue(entry, depth + 1, new WeakSet());
+        }
+    };
+    const truncateError = (error, depth) => {
+        if (depth >= maxDepth) {
+            const maxDepthError = new Error('[Max depth]');
+            maxDepthError.name = error.name;
+            return maxDepthError;
+        }
+        const message = truncateString(error.message, maxMessageLength);
+        let truncated;
+        if (typeof AggregateError !== 'undefined' &&
+            error instanceof AggregateError) {
+            truncated = new AggregateError(error.errors.map((item) => item instanceof Error
+                ? truncateError(item, depth + 1)
+                : truncateDataValue(item, depth + 1, new WeakSet())), message);
+        }
+        else {
+            truncated = new Error(message);
+        }
+        truncated.name = error.name;
+        if (typeof error.stack === 'string') {
+            truncated.stack = truncateString(error.stack, maxStackLength);
+        }
+        if ('cause' in error && error.cause !== undefined) {
+            truncated.cause = error.cause instanceof Error
+                ? truncateError(error.cause, depth + 1)
+                : truncateDataValue(error.cause, depth + 1, new WeakSet());
+        }
+        copyCustomErrorFields(error, truncated, depth);
+        return truncated;
+    };
+    return (logInput) => {
+        const truncated = {
+            message: truncateString(logInput.message, maxMessageLength),
+        };
+        if (logInput.category !== undefined) {
+            truncated.category = truncateString(logInput.category, maxCategoryLength);
+        }
+        if (logInput.data !== undefined) {
+            truncated.data = truncateData(logInput.data);
+        }
+        if (logInput.error !== undefined) {
+            truncated.error = truncateError(logInput.error, 0);
+        }
+        if (logInput.correlationId !== undefined) {
+            truncated.correlationId = logInput.correlationId;
+        }
+        return truncated;
+    };
+};

package/esm/lib/log/logger.d.ts

@@ -32,6 +32,12 @@ export type LogInput = {
      * Useful for tracking a request through multiple services or handlers.
      */
     correlationId?: string;
+    /**
+     * When `true`, skips the configured truncator for this log call.
+     * Useful for intentionally logging full payloads. Defaults to `false`.
+     * This flag is not included in the emitted log record.
+     */
+    skipTruncation?: boolean;
 };
 /**
  * A full log record with the log input and additional metadata attached.
@@ -80,6 +86,7 @@ export type LogRecord = {
  * @example
  * ```ts
  * import {
+ *     createLogTruncator,
  *     getLogger,
  *     jsonLogFormatter,
  *     parseLogLevel,
@@ -94,6 +101,7 @@ export type LogRecord = {
  *         ? jsonLogFormatter
  *         : prettyLogFormatter,
  *     useConsoleColors: process.env.NODE_ENV !== 'production',
+ *     truncator: createLogTruncator(),
  * });
  *
  * // Use the logger throughout your application
@@ -118,6 +126,7 @@ export declare class Logger {
     private readonly _logLevel;
     private readonly _formatter;
     private readonly _useConsoleColors;
+    private readonly _truncator?;
     constructor(options: LogOptions);
     /**
      * Configure the Logger.
@@ -125,6 +134,7 @@ export declare class Logger {
      * @param {LogOptions} options - The options for the Logger
      * @param {LogLevel} options.logLevel - The log level to use for the Logger
      * @param {LogFormatter} options.formatter - The formatter to use for the Logger
+     * @param {LogTruncator} options.truncator - Optional truncator for log inputs
      */
     static configure(options: LogOptions): void;
     /**
@@ -289,6 +299,14 @@ export declare class Logger {
      * @returns {string} The colorized string
      */
     private _colorizeString;
+    /**
+     * Apply the configured truncator, failing open if it throws.
+     *
+     * @param {LogInput} logInput - The original log input
+     *
+     * @returns {LogInput} The truncated log input, or the original on failure
+     */
+    private _applyTruncator;
     /**
      * Log a message.
      *
@@ -306,6 +324,7 @@ export declare class Logger {
  * @example
  * ```ts
  * import {
+ *     createLogTruncator,
  *     jsonLogFormatter,
  *     parseLogLevel,
  *     prettyLogFormatter,
@@ -319,6 +338,7 @@ export declare class Logger {
  *             ? prettyLogFormatter
  *             : jsonLogFormatter,
  *     useConsoleColors: process.env.NODE_ENV === "development",
+ *     truncator: createLogTruncator(),
  * });
  * ```
  */

package/esm/lib/log/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../src/lib/log/logger.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAE3D,OAAO,EAAE,KAAK,QAAQ,EAAmB,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAqB,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAElE;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG;IACnB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B;;;OAGG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC;IACd;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG;IACpB;;OAEG;IACH,SAAS,EAAE,IAAI,CAAC;IAChB;;OAEG;IACH,KAAK,EAAE,QAAQ,CAAC;IAChB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B;;OAEG;IACH,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;IAC1B;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,qBAAa,MAAM;IACf,OAAO,CAAC,MAAM,CAAC,SAAS,CAAS;IAEjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAW;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAe;IAC1C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAU;gBAEhC,OAAO,EAAE,UAAU;IAO/B;;;;;;OAMG;WACW,SAAS,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI;IAIlD;;;;OAIG;WACW,WAAW,IAAI,MAAM;IAQnC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACI,KAAK,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAMtC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACI,IAAI,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAMrC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACI,IAAI,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAMrC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACI,KAAK,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAMtC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACI,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAMzC;;;;;;;OAOG;IACH,OAAO,CAAC,iBAAiB;IAgBzB;;;;;;OAMG;IACH,OAAO,CAAC,gBAAgB;IAMxB;;;;;;;OAOG;IACH,OAAO,CAAC,eAAe;IAwBvB;;;;;;OAMG;IACH,OAAO,CAAC,IAAI;CAwBf;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,WAAW,GAAI,SAAS,UAAU,KAAG,IAEjD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,eAAO,MAAM,SAAS,QAAO,MAE5B,CAAC"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../src/lib/log/logger.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAE3D,OAAO,EAAE,KAAK,QAAQ,EAAmB,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAqB,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAGlE;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG;IACnB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B;;;OAGG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC;IACd;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC5B,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG;IACpB;;OAEG;IACH,SAAS,EAAE,IAAI,CAAC;IAChB;;OAEG;IACH,KAAK,EAAE,QAAQ,CAAC;IAChB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B;;OAEG;IACH,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;IAC1B;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,qBAAa,MAAM;IACf,OAAO,CAAC,MAAM,CAAC,SAAS,CAAS;IAEjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAW;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAe;IAC1C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAU;IAC5C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAe;gBAE/B,OAAO,EAAE,UAAU;IAQ/B;;;;;;;OAOG;WACW,SAAS,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI;IAIlD;;;;OAIG;WACW,WAAW,IAAI,MAAM;IAQnC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACI,KAAK,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAMtC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACI,IAAI,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAMrC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACI,IAAI,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAMrC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACI,KAAK,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAMtC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACI,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAMzC;;;;;;;OAOG;IACH,OAAO,CAAC,iBAAiB;IAgBzB;;;;;;OAMG;IACH,OAAO,CAAC,gBAAgB;IAMxB;;;;;;;OAOG;IACH,OAAO,CAAC,eAAe;IAwBvB;;;;;;OAMG;IACH,OAAO,CAAC,eAAe;IAgBvB;;;;;;OAMG;IACH,OAAO,CAAC,IAAI;CAyBf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,WAAW,GAAI,SAAS,UAAU,KAAG,IAEjD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,eAAO,MAAM,SAAS,QAAO,MAE5B,CAAC"}

package/esm/lib/log/logger.js

@@ -13,6 +13,7 @@ import { defaultLogOptions } from './options.js';
  * @example
  * ```ts
  * import {
+ *     createLogTruncator,
  *     getLogger,
  *     jsonLogFormatter,
  *     parseLogLevel,
@@ -27,6 +28,7 @@ import { defaultLogOptions } from './options.js';
  *         ? jsonLogFormatter
  *         : prettyLogFormatter,
  *     useConsoleColors: process.env.NODE_ENV !== 'production',
+ *     truncator: createLogTruncator(),
  * });
  *
  * // Use the logger throughout your application
@@ -51,11 +53,13 @@ export class Logger {
     _logLevel;
     _formatter;
     _useConsoleColors;
+    _truncator;
     constructor(options) {
         this._logLevel = options.logLevel ?? defaultLogOptions.logLevel;
         this._formatter = options.formatter ?? defaultLogOptions.formatter;
         this._useConsoleColors = options.useConsoleColors ??
             defaultLogOptions.useConsoleColors;
+        this._truncator = options.truncator ?? defaultLogOptions.truncator;
     }
     /**
      * Configure the Logger.
@@ -63,6 +67,7 @@ export class Logger {
      * @param {LogOptions} options - The options for the Logger
      * @param {LogLevel} options.logLevel - The log level to use for the Logger
      * @param {LogFormatter} options.formatter - The formatter to use for the Logger
+     * @param {LogTruncator} options.truncator - Optional truncator for log inputs
      */
     static configure(options) {
         Logger._instance = new Logger(options);
@@ -285,6 +290,25 @@ export class Logger {
         }
         return string;
     }
+    /**
+     * Apply the configured truncator, failing open if it throws.
+     *
+     * @param {LogInput} logInput - The original log input
+     *
+     * @returns {LogInput} The truncated log input, or the original on failure
+     */
+    _applyTruncator(logInput) {
+        if (!this._truncator || logInput.skipTruncation) {
+            return logInput;
+        }
+        try {
+            return this._truncator(logInput);
+        }
+        catch (error) {
+            console.warn('Log truncator failed; logging original input.', error);
+            return logInput;
+        }
+    }
     /**
      * Log a message.
      *
@@ -293,7 +317,8 @@ export class Logger {
      * @param {Function} logFunction - The log function
      */
     _log(logInput, logLevel, logFunction) {
-        const logRecord = this._produceLogRecord(logInput, logLevel);
+        const truncatedInput = this._applyTruncator(logInput);
+        const logRecord = this._produceLogRecord(truncatedInput, logLevel);
         const formattedLogRecord = this._formatLogRecord(logRecord);
         if (Array.isArray(formattedLogRecord)) {
             if (this._useConsoleColors) {
@@ -320,6 +345,7 @@ export class Logger {
  * @example
  * ```ts
  * import {
+ *     createLogTruncator,
  *     jsonLogFormatter,
  *     parseLogLevel,
  *     prettyLogFormatter,
@@ -333,6 +359,7 @@ export class Logger {
  *             ? prettyLogFormatter
  *             : jsonLogFormatter,
  *     useConsoleColors: process.env.NODE_ENV === "development",
+ *     truncator: createLogTruncator(),
  * });
  * ```
  */

package/esm/lib/log/options.d.ts

@@ -1,5 +1,6 @@
 import { type LogFormatter } from './logFormatter.js';
 import type { LogLevel } from './logLevel.js';
+import type { LogTruncator } from './logTruncator.js';
 /**
  * Configuration options for the Logger.
  *
@@ -26,9 +27,20 @@ export type LogOptions = {
      * Defaults to false.
      */
     useConsoleColors?: boolean;
+    /**
+     * Optional truncator applied to each {@link LogInput} before formatting.
+     * Use {@link createLogTruncator} for the built-in implementation, or supply a custom one.
+     * Defaults to undefined (no truncation).
+     */
+    truncator?: LogTruncator;
 };
 /**
  * The default log options.
  */
-export declare const defaultLogOptions: Required<LogOptions>;
+export declare const defaultLogOptions: {
+    logLevel: LogLevel;
+    formatter: LogFormatter;
+    useConsoleColors: boolean;
+    truncator?: LogTruncator;
+};
 //# sourceMappingURL=options.d.ts.map

package/esm/lib/log/options.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../../src/lib/log/options.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACxE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG;IACrB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,YAAY,CAAC;IACzB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC9B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,UAAU,CAIlD,CAAC"}
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../../src/lib/log/options.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACxE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG;IACrB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,YAAY,CAAC;IACzB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;OAIG;IACH,SAAS,CAAC,EAAE,YAAY,CAAC;CAC5B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE;IAC5B,QAAQ,EAAE,QAAQ,CAAC;IACnB,SAAS,EAAE,YAAY,CAAC;IACxB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,SAAS,CAAC,EAAE,YAAY,CAAC;CAK5B,CAAC"}

package/esm/lib/retry/withRetry.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Context passed to {@link WithRetryOptions.shouldRetry} and
+ * {@link WithRetryOptions.onRetry} after a failed attempt.
+ */
+export type RetryContext = {
+    /**
+     * The error thrown by the failed attempt.
+     */
+    error: Error;
+    /**
+     * The 1-based attempt number that failed.
+     */
+    attempt: number;
+    /**
+     * How many retries remain after this failure (not counting the
+     * attempt that just failed).
+     */
+    retriesLeft: number;
+    /**
+     * The delay in milliseconds before the next retry.
+     */
+    delayMs: number;
+};
+/**
+ * Options for {@link withRetry}.
+ */
+export type WithRetryOptions = {
+    /**
+     * Maximum number of retries after the initial attempt.
+     * Total attempts = `maxRetries + 1`. Defaults to `2`.
+     */
+    maxRetries?: number;
+    /**
+     * Base delay in milliseconds before the first retry. Subsequent
+     * retries scale exponentially by {@link factor}. Defaults to `1000`.
+     */
+    initialDelayMs?: number;
+    /**
+     * Cap for the exponential backoff delay in milliseconds (applied
+     * before jitter). Defaults to `30000`.
+     */
+    maxDelayMs?: number;
+    /**
+     * Exponential growth factor. Defaults to `2`.
+     */
+    factor?: number;
+    /**
+     * Fraction of the capped base delay added as random jitter
+     * (`0` disables jitter). Defaults to `0.1` (up to 10%).
+     */
+    jitterFactor?: number;
+    /**
+     * Optional wall-clock budget for the entire retry sequence,
+     * measured with `performance.now()`. When exceeded, the last
+     * error is thrown without further attempts.
+     */
+    maxRetryTimeMs?: number;
+    /**
+     * Abort signal that cancels waiting between retries and prevents
+     * further attempts.
+     */
+    signal?: AbortSignal;
+    /**
+     * Decide whether a failed attempt should be retried. Returning
+     * `false` rejects with the failure error immediately.
+     */
+    shouldRetry?: (context: RetryContext) => boolean | Promise<boolean>;
+    /**
+     * Called after a failed attempt when another retry will occur,
+     * before waiting for {@link RetryContext.delayMs}.
+     */
+    onRetry?: (context: RetryContext) => void | Promise<void>;
+};
+/**
+ * Options for {@link calculateBackoffDelay}.
+ */
+export type CalculateBackoffDelayOptions = {
+    /**
+     * Cap for the exponential base delay in milliseconds. Defaults to
+     * `Infinity` (no cap).
+     */
+    maxDelayMs?: number;
+    /**
+     * Exponential growth factor. Defaults to `2`.
+     */
+    factor?: number;
+    /**
+     * Fraction of the capped base delay added as random jitter
+     * (`0` disables jitter). Defaults to `0.1`.
+     */
+    jitterFactor?: number;
+};
+/**
+ * Error thrown from inside a {@link withRetry} operation to abort
+ * further retries immediately. The promise rejects with this error
+ * (or its cause message when constructed from another error).
+ *
+ * @example
+ * ```ts
+ * import { RetryAbortedError, withRetry } from '@nimbus-cqrs/core';
+ *
+ * await withRetry(async () => {
+ *     const response = await fetch(url);
+ *     if (response.status === 404) {
+ *         throw new RetryAbortedError('Resource not found');
+ *     }
+ *     return response.json();
+ * });
+ * ```
+ */
+export declare class RetryAbortedError extends Error {
+    /**
+     * Optional underlying error when constructed from an `Error`.
+     */
+    readonly cause?: Error;
+    constructor(messageOrError?: string | Error);
+}
+/**
+ * Calculates an exponential backoff delay with optional jitter and
+ * max-delay cap for a given retry attempt.
+ *
+ * @param initialDelayMs - Base delay in milliseconds before exponential
+ *   scaling.
+ * @param attempt - Zero-based retry attempt number (`0` for the first
+ *   retry after the initial failure).
+ * @param options - Optional factor, max delay, and jitter settings.
+ * @returns The backoff delay in milliseconds (integer).
+ *
+ * @example
+ * ```ts
+ * import { calculateBackoffDelay } from '@nimbus-cqrs/core';
+ *
+ * const delayMs = calculateBackoffDelay(1000, 0, {
+ *     maxDelayMs: 30_000,
+ *     jitterFactor: 0.1,
+ * });
+ * ```
+ */
+export declare const calculateBackoffDelay: (initialDelayMs: number, attempt: number, options?: CalculateBackoffDelayOptions) => number;
+/**
+ * Retries an async (or sync) function with exponential backoff until
+ * it succeeds, retries are exhausted, or retries are aborted.
+ *
+ * On exhaustion the last error is rethrown. Throw
+ * {@link RetryAbortedError} inside `fn` to stop retrying immediately.
+ * Pass an {@link AbortSignal} to cancel waiting between attempts.
+ *
+ * @param fn - Function to execute. Receives the 1-based attempt number.
+ * @param options - Retry, backoff, and callback options.
+ * @returns The fulfilled value of `fn`.
+ * @throws The last error after retries are exhausted, a
+ *   {@link RetryAbortedError}, or the abort signal reason.
+ *
+ * @example
+ * ```ts
+ * import { withRetry } from '@nimbus-cqrs/core';
+ *
+ * const data = await withRetry(
+ *     async (attempt) => {
+ *         console.log(`Attempt ${attempt}`);
+ *         return await fetch(url).then((r) => r.json());
+ *     },
+ *     {
+ *         maxRetries: 3,
+ *         initialDelayMs: 500,
+ *         maxDelayMs: 10_000,
+ *         onRetry: ({ attempt, delayMs, error }) => {
+ *             console.warn(`Retry ${attempt} in ${delayMs}ms`, error);
+ *         },
+ *     },
+ * );
+ * ```
+ */
+export declare const withRetry: <T>(fn: (attempt: number) => Promise<T> | T, options?: WithRetryOptions) => Promise<T>;
+//# sourceMappingURL=withRetry.d.ts.map

package/esm/lib/retry/withRetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"withRetry.d.ts","sourceRoot":"","sources":["../../../src/lib/retry/withRetry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG;IACvB;;OAEG;IACH,KAAK,EAAE,KAAK,CAAC;IACb;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC3B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;OAGG;IACH,WAAW,CAAC,EAAE,CACV,OAAO,EAAE,YAAY,KACpB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAChC;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7D,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,4BAA4B,GAAG;IACvC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAQF;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IACxC;;OAEG;IACH,SAAkB,KAAK,CAAC,EAAE,KAAK,CAAC;gBAEpB,cAAc,CAAC,EAAE,MAAM,GAAG,KAAK;CAc9C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,qBAAqB,GAC9B,gBAAgB,MAAM,EACtB,SAAS,MAAM,EACf,UAAS,4BAAiC,KAC3C,MAcF,CAAC;AA+CF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,SAAS,GAAU,CAAC,EAC7B,IAAI,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EACvC,UAAS,gBAAqB,KAC/B,OAAO,CAAC,CAAC,CAgFX,CAAC"}

package/esm/lib/retry/withRetry.js

@@ -0,0 +1,207 @@
+const DEFAULT_MAX_RETRIES = 2;
+const DEFAULT_INITIAL_DELAY_MS = 1000;
+const DEFAULT_MAX_DELAY_MS = 30_000;
+const DEFAULT_FACTOR = 2;
+const DEFAULT_JITTER_FACTOR = 0.1;
+/**
+ * Error thrown from inside a {@link withRetry} operation to abort
+ * further retries immediately. The promise rejects with this error
+ * (or its cause message when constructed from another error).
+ *
+ * @example
+ * ```ts
+ * import { RetryAbortedError, withRetry } from '@nimbus-cqrs/core';
+ *
+ * await withRetry(async () => {
+ *     const response = await fetch(url);
+ *     if (response.status === 404) {
+ *         throw new RetryAbortedError('Resource not found');
+ *     }
+ *     return response.json();
+ * });
+ * ```
+ */
+export class RetryAbortedError extends Error {
+    /**
+     * Optional underlying error when constructed from an `Error`.
+     */
+    cause;
+    constructor(messageOrError) {
+        const message = messageOrError instanceof Error
+            ? messageOrError.message
+            : (messageOrError ?? 'Retry aborted');
+        const cause = messageOrError instanceof Error
+            ? messageOrError
+            : undefined;
+        super(message, cause ? { cause } : undefined);
+        this.name = 'RetryAbortedError';
+        if (cause) {
+            this.cause = cause;
+        }
+    }
+}
+/**
+ * Calculates an exponential backoff delay with optional jitter and
+ * max-delay cap for a given retry attempt.
+ *
+ * @param initialDelayMs - Base delay in milliseconds before exponential
+ *   scaling.
+ * @param attempt - Zero-based retry attempt number (`0` for the first
+ *   retry after the initial failure).
+ * @param options - Optional factor, max delay, and jitter settings.
+ * @returns The backoff delay in milliseconds (integer).
+ *
+ * @example
+ * ```ts
+ * import { calculateBackoffDelay } from '@nimbus-cqrs/core';
+ *
+ * const delayMs = calculateBackoffDelay(1000, 0, {
+ *     maxDelayMs: 30_000,
+ *     jitterFactor: 0.1,
+ * });
+ * ```
+ */
+export const calculateBackoffDelay = (initialDelayMs, attempt, options = {}) => {
+    const factor = options.factor ?? DEFAULT_FACTOR;
+    const maxDelayMs = options.maxDelayMs ?? Infinity;
+    const jitterFactor = options.jitterFactor ?? DEFAULT_JITTER_FACTOR;
+    const baseDelay = Math.min(initialDelayMs * Math.pow(factor, attempt), maxDelayMs);
+    const jitter = jitterFactor > 0
+        ? Math.random() * baseDelay * jitterFactor
+        : 0;
+    return Math.floor(baseDelay + jitter);
+};
+const toError = (error) => error instanceof Error ? error : new Error(String(error));
+const getAbortReason = (signal) => {
+    if (signal.reason instanceof Error) {
+        return signal.reason;
+    }
+    if (typeof signal.reason === 'string' && signal.reason.length > 0) {
+        return new Error(signal.reason);
+    }
+    return new DOMException('The operation was aborted.', 'AbortError');
+};
+/**
+ * Returns a promise that resolves after `ms` milliseconds, or rejects
+ * early when {@link signal} is aborted.
+ */
+const delay = (ms, signal) => {
+    if (ms <= 0) {
+        if (signal?.aborted) {
+            return Promise.reject(getAbortReason(signal));
+        }
+        return Promise.resolve();
+    }
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(getAbortReason(signal));
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(getAbortReason(signal));
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+};
+/**
+ * Retries an async (or sync) function with exponential backoff until
+ * it succeeds, retries are exhausted, or retries are aborted.
+ *
+ * On exhaustion the last error is rethrown. Throw
+ * {@link RetryAbortedError} inside `fn` to stop retrying immediately.
+ * Pass an {@link AbortSignal} to cancel waiting between attempts.
+ *
+ * @param fn - Function to execute. Receives the 1-based attempt number.
+ * @param options - Retry, backoff, and callback options.
+ * @returns The fulfilled value of `fn`.
+ * @throws The last error after retries are exhausted, a
+ *   {@link RetryAbortedError}, or the abort signal reason.
+ *
+ * @example
+ * ```ts
+ * import { withRetry } from '@nimbus-cqrs/core';
+ *
+ * const data = await withRetry(
+ *     async (attempt) => {
+ *         console.log(`Attempt ${attempt}`);
+ *         return await fetch(url).then((r) => r.json());
+ *     },
+ *     {
+ *         maxRetries: 3,
+ *         initialDelayMs: 500,
+ *         maxDelayMs: 10_000,
+ *         onRetry: ({ attempt, delayMs, error }) => {
+ *             console.warn(`Retry ${attempt} in ${delayMs}ms`, error);
+ *         },
+ *     },
+ * );
+ * ```
+ */
+export const withRetry = async (fn, options = {}) => {
+    const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    const initialDelayMs = options.initialDelayMs ?? DEFAULT_INITIAL_DELAY_MS;
+    const maxDelayMs = options.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+    const factor = options.factor ?? DEFAULT_FACTOR;
+    const jitterFactor = options.jitterFactor ?? DEFAULT_JITTER_FACTOR;
+    const maxRetryTimeMs = options.maxRetryTimeMs;
+    const signal = options.signal;
+    const startedAt = performance.now();
+    let attempt = 0;
+    while (true) {
+        if (signal?.aborted) {
+            throw getAbortReason(signal);
+        }
+        attempt++;
+        try {
+            return await fn(attempt);
+        }
+        catch (error) {
+            if (error instanceof RetryAbortedError) {
+                throw error;
+            }
+            const err = toError(error);
+            const retriesLeft = maxRetries + 1 - attempt;
+            if (retriesLeft <= 0) {
+                throw err;
+            }
+            if (maxRetryTimeMs !== undefined &&
+                performance.now() - startedAt >= maxRetryTimeMs) {
+                throw err;
+            }
+            let delayMs = calculateBackoffDelay(initialDelayMs, attempt - 1, { maxDelayMs, factor, jitterFactor });
+            if (maxRetryTimeMs !== undefined) {
+                const remainingMs = maxRetryTimeMs -
+                    (performance.now() - startedAt);
+                // floor() can turn a sub-millisecond remainder into 0.
+                // delay(0) is a no-op, so sync failures would otherwise
+                // burn through every remaining retry without ever
+                // advancing past maxRetryTimeMs.
+                if (remainingMs < 1) {
+                    throw err;
+                }
+                delayMs = Math.min(delayMs, Math.floor(remainingMs));
+            }
+            const context = {
+                error: err,
+                attempt,
+                retriesLeft,
+                delayMs,
+            };
+            if (options.shouldRetry) {
+                const shouldRetry = await options.shouldRetry(context);
+                if (!shouldRetry) {
+                    throw err;
+                }
+            }
+            if (options.onRetry) {
+                await options.onRetry(context);
+            }
+            await delay(delayMs, signal);
+        }
+    }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nimbus-cqrs/core",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Simplify Event-Driven Applications - Core building blocks of the Nimbus framework.",
   "keywords": [
     "nimbus",