@nimbus-cqrs/core 2.1.2 → 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/exception/exception.d.ts

@@ -5,6 +5,6 @@ export declare class Exception extends Error {
     details?: Record<string, unknown>;
     statusCode?: number;
     constructor(name: string, message: string, details?: Record<string, unknown>, statusCode?: number);
-    fromError(error: Error): Exception;
+    fromError(error: Error): this;
 }
 //# sourceMappingURL=exception.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"exception.d.ts","sourceRoot":"","sources":["../../../src/lib/exception/exception.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,SAAU,SAAQ,KAAK;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;gBAGvB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,UAAU,CAAC,EAAE,MAAM;IAmBhB,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS;CAM5C"}
+{"version":3,"file":"exception.d.ts","sourceRoot":"","sources":["../../../src/lib/exception/exception.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,SAAU,SAAQ,KAAK;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;gBAGvB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,UAAU,CAAC,EAAE,MAAM;IAmBhB,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;CAMvC"}

package/esm/lib/exception/invalidInputException.d.ts

@@ -13,6 +13,6 @@ export declare class InvalidInputException extends Exception {
      *
      * @returns {InvalidInputException} The InvalidInputException.
      */
-    fromZodError(error: ZodError): InvalidInputException;
+    fromZodError(error: ZodError): this;
 }
 //# sourceMappingURL=invalidInputException.d.ts.map

package/esm/lib/exception/invalidInputException.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"invalidInputException.d.ts","sourceRoot":"","sources":["../../../src/lib/exception/invalidInputException.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,SAAS;gBACpC,OAAO,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAS/D;;;;;;;OAOG;IACI,YAAY,CAAC,KAAK,EAAE,QAAQ,GAAG,qBAAqB;CAa9D"}
+{"version":3,"file":"invalidInputException.d.ts","sourceRoot":"","sources":["../../../src/lib/exception/invalidInputException.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,SAAS;gBACpC,OAAO,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAS/D;;;;;;;OAOG;IACI,YAAY,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;CAa7C"}

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;
+    };
+};