@cqrs-ddd/pipeline-correlation 0.5.0

package/dist/decorators/with-correlation.decorator.js

@@ -0,0 +1,85 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { untyped } from '@cqrs-ddd/untyped';
+import { DEFAULT_CORRELATION_HEADER } from '../constants/correlation.constants.js';
+import { getCorrelationId, runWithCorrelationId, } from '../correlation.store.js';
+import { methodDecorator, } from '../helpers/method-decorator.js';
+import { dyn } from '../types/safe-typing.js';
+/**
+ * Resolve a dot-notation path on an object.
+ * Returns `undefined` for any missing segment or non-string leaf.
+ *
+ * @internal
+ */
+function getByPath(obj, path) {
+    let current = untyped(obj);
+    for (const segment of path.split('.')) {
+        if (current == null)
+            return undefined;
+        current = untyped(current[segment]);
+    }
+    return typeof current === 'string' ? current : undefined;
+}
+export function WithCorrelation(pathOrOptions) {
+    const options = typeof pathOrOptions === 'string'
+        ? { path: pathOrOptions }
+        : (pathOrOptions ?? {});
+    const { path = 'data.correlationId', extract } = options;
+    return methodDecorator((originalMethod, _propertyKey) => {
+        return function (...args) {
+            const logger = options.logger ??
+                untyped(this)?.logger ??
+                console;
+            if (!extract && Array.isArray(args[0])) {
+                logger.warn(`${untyped(this).constructor?.name}.${String(_propertyKey)}: first argument is an array — ` +
+                    `dot-path "${path}" cannot extract a correlation ID from it. ` +
+                    `Use the 'extract' option for array payloads.`);
+            }
+            const correlationId = extract
+                ? extract(...args)
+                : getByPath(args[0], path);
+            return runWithCorrelationId(correlationId, () => {
+                if (options.logLevel !== 'none') {
+                    const level = options.logLevel ?? 'debug';
+                    const method = logger[level];
+                    if (typeof method === 'function') {
+                        method.call(logger, `🔗 Starting ${untyped(this).constructor?.name}.${String(_propertyKey)} with correlationId: ${getCorrelationId()}`);
+                    }
+                }
+                return originalMethod.apply(this, args);
+            });
+        };
+    });
+}
+/**
+ * Pre-built extraction presets for {@link WithCorrelation}, for transports whose
+ * handlers receive the correlation id in metadata rather than in the payload.
+ *
+ * For transports that carry it in the payload (BullMQ, PostgreSQL NOTIFY), use
+ * the bare `@WithCorrelation()` or a `path`; for any other shape, an `extract`
+ * function.
+ *
+ * @example
+ * ```ts
+ * class Users {
+ *   // gRPC (@grpc/grpc-js): (request, metadata)
+ *   @WithCorrelation(CorrelationFrom.grpc())
+ *   async findOne(request: FindOneRequest, metadata: Metadata) {}
+ * }
+ * ```
+ */
+export const CorrelationFrom = {
+    /**
+     * gRPC — extracts from gRPC `Metadata` (second argument).
+     *
+     * In gRPC handlers the signature is `(data, metadata, call)`.
+     *
+     * @param key - Metadata key. Defaults to `'x-correlation-id'`.
+     */
+    grpc: (key = DEFAULT_CORRELATION_HEADER) => ({
+        extract: (_data, metadata) => {
+            const values = dyn(metadata)?.get?.(key);
+            return values?.[0]?.toString();
+        },
+    }),
+};
+//# sourceMappingURL=with-correlation.decorator.js.map

package/dist/decorators/with-correlation.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-correlation.decorator.js","sourceRoot":"","sources":["../../src/decorators/with-correlation.decorator.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAC5C,OAAO,EAAE,0BAA0B,EAAE,MAAM,uCAAuC,CAAC;AACnF,OAAO,EACL,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAEL,eAAe,GAChB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,GAAG,EAAE,MAAM,yBAAyB,CAAC;AAqG9C;;;;;GAKG;AACH,SAAS,SAAS,CAAC,GAAY,EAAE,IAAY;IAC3C,IAAI,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC3B,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACtC,IAAI,OAAO,IAAI,IAAI;YAAE,OAAO,SAAS,CAAC;QACtC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;IACtC,CAAC;IACD,OAAO,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAE,OAAkB,CAAC,CAAC,CAAC,SAAS,CAAC;AACvE,CAAC;AAmED,MAAM,UAAU,eAAe,CAC7B,aAAoD;IAEpD,MAAM,OAAO,GACX,OAAO,aAAa,KAAK,QAAQ;QAC/B,CAAC,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE;QACzB,CAAC,CAAC,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC;IAE5B,MAAM,EAAE,IAAI,GAAG,oBAAoB,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAEzD,OAAO,eAAe,CAAC,CAAC,cAAc,EAAE,YAAY,EAAE,EAAE;QACtD,OAAO,UAAyB,GAAG,IAAe;YAChD,MAAM,MAAM,GACV,OAAO,CAAC,MAAM;gBACb,OAAO,CAAC,IAAI,CAAC,EAAE,MAAwC;gBACxD,OAAO,CAAC;YAEV,IAAI,CAAC,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBACvC,MAAM,CAAC,IAAI,CACT,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,IAAI,IAAI,MAAM,CAAC,YAAY,CAAC,iCAAiC;oBACzF,aAAa,IAAI,6CAA6C;oBAC9D,8CAA8C,CACjD,CAAC;YACJ,CAAC;YAED,MAAM,aAAa,GAAG,OAAO;gBAC3B,CAAC,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;gBAClB,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;YAE7B,OAAO,oBAAoB,CAAC,aAAa,EAAE,GAAG,EAAE;gBAC9C,IAAI,OAAO,CAAC,QAAQ,KAAK,MAAM,EAAE,CAAC;oBAChC,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC;oBAC1C,MAAM,MAAM,GAAG,MAAM,CAAC,KAAgC,CAAC,CAAC;oBACxD,IAAI,OAAO,MAAM,KAAK,UAAU,EAAE,CAAC;wBAChC,MAAgC,CAAC,IAAI,CACpC,MAAM,EACN,eAAe,OAAO,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,IAAI,IAAI,MAAM,CAAC,YAAY,CAAC,wBAAwB,gBAAgB,EAAE,EAAE,CACnH,CAAC;oBACJ,CAAC;gBACH,CAAC;gBACD,OAAO,cAAc,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAC1C,CAAC,CAAC,CAAC;QACL,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B;;;;;;OAMG;IACH,IAAI,EAAE,CAAC,GAAG,GAAG,0BAA0B,EAA+B,EAAE,CAAC,CAAC;QACxE,OAAO,EAAE,CAAC,KAAc,EAAE,QAAiB,EAAE,EAAE;YAC7C,MAAM,MAAM,GAAG,GAAG,CAAC,QAAQ,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;YACzC,OAAO,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC;QACjC,CAAC;KACF,CAAC;CACM,CAAC"}

package/dist/helpers/method-decorator.d.ts

@@ -0,0 +1,13 @@
+type AnyMethod = (this: unknown, ...args: any[]) => unknown;
+/** A method decorator for the standard and the `experimentalDecorators` mode. */
+export interface DualMethodDecorator {
+    <F extends AnyMethod>(method: F, context: ClassMethodDecoratorContext): F;
+    (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor;
+}
+/**
+ * Builds a decorator that replaces a method with `replace(method, name)`, keeping the
+ * method's own name for stack traces.
+ */
+export declare function methodDecorator(replace: (method: AnyMethod, name: string) => AnyMethod): DualMethodDecorator;
+export {};
+//# sourceMappingURL=method-decorator.d.ts.map

package/dist/helpers/method-decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"method-decorator.d.ts","sourceRoot":"","sources":["../../src/helpers/method-decorator.ts"],"names":[],"mappings":"AAGA,KAAK,SAAS,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC;AAE5D,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IAClC,CAAC,CAAC,SAAS,SAAS,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,2BAA2B,GAAG,CAAC,CAAC;IAC1E,CACE,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAAG,MAAM,EAC5B,UAAU,EAAE,kBAAkB,GAC7B,kBAAkB,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,KAAK,SAAS,GACtD,mBAAmB,CAiBrB"}

package/dist/helpers/method-decorator.js

@@ -0,0 +1,24 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+/**
+ * Builds a decorator that replaces a method with `replace(method, name)`, keeping the
+ * method's own name for stack traces.
+ */
+export function methodDecorator(replace) {
+    const replaced = (method, name) => {
+        const replacement = replace(method, name);
+        Object.defineProperty(replacement, 'name', {
+            value: method.name,
+            configurable: true,
+        });
+        return replacement;
+    };
+    return ((target, key, descriptor) => {
+        if (typeof key === 'object' && key !== null && 'name' in key) {
+            return replaced(target, String(key.name));
+        }
+        const property = descriptor;
+        property.value = replaced(property.value, String(key));
+        return property;
+    });
+}
+//# sourceMappingURL=method-decorator.js.map

package/dist/helpers/method-decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"method-decorator.js","sourceRoot":"","sources":["../../src/helpers/method-decorator.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAetE;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAuD;IAEvD,MAAM,QAAQ,GAAG,CAAC,MAAiB,EAAE,IAAY,EAAE,EAAE;QACnD,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAC1C,MAAM,CAAC,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE;YACzC,KAAK,EAAE,MAAM,CAAC,IAAI;YAClB,YAAY,EAAE,IAAI;SACnB,CAAC,CAAC;QACH,OAAO,WAAW,CAAC;IACrB,CAAC,CAAC;IACF,OAAO,CAAC,CAAC,MAAe,EAAE,GAAY,EAAE,UAA+B,EAAE,EAAE;QACzE,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,MAAM,IAAI,GAAG,EAAE,CAAC;YAC7D,OAAO,QAAQ,CAAC,MAAmB,EAAE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;QACzD,CAAC;QACD,MAAM,QAAQ,GAAG,UAAgC,CAAC;QAClD,QAAQ,CAAC,KAAK,GAAG,QAAQ,CAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QACvD,OAAO,QAAQ,CAAC;IAClB,CAAC,CAAwB,CAAC;AAC5B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { DEFAULT_CORRELATION_HEADER } from './constants/correlation.constants.js';
+export type { WithCorrelationId } from './correlation.store.js';
+export { addCorrelationId, correlationHeaders, correlationSource, getCorrelationId, runWithCorrelationId, } from './correlation.store.js';
+export type { CorrelationDecoratorOptions, CorrelationExtractor, CorrelationLogger, LogLevel, } from './decorators/with-correlation.decorator.js';
+export { CorrelationFrom, WithCorrelation, } from './decorators/with-correlation.decorator.js';
+export { type HttpMiddleware, httpCorrelation, } from './middlewares/http-correlation.middleware.js';
+export type { CorrelationOptions } from './options/correlation.options.js';
+export { DEFAULT_CORRELATION_ID_MAX_LENGTH, DEFAULT_CORRELATION_ID_PATTERN, } from './options/correlation.options.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,0BAA0B,EAAE,MAAM,sCAAsC,CAAC;AAClF,YAAY,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,2BAA2B,EAC3B,oBAAoB,EACpB,iBAAiB,EACjB,QAAQ,GACT,MAAM,4CAA4C,CAAC;AACpD,OAAO,EACL,eAAe,EACf,eAAe,GAChB,MAAM,4CAA4C,CAAC;AACpD,OAAO,EACL,KAAK,cAAc,EACnB,eAAe,GAChB,MAAM,8CAA8C,CAAC;AACtD,YAAY,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAC3E,OAAO,EACL,iCAAiC,EACjC,8BAA8B,GAC/B,MAAM,kCAAkC,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+export { DEFAULT_CORRELATION_HEADER } from './constants/correlation.constants.js';
+export { addCorrelationId, correlationHeaders, correlationSource, getCorrelationId, runWithCorrelationId, } from './correlation.store.js';
+export { CorrelationFrom, WithCorrelation, } from './decorators/with-correlation.decorator.js';
+export { httpCorrelation, } from './middlewares/http-correlation.middleware.js';
+export { DEFAULT_CORRELATION_ID_MAX_LENGTH, DEFAULT_CORRELATION_ID_PATTERN, } from './options/correlation.options.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE,OAAO,EAAE,0BAA0B,EAAE,MAAM,sCAAsC,CAAC;AAElF,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,wBAAwB,CAAC;AAOhC,OAAO,EACL,eAAe,EACf,eAAe,GAChB,MAAM,4CAA4C,CAAC;AACpD,OAAO,EAEL,eAAe,GAChB,MAAM,8CAA8C,CAAC;AAEtD,OAAO,EACL,iCAAiC,EACjC,8BAA8B,GAC/B,MAAM,kCAAkC,CAAC"}

package/dist/middlewares/http-correlation.middleware.d.ts

@@ -0,0 +1,25 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type CorrelationOptions } from '../options/correlation.options.js';
+/** A Node `http` middleware: Express and Connect take it as it is. */
+export type HttpMiddleware = (req: IncomingMessage, res: ServerResponse, next: () => void) => void;
+/**
+ * An HTTP middleware that takes the correlation id from the incoming request header and
+ * runs the rest of the request with it ({@link runWithCorrelationId}), so pipelines
+ * that the request starts take it. It echoes the id on the response header.
+ *
+ * The header name defaults to `x-correlation-id`. If `header` is omitted or is any
+ * non-string value (including `false`), the default header is used.
+ *
+ * An incoming id longer than 128 characters or outside the default character set is
+ * replaced by a local id. `acceptIncoming`, `trimIncoming`, `maxLength` and
+ * `validateIncoming` adjust that policy.
+ *
+ * @throws TypeError when `header` is not a valid HTTP field name, or `maxLength` is not
+ *   a positive safe integer.
+ * @example Express
+ * ```ts
+ * app.use(httpCorrelation({ trimIncoming: true, validateIncoming: (id) => id.startsWith('edge:') }));
+ * ```
+ */
+export declare function httpCorrelation(options?: CorrelationOptions): HttpMiddleware;
+//# sourceMappingURL=http-correlation.middleware.d.ts.map

package/dist/middlewares/http-correlation.middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-correlation.middleware.d.ts","sourceRoot":"","sources":["../../src/middlewares/http-correlation.middleware.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAMjE,OAAO,EACL,KAAK,kBAAkB,EAGxB,MAAM,mCAAmC,CAAC;AAI3C,sEAAsE;AACtE,MAAM,MAAM,cAAc,GAAG,CAC3B,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,cAAc,EACnB,IAAI,EAAE,MAAM,IAAI,KACb,IAAI,CAAC;AAEV;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,cAAc,CA2C5E"}

package/dist/middlewares/http-correlation.middleware.js

@@ -0,0 +1,63 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { DEFAULT_CORRELATION_HEADER } from '../constants/correlation.constants.js';
+import { getCorrelationId, runWithCorrelationId, } from '../correlation.store.js';
+import { DEFAULT_CORRELATION_ID_MAX_LENGTH, DEFAULT_CORRELATION_ID_PATTERN, } from '../options/correlation.options.js';
+const HTTP_FIELD_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+/**
+ * An HTTP middleware that takes the correlation id from the incoming request header and
+ * runs the rest of the request with it ({@link runWithCorrelationId}), so pipelines
+ * that the request starts take it. It echoes the id on the response header.
+ *
+ * The header name defaults to `x-correlation-id`. If `header` is omitted or is any
+ * non-string value (including `false`), the default header is used.
+ *
+ * An incoming id longer than 128 characters or outside the default character set is
+ * replaced by a local id. `acceptIncoming`, `trimIncoming`, `maxLength` and
+ * `validateIncoming` adjust that policy.
+ *
+ * @throws TypeError when `header` is not a valid HTTP field name, or `maxLength` is not
+ *   a positive safe integer.
+ * @example Express
+ * ```ts
+ * app.use(httpCorrelation({ trimIncoming: true, validateIncoming: (id) => id.startsWith('edge:') }));
+ * ```
+ */
+export function httpCorrelation(options) {
+    const h = options?.header;
+    if (typeof h === 'string' && !HTTP_FIELD_NAME.test(h)) {
+        throw new TypeError(`Invalid correlation HTTP header name: "${h}".`);
+    }
+    if (options?.maxLength !== undefined &&
+        (!Number.isSafeInteger(options.maxLength) || options.maxLength <= 0)) {
+        throw new TypeError('Correlation maxLength must be a positive safe integer when provided.');
+    }
+    const header = typeof h === 'string' ? h.toLowerCase() : DEFAULT_CORRELATION_HEADER;
+    const acceptIncoming = options?.acceptIncoming ?? true;
+    const trimIncoming = options?.trimIncoming ?? false;
+    const maxLength = options?.maxLength ?? DEFAULT_CORRELATION_ID_MAX_LENGTH;
+    const validateIncoming = options?.validateIncoming ??
+        ((id) => DEFAULT_CORRELATION_ID_PATTERN.test(id));
+    const resolveIncoming = (raw) => {
+        if (!acceptIncoming || typeof raw !== 'string')
+            return undefined;
+        const value = trimIncoming ? raw.trim() : raw;
+        if (value.length === 0 || value.length > maxLength)
+            return undefined;
+        try {
+            return validateIncoming(value) ? value : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    return (req, res, next) => {
+        const raw = req.headers?.[header];
+        const candidate = Array.isArray(raw) ? raw[0] : raw;
+        const correlationId = resolveIncoming(candidate) ?? getCorrelationId();
+        if (typeof res?.setHeader === 'function') {
+            res.setHeader(header, correlationId);
+        }
+        runWithCorrelationId(correlationId, next);
+    };
+}
+//# sourceMappingURL=http-correlation.middleware.js.map

package/dist/middlewares/http-correlation.middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-correlation.middleware.js","sourceRoot":"","sources":["../../src/middlewares/http-correlation.middleware.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAGtE,OAAO,EAAE,0BAA0B,EAAE,MAAM,uCAAuC,CAAC;AACnF,OAAO,EACL,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAEL,iCAAiC,EACjC,8BAA8B,GAC/B,MAAM,mCAAmC,CAAC;AAE3C,MAAM,eAAe,GAAG,gCAAgC,CAAC;AASzD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,eAAe,CAAC,OAA4B;IAC1D,MAAM,CAAC,GAAG,OAAO,EAAE,MAAM,CAAC;IAC1B,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QACtD,MAAM,IAAI,SAAS,CAAC,0CAA0C,CAAC,IAAI,CAAC,CAAC;IACvE,CAAC;IACD,IACE,OAAO,EAAE,SAAS,KAAK,SAAS;QAChC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,OAAO,CAAC,SAAS,IAAI,CAAC,CAAC,EACpE,CAAC;QACD,MAAM,IAAI,SAAS,CACjB,sEAAsE,CACvE,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GACV,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,0BAA0B,CAAC;IACvE,MAAM,cAAc,GAAG,OAAO,EAAE,cAAc,IAAI,IAAI,CAAC;IACvD,MAAM,YAAY,GAAG,OAAO,EAAE,YAAY,IAAI,KAAK,CAAC;IACpD,MAAM,SAAS,GAAG,OAAO,EAAE,SAAS,IAAI,iCAAiC,CAAC;IAC1E,MAAM,gBAAgB,GACpB,OAAO,EAAE,gBAAgB;QACzB,CAAC,CAAC,EAAU,EAAE,EAAE,CAAC,8BAA8B,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;IAE5D,MAAM,eAAe,GAAG,CAAC,GAAuB,EAAsB,EAAE;QACtE,IAAI,CAAC,cAAc,IAAI,OAAO,GAAG,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QACjE,MAAM,KAAK,GAAG,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;QAC9C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,SAAS;YAAE,OAAO,SAAS,CAAC;QACrE,IAAI,CAAC;YACH,OAAO,gBAAgB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;QACrD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC,CAAC;IAEF,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QACxB,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,EAAE,CAAC,MAAM,CAAC,CAAC;QAClC,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;QACpD,MAAM,aAAa,GAAG,eAAe,CAAC,SAAS,CAAC,IAAI,gBAAgB,EAAE,CAAC;QACvE,IAAI,OAAO,GAAG,EAAE,SAAS,KAAK,UAAU,EAAE,CAAC;YACzC,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;QACvC,CAAC;QACD,oBAAoB,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;IAC5C,CAAC,CAAC;AACJ,CAAC"}

package/dist/options/correlation.options.d.ts

@@ -0,0 +1,91 @@
+/** Default upper bound for an accepted incoming correlation ID. */
+export declare const DEFAULT_CORRELATION_ID_MAX_LENGTH = 128;
+/**
+ * Characters accepted in an incoming correlation ID unless `validateIncoming`
+ * is configured: letters, digits and `. _ ~ : / + = @ -`, which covers UUIDs,
+ * W3C trace identifiers and common request-ID formats.
+ */
+export declare const DEFAULT_CORRELATION_ID_PATTERN: RegExp;
+/**
+ * Correlation ID configuration consumed by {@link httpCorrelation}.
+ *
+ * The middleware is registered explicitly by the application. For non-HTTP
+ * transports (Bull, RabbitMQ, etc.), use `runWithCorrelationId()` directly in
+ * your processor/handler.
+ *
+ * An incoming header value is accepted only when it is at most
+ * {@link DEFAULT_CORRELATION_ID_MAX_LENGTH} characters and matches
+ * {@link DEFAULT_CORRELATION_ID_PATTERN}; otherwise a local ID is used.
+ * `maxLength` and `validateIncoming` replace these defaults.
+ *
+ * @example
+ * ```ts
+ * // Custom header name
+ * { header: 'x-request-id' }
+ *
+ * // `header: false` selects the default header; it does not disable the middleware.
+ * { header: false } // uses 'x-correlation-id'
+ * ```
+ *
+ * @example Accept only UUIDs from clients
+ * ```ts
+ * {
+ *   maxLength: 36,
+ *   trimIncoming: true,
+ *   validateIncoming: (id) => /^[0-9a-f-]{36}$/i.test(id),
+ * }
+ * ```
+ *
+ * @example Ignore client IDs completely and always generate/use the local ID
+ * ```ts
+ * { acceptIncoming: false }
+ * ```
+ */
+export interface CorrelationOptions {
+    /**
+     * HTTP header name to extract the correlation ID from.
+     * A valid, non-empty HTTP field-name string selects that header. Invalid
+     * strings throw during middleware construction. Any non-string value, including `false` and
+     * `undefined`, makes the middleware use the default `x-correlation-id` header.
+     *
+     * @default 'x-correlation-id'
+     */
+    header?: string | false;
+    /**
+     * Whether a non-empty incoming correlation ID may be used.
+     * Set to `false` when correlation IDs are internal-only and should never be
+     * controlled by the HTTP client.
+     *
+     * @default true
+     */
+    acceptIncoming?: boolean;
+    /**
+     * Trim surrounding whitespace before optional length/custom validation and
+     * before storing/echoing the ID.
+     *
+     * @default false
+     */
+    trimIncoming?: boolean;
+    /**
+     * Maximum accepted incoming correlation-ID length. Longer values are
+     * discarded and replaced by the locally resolved/generated ID.
+     *
+     * @default 128
+     */
+    maxLength?: number;
+    /**
+     * Validation predicate for incoming IDs; replaces the default
+     * {@link DEFAULT_CORRELATION_ID_PATTERN} check. Returning `false` (or
+     * throwing) rejects the incoming value and falls back to the local
+     * correlation ID. `maxLength` still applies.
+     *
+     * @example
+     * ```ts
+     * {
+     *   validateIncoming: (id) => /^[A-Za-z0-9._-]+$/.test(id),
+     * }
+     * ```
+     */
+    validateIncoming?: (correlationId: string) => boolean;
+}
+//# sourceMappingURL=correlation.options.d.ts.map

package/dist/options/correlation.options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlation.options.d.ts","sourceRoot":"","sources":["../../src/options/correlation.options.ts"],"names":[],"mappings":"AAEA,mEAAmE;AACnE,eAAO,MAAM,iCAAiC,MAAM,CAAC;AAErD;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,QAA4B,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAExB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;;;;;;;OAYG;IACH,gBAAgB,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC;CACvD"}

package/dist/options/correlation.options.js

@@ -0,0 +1,10 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+/** Default upper bound for an accepted incoming correlation ID. */
+export const DEFAULT_CORRELATION_ID_MAX_LENGTH = 128;
+/**
+ * Characters accepted in an incoming correlation ID unless `validateIncoming`
+ * is configured: letters, digits and `. _ ~ : / + = @ -`, which covers UUIDs,
+ * W3C trace identifiers and common request-ID formats.
+ */
+export const DEFAULT_CORRELATION_ID_PATTERN = /^[A-Za-z0-9._~:/+=@-]+$/;
+//# sourceMappingURL=correlation.options.js.map

package/dist/options/correlation.options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlation.options.js","sourceRoot":"","sources":["../../src/options/correlation.options.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE,mEAAmE;AACnE,MAAM,CAAC,MAAM,iCAAiC,GAAG,GAAG,CAAC;AAErD;;;;GAIG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,yBAAyB,CAAC"}

package/dist/types/safe-typing.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Recursive dynamic type for deep chained property/method access on unknown
+ *
+ * Every property access and method call returns another `DynResult`, so
+ * optional chains like `dyn(ctx)?.getMessage?.()?.properties?.correlationId`
+ * compile without `any`.
+ */
+interface DynResult {
+    [key: string | symbol]: DynResult;
+    (...args: unknown[]): DynResult;
+}
+/** Cast unknown value to a recursively-callable dynamic type. */
+export declare function dyn(value: unknown): DynResult | undefined;
+export {};
+//# sourceMappingURL=safe-typing.d.ts.map

package/dist/types/safe-typing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-typing.d.ts","sourceRoot":"","sources":["../../src/types/safe-typing.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,UAAU,SAAS;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAClC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,SAAS,CAAC;CACjC;AAED,iEAAiE;AACjE,wBAAgB,GAAG,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAEzD"}

package/dist/types/safe-typing.js

@@ -0,0 +1,6 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+/** Cast unknown value to a recursively-callable dynamic type. */
+export function dyn(value) {
+    return value;
+}
+//# sourceMappingURL=safe-typing.js.map

package/dist/types/safe-typing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-typing.js","sourceRoot":"","sources":["../../src/types/safe-typing.ts"],"names":[],"mappings":"AAAA,sEAAsE;AActE,iEAAiE;AACjE,MAAM,UAAU,GAAG,CAAC,KAAc;IAChC,OAAO,KAA8B,CAAC;AACxC,CAAC"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@cqrs-ddd/pipeline-correlation",
+  "version": "0.5.0",
+  "description": "Correlation id propagation for any Node.js application: HTTP middleware, queue and message consumers, cron jobs",
+  "author": "Aristotelis",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aristoteliss/ddd-cqrs.git",
+    "directory": "packages/pipeline-correlation"
+  },
+  "homepage": "https://aristoteliss.github.io/ddd-cqrs/packages/pipeline-correlation/",
+  "bugs": {
+    "url": "https://github.com/aristoteliss/ddd-cqrs/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "COMMERCIAL_LICENSE.txt"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^5.0.3",
+    "vitest": "^5.0.3"
+  },
+  "dependencies": {
+    "@cqrs-ddd/uuidv7": "^0.5.0",
+    "@cqrs-ddd/untyped": "^0.5.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "build:watch": "tsc -p tsconfig.build.json --watch",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "rebuild": "pnpm run clean && pnpm run build",
+    "lint": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}