@cqrs-ddd/pipeline-correlation 0.5.1 → 0.5.2

package/dist/correlation.store.d.ts

@@ -4,11 +4,12 @@
  * `@cqrs-ddd/pipeline-job-context`. Unlike {@link getCorrelationId}, `current()`
  * generates nothing: it returns `undefined` when no id is set, so a pipeline
  * generates one and runs with it, and {@link getCorrelationId} inside the
- * handler returns that id. `create()` makes a new id, the one way this
- * package, pipelines and jobs generate one. `accepts(id)` tells whether an id received from
- * outside, such as in a job payload, is well formed: at most
- * {@link DEFAULT_CORRELATION_ID_MAX_LENGTH} characters matching
- * {@link DEFAULT_CORRELATION_ID_PATTERN}.
+ * handler returns that id. `run(id, fn)` runs `fn` with `id`, or with no id when `id`
+ * is not printable ASCII without surrounding spaces. `create()` makes a new id, the one
+ * way this package, pipelines and jobs generate one. `accepts(id)` tells whether an id
+ * received from outside, such as in a job payload, passes the rules
+ * `configureCorrelation` sets: by default at most 128 characters matching
+ * `DEFAULT_CORRELATION_ID_PATTERN`. It reports nothing to `onRejected`.
  *
  * @example
  * ```ts
@@ -28,11 +29,13 @@ export declare const correlationSource: {
  * WebSocket handlers, scheduled jobs) to propagate an external correlation ID
  * into everything the callback runs, wrapped operations included.
  *
- * If `correlationId` is falsy (`undefined` or empty), the id is resolved via
- * {@link getCorrelationId} (the current one, or a new one from
- * `correlationSource.create()`), so
- * `fn` always runs with a correlation id. A pipeline dispatched inside `fn`
- * takes it as its `context.correlationId`.
+ * When `correlationId` is missing, empty, not printable ASCII without surrounding
+ * spaces, or, once `configureCorrelation` has been called, rejected by its rules, `fn`
+ * runs with the id {@link getCorrelationId}
+ * returns (the current one, or a new one from `correlationSource.create()`), so it always
+ * runs with a correlation id. A rejected id is reported to `onRejected` with the source
+ * `'runWithCorrelationId'`. A pipeline dispatched inside `fn` takes the id as its
+ * `context.correlationId`.
  *
  * @example
  * ```ts
@@ -52,10 +55,12 @@ export declare const correlationSource: {
  * setInterval(() => runWithCorrelationId(undefined, () => hourlySync()), 3_600_000);
  * ```
  *
- * @param correlationId - The correlation ID to propagate. If falsy, falls back to {@link getCorrelationId}.
+ * @param correlationId - The correlation ID to propagate, as received from outside.
  * @param fn - The callback to execute within the correlation context.
  */
 export declare function runWithCorrelationId<T>(correlationId: string | undefined, fn: () => T): T;
+/** Runs `fn` with `id` when the rules accept it, else with the current or a new id. */
+export declare function runWithIncoming<T>(id: unknown, source: string, fn: () => T): T;
 /**
  * Read the current correlation ID.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"correlation.store.d.ts","sourceRoot":"","sources":["../src/correlation.store.ts"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,iBAAiB;aAC5B,OAAO,QAAM,MAAM,GAAG,SAAS;aAC/B,GAAG,GAAG,CAAC,SAAS,MAAM,GAAG,SAAS,MAAM,MAAM,CAAC,KAAG,CAAC;aAEnD,MAAM,QAAM,MAAM;aAClB,OAAO,OAAO,MAAM,KAAG,OAAO;CAGtB,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,EAAE,EAAE,MAAM,CAAC,GACV,CAAC,CAEH;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG;IAC/D,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChE,IAAI,EAAE,CAAC,GACN,iBAAiB,CAAC,CAAC,CAAC,CAYtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,SAA6B,GAC/B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAExB"}
+{"version":3,"file":"correlation.store.d.ts","sourceRoot":"","sources":["../src/correlation.store.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,iBAAiB;aAC5B,OAAO,QAAM,MAAM,GAAG,SAAS;aAC/B,GAAG,GAAG,CAAC,SAAS,MAAM,GAAG,SAAS,MAAM,MAAM,CAAC,KAAG,CAAC;aAEnD,MAAM,QAAM,MAAM;aAClB,OAAO,OAAO,MAAM,KAAG,OAAO;CACtB,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,EAAE,EAAE,MAAM,CAAC,GACV,CAAC,CAEH;AAED,uFAAuF;AACvF,wBAAgB,eAAe,CAAC,CAAC,EAC/B,EAAE,EAAE,OAAO,EACX,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,MAAM,CAAC,GACV,CAAC,CAKH;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG;IAC/D,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChE,IAAI,EAAE,CAAC,GACN,iBAAiB,CAAC,CAAC,CAAC,CAYtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,SAA6B,GAC/B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAExB"}

package/dist/correlation.store.js

@@ -2,7 +2,7 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { uuidv7 } from '@cqrs-ddd/uuidv7';
 import { DEFAULT_CORRELATION_HEADER } from './constants/correlation.constants.js';
-import { DEFAULT_CORRELATION_ID_MAX_LENGTH, DEFAULT_CORRELATION_ID_PATTERN, } from './options/correlation.options.js';
+import { admit, isAccepted, isPortable } from './policy/correlation.policy.js';
 const correlation = new AsyncLocalStorage();
 /**
  * The correlation id as a context source, for `createPipeline({ sources })`
@@ -10,11 +10,12 @@ const correlation = new AsyncLocalStorage();
  * `@cqrs-ddd/pipeline-job-context`. Unlike {@link getCorrelationId}, `current()`
  * generates nothing: it returns `undefined` when no id is set, so a pipeline
  * generates one and runs with it, and {@link getCorrelationId} inside the
- * handler returns that id. `create()` makes a new id, the one way this
- * package, pipelines and jobs generate one. `accepts(id)` tells whether an id received from
- * outside, such as in a job payload, is well formed: at most
- * {@link DEFAULT_CORRELATION_ID_MAX_LENGTH} characters matching
- * {@link DEFAULT_CORRELATION_ID_PATTERN}.
+ * handler returns that id. `run(id, fn)` runs `fn` with `id`, or with no id when `id`
+ * is not printable ASCII without surrounding spaces. `create()` makes a new id, the one
+ * way this package, pipelines and jobs generate one. `accepts(id)` tells whether an id
+ * received from outside, such as in a job payload, passes the rules
+ * `configureCorrelation` sets: by default at most 128 characters matching
+ * `DEFAULT_CORRELATION_ID_PATTERN`. It reports nothing to `onRejected`.
  *
  * @example
  * ```ts
@@ -23,10 +24,9 @@ const correlation = new AsyncLocalStorage();
  */
 export const correlationSource = {
     current: () => correlation.getStore(),
-    run: (value, fn) => correlation.run(value, fn),
+    run: (value, fn) => correlation.run(isPortable(value) ? value : undefined, fn),
     create: () => uuidv7(),
-    accepts: (id) => id.length <= DEFAULT_CORRELATION_ID_MAX_LENGTH &&
-        DEFAULT_CORRELATION_ID_PATTERN.test(id),
+    accepts: (id) => isAccepted(id),
 };
 /**
  * Run a callback within a correlation context.
@@ -35,11 +35,13 @@ export const correlationSource = {
  * WebSocket handlers, scheduled jobs) to propagate an external correlation ID
  * into everything the callback runs, wrapped operations included.
  *
- * If `correlationId` is falsy (`undefined` or empty), the id is resolved via
- * {@link getCorrelationId} (the current one, or a new one from
- * `correlationSource.create()`), so
- * `fn` always runs with a correlation id. A pipeline dispatched inside `fn`
- * takes it as its `context.correlationId`.
+ * When `correlationId` is missing, empty, not printable ASCII without surrounding
+ * spaces, or, once `configureCorrelation` has been called, rejected by its rules, `fn`
+ * runs with the id {@link getCorrelationId}
+ * returns (the current one, or a new one from `correlationSource.create()`), so it always
+ * runs with a correlation id. A rejected id is reported to `onRejected` with the source
+ * `'runWithCorrelationId'`. A pipeline dispatched inside `fn` takes the id as its
+ * `context.correlationId`.
  *
  * @example
  * ```ts
@@ -59,11 +61,15 @@ export const correlationSource = {
  * setInterval(() => runWithCorrelationId(undefined, () => hourlySync()), 3_600_000);
  * ```
  *
- * @param correlationId - The correlation ID to propagate. If falsy, falls back to {@link getCorrelationId}.
+ * @param correlationId - The correlation ID to propagate, as received from outside.
  * @param fn - The callback to execute within the correlation context.
  */
 export function runWithCorrelationId(correlationId, fn) {
-    return correlation.run(correlationId || getCorrelationId(), fn);
+    return runWithIncoming(correlationId, 'runWithCorrelationId', fn);
+}
+/** Runs `fn` with `id` when the rules accept it, else with the current or a new id. */
+export function runWithIncoming(id, source, fn) {
+    return correlation.run(admit(id, source, 'unchecked') ?? getCorrelationId(), fn);
 }
 /**
  * Read the current correlation ID.

package/dist/correlation.store.js.map

@@ -1 +1 @@
-{"version":3,"file":"correlation.store.js","sourceRoot":"","sources":["../src/correlation.store.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,0BAA0B,EAAE,MAAM,sCAAsC,CAAC;AAClF,OAAO,EACL,iCAAiC,EACjC,8BAA8B,GAC/B,MAAM,kCAAkC,CAAC;AAE1C,MAAM,WAAW,GAAG,IAAI,iBAAiB,EAAsB,CAAC;AAEhE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,OAAO,EAAE,GAAuB,EAAE,CAAC,WAAW,CAAC,QAAQ,EAAE;IACzD,GAAG,EAAE,CAAI,KAAyB,EAAE,EAAW,EAAK,EAAE,CACpD,WAAW,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,CAAC;IAC5B,MAAM,EAAE,GAAW,EAAE,CAAC,MAAM,EAAE;IAC9B,OAAO,EAAE,CAAC,EAAU,EAAW,EAAE,CAC/B,EAAE,CAAC,MAAM,IAAI,iCAAiC;QAC9C,8BAA8B,CAAC,IAAI,CAAC,EAAE,CAAC;CACjC,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,UAAU,oBAAoB,CAClC,aAAiC,EACjC,EAAW;IAEX,OAAO,WAAW,CAAC,GAAG,CAAC,aAAa,IAAI,gBAAgB,EAAE,EAAE,EAAE,CAAC,CAAC;AAClE,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,WAAW,CAAC,QAAQ,EAAE,IAAI,iBAAiB,CAAC,MAAM,EAAE,CAAC;AAC9D,CAAC;AAuBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAAO;IAEP,MAAM,SAAS,GACb,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QACvC,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC;QAC7B,CAAC,CAAC,SAAS,CAAC;IAChB,IAAI,SAAS,KAAK,MAAM,CAAC,SAAS,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;QACzD,MAAM,IAAI,SAAS,CACjB,0DAA0D;YACxD,0DAA0D,CAC7D,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,GAAG,IAAI,EAAE,aAAa,EAAE,gBAAgB,EAAE,EAAE,CAAC;AACxD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,UAAU,kBAAkB,CAChC,GAAG,GAAG,0BAA0B;IAEhC,OAAO,EAAE,CAAC,GAAG,CAAC,EAAE,gBAAgB,EAAE,EAAE,CAAC;AACvC,CAAC"}
+{"version":3,"file":"correlation.store.js","sourceRoot":"","sources":["../src/correlation.store.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,0BAA0B,EAAE,MAAM,sCAAsC,CAAC;AAClF,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAE/E,MAAM,WAAW,GAAG,IAAI,iBAAiB,EAAsB,CAAC;AAEhE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,OAAO,EAAE,GAAuB,EAAE,CAAC,WAAW,CAAC,QAAQ,EAAE;IACzD,GAAG,EAAE,CAAI,KAAyB,EAAE,EAAW,EAAK,EAAE,CACpD,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC;IAC5D,MAAM,EAAE,GAAW,EAAE,CAAC,MAAM,EAAE;IAC9B,OAAO,EAAE,CAAC,EAAU,EAAW,EAAE,CAAC,UAAU,CAAC,EAAE,CAAC;CACxC,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,UAAU,oBAAoB,CAClC,aAAiC,EACjC,EAAW;IAEX,OAAO,eAAe,CAAC,aAAa,EAAE,sBAAsB,EAAE,EAAE,CAAC,CAAC;AACpE,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,eAAe,CAC7B,EAAW,EACX,MAAc,EACd,EAAW;IAEX,OAAO,WAAW,CAAC,GAAG,CACpB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,CAAC,IAAI,gBAAgB,EAAE,EACpD,EAAE,CACH,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,WAAW,CAAC,QAAQ,EAAE,IAAI,iBAAiB,CAAC,MAAM,EAAE,CAAC;AAC9D,CAAC;AAuBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAAO;IAEP,MAAM,SAAS,GACb,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QACvC,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC;QAC7B,CAAC,CAAC,SAAS,CAAC;IAChB,IAAI,SAAS,KAAK,MAAM,CAAC,SAAS,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;QACzD,MAAM,IAAI,SAAS,CACjB,0DAA0D;YACxD,0DAA0D,CAC7D,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,GAAG,IAAI,EAAE,aAAa,EAAE,gBAAgB,EAAE,EAAE,CAAC;AACxD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,UAAU,kBAAkB,CAChC,GAAG,GAAG,0BAA0B;IAEhC,OAAO,EAAE,CAAC,GAAG,CAAC,EAAE,gBAAgB,EAAE,EAAE,CAAC;AACvC,CAAC"}

package/dist/decorators/with-correlation.decorator.d.ts

@@ -99,9 +99,11 @@ export interface CorrelationLogger {
  * not replace or interfere with them.
  *
  * It extracts the correlation ID from the method arguments (via `path` or
- * `extract`) and runs the method inside {@link runWithCorrelationId}, which
- * keeps the current id, or makes one with `correlationSource.create()`, when
- * no ID is found.
+ * `extract`) and runs the method with it when it is printable ASCII without
+ * surrounding spaces and, once `configureCorrelation` has been called, passes its
+ * rules. Otherwise the method keeps the current id, or gets a new one from
+ * `correlationSource.create()`, and a rejected id is reported to `onRejected` with the
+ * source `'Class.method'`.
  *
  * **⚠️ Array payloads:**
  * When using the default dot-path extraction, the first argument must be an

package/dist/decorators/with-correlation.decorator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"with-correlation.decorator.d.ts","sourceRoot":"","sources":["../../src/decorators/with-correlation.decorator.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,KAAK,mBAAmB,EAEzB,MAAM,gCAAgC,CAAC;AAGxC;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,MAAM,GAAG,SAAS,CAAC;AAE9E;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;;;;;;;;;OAUG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAE/B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAE7B;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC5B;AAED,yEAAyE;AACzE,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC;AAEhF;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,cAAc,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAC7D,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,cAAc,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAC9D,KAAK,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,cAAc,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAChE,OAAO,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,cAAc,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAClE,KAAK,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,cAAc,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAChE,KAAK,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,cAAc,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;CACjE;AAiBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,wBAAgB,eAAe,IAAI,mBAAmB,CAAC;AACvD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,CAAC;AACnE,wBAAgB,eAAe,CAC7B,OAAO,EAAE,2BAA2B,GACnC,mBAAmB,CAAC;AAyDvB;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,eAAe;IAC1B;;;;;;OAMG;qCACuC,2BAA2B;CAM7D,CAAC"}
+{"version":3,"file":"with-correlation.decorator.d.ts","sourceRoot":"","sources":["../../src/decorators/with-correlation.decorator.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,KAAK,mBAAmB,EAEzB,MAAM,gCAAgC,CAAC;AAGxC;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,MAAM,GAAG,SAAS,CAAC;AAE9E;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;;;;;;;;;OAUG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAE/B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAE7B;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC5B;AAED,yEAAyE;AACzE,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC;AAEhF;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,cAAc,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAC7D,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,cAAc,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAC9D,KAAK,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,cAAc,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAChE,OAAO,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,cAAc,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAClE,KAAK,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,cAAc,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAChE,KAAK,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,cAAc,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;CACjE;AAiBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,wBAAgB,eAAe,IAAI,mBAAmB,CAAC;AACvD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,CAAC;AACnE,wBAAgB,eAAe,CAC7B,OAAO,EAAE,2BAA2B,GACnC,mBAAmB,CAAC;AA0DvB;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,eAAe;IAC1B;;;;;;OAMG;qCACuC,2BAA2B;CAM7D,CAAC"}

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

@@ -1,7 +1,7 @@
 /* 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 { getCorrelationId, runWithIncoming } from '../correlation.store.js';
 import { methodDecorator, } from '../helpers/method-decorator.js';
 import { dyn } from '../types/safe-typing.js';
 /**
@@ -29,17 +29,18 @@ export function WithCorrelation(pathOrOptions) {
             const logger = options.logger ??
                 untyped(this)?.logger ??
                 console;
+            const source = `${untyped(this).constructor?.name}.${String(_propertyKey)}`;
             if (!extract && Array.isArray(args[0])) {
-                logger.warn(`${untyped(this).constructor?.name}.${String(_propertyKey)}: first argument is an array — ` +
+                logger.warn(`${source}: 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, () => {
+            return runWithIncoming(correlationId, source, () => {
                 const log = logAt(logger, options.logLevel);
-                log?.(`🔗 Starting ${untyped(this).constructor?.name}.${String(_propertyKey)} with correlationId: ${getCorrelationId()}`);
+                log?.(`🔗 Starting ${source} with correlationId: ${getCorrelationId()}`);
                 return originalMethod.apply(this, args);
             });
         };

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

@@ -1 +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,MAAM,IAAI,GAA0C,CAClD,cAAc,EACd,YAAY,EACZ,EAAE;QACF,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,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAC5C,GAAG,EAAE,CACH,eAAe,OAAO,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,IAAI,IAAI,MAAM,CAAC,YAAY,CAAC,wBAAwB,gBAAgB,EAAE,EAAE,CACnH,CAAC;gBACF,OAAO,cAAc,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAC1C,CAAC,CAAC,CAAC;QACL,CAAC,CAAC;IACJ,CAAC,CAAC;IAEF,OAAO,eAAe,CAAC,IAAI,CAAC,CAAC;AAC/B,CAAC;AAED,6FAA6F;AAC7F,SAAS,KAAK,CACZ,MAAyB,EACzB,QAAiD;IAEjD,IAAI,QAAQ,KAAK,MAAM;QAAE,OAAO,SAAS,CAAC;IAC1C,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,QAAQ,IAAI,OAAO,CAA4B,CAAC,CAAC;IACxE,IAAI,OAAO,MAAM,KAAK,UAAU;QAAE,OAAO,SAAS,CAAC;IACnD,OAAO,CAAC,OAAO,EAAE,EAAE,CAAE,MAAgC,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC9E,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"}
+{"version":3,"file":"with-correlation.decorator.js","sourceRoot":"","sources":["../../src/decorators/with-correlation.decorator.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -6,4 +6,6 @@ export { CorrelationFrom, WithCorrelation, } from './decorators/with-correlation
 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';
+export type { CorrelationPolicy, CorrelationRejection, CorrelationRejectionReason, } from './policy/correlation.policy.js';
+export { configureCorrelation } from './policy/correlation.policy.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +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"}
+{"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;AAC1C,YAAY,EACV,iBAAiB,EACjB,oBAAoB,EACpB,0BAA0B,GAC3B,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC"}

package/dist/index.js

@@ -4,4 +4,5 @@ export { addCorrelationId, correlationHeaders, correlationSource, getCorrelation
 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';
+export { configureCorrelation } from './policy/correlation.policy.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +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"}
+{"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;AAM1C,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC"}

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

@@ -1,5 +1,5 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
-import { type CorrelationOptions } from '../options/correlation.options.js';
+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;
 /**
@@ -10,9 +10,12 @@ export type HttpMiddleware = (req: IncomingMessage, res: ServerResponse, next: (
  * 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.
+ * An incoming id that the rules `configureCorrelation` sets reject (by default, longer
+ * than 128 characters or outside the default character set) is replaced by a local id
+ * and reported to `onRejected` with the source `'http'`. `acceptIncoming`,
+ * `trimIncoming`, `maxLength` and `validateIncoming` adjust that policy for this
+ * middleware. None of them lets through an id that is not printable ASCII or that starts
+ * or ends with a space.
  *
  * @throws TypeError when `header` is not a valid HTTP field name, or `maxLength` is not
  *   a positive safe integer.

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

@@ -1 +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,CA2B5E"}
+{"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;AAGjE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AAK5E,sEAAsE;AACtE,MAAM,MAAM,cAAc,GAAG,CAC3B,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,cAAc,EACnB,IAAI,EAAE,MAAM,IAAI,KACb,IAAI,CAAC;AAEV;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,cAAc,CAoB5E"}

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

@@ -1,7 +1,7 @@
 /* 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';
+import { correlationSource, getCorrelationId } from '../correlation.store.js';
+import { admit, assertMaxLength } from '../policy/correlation.policy.js';
 const HTTP_FIELD_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
 /**
  * An HTTP middleware that takes the correlation id from the incoming request header and
@@ -11,9 +11,12 @@ const HTTP_FIELD_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
  * 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.
+ * An incoming id that the rules `configureCorrelation` sets reject (by default, longer
+ * than 128 characters or outside the default character set) is replaced by a local id
+ * and reported to `onRejected` with the source `'http'`. `acceptIncoming`,
+ * `trimIncoming`, `maxLength` and `validateIncoming` adjust that policy for this
+ * middleware. None of them lets through an id that is not printable ASCII or that starts
+ * or ends with a space.
  *
  * @throws TypeError when `header` is not a valid HTTP field name, or `maxLength` is not
  *   a positive safe integer.
@@ -27,10 +30,7 @@ export function httpCorrelation(options) {
     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.');
-    }
+    assertMaxLength(options?.maxLength);
     const header = typeof h === 'string' ? h.toLowerCase() : DEFAULT_CORRELATION_HEADER;
     const resolveIncoming = incomingResolver(options);
     return (req, res, next) => {
@@ -40,28 +40,21 @@ export function httpCorrelation(options) {
         if (typeof res?.setHeader === 'function') {
             res.setHeader(header, correlationId);
         }
-        runWithCorrelationId(correlationId, next);
+        correlationSource.run(correlationId, next);
     };
 }
 /** Returns an incoming id the options accept, else `undefined`. */
 function incomingResolver(options) {
     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 overrides = {
+        maxLength: options?.maxLength,
+        validateIncoming: options?.validateIncoming,
+    };
     return (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 admit(trimIncoming ? raw.trim() : raw, 'http', 'checked', overrides);
     };
 }
 //# sourceMappingURL=http-correlation.middleware.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"http-correlation.middleware.js","sourceRoot":"","sources":["../../src/middlewares/http-correlation.middleware.ts"],"names":[],"mappings":"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"}
+{"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,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE9E,OAAO,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAEzE,MAAM,eAAe,GAAG,gCAAgC,CAAC;AASzD;;;;;;;;;;;;;;;;;;;;;GAqBG;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,eAAe,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAEpC,MAAM,MAAM,GACV,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,0BAA0B,CAAC;IACvE,MAAM,eAAe,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAElD,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,iBAAiB,CAAC,GAAG,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;IAC7C,CAAC,CAAC;AACJ,CAAC;AAED,mEAAmE;AACnE,SAAS,gBAAgB,CACvB,OAA4B;IAE5B,MAAM,cAAc,GAAG,OAAO,EAAE,cAAc,IAAI,IAAI,CAAC;IACvD,MAAM,YAAY,GAAG,OAAO,EAAE,YAAY,IAAI,KAAK,CAAC;IACpD,MAAM,SAAS,GAAG;QAChB,SAAS,EAAE,OAAO,EAAE,SAAS;QAC7B,gBAAgB,EAAE,OAAO,EAAE,gBAAgB;KAC5C,CAAC;IAEF,OAAO,CAAC,GAAG,EAAE,EAAE;QACb,IAAI,CAAC,cAAc,IAAI,OAAO,GAAG,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QACjE,OAAO,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;IAC9E,CAAC,CAAC;AACJ,CAAC"}

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

@@ -13,10 +13,11 @@ export declare const DEFAULT_CORRELATION_ID_PATTERN: RegExp;
  * 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
+ * An incoming header value is accepted only when it passes the rules
+ * `configureCorrelation` sets, by default at most
+ * {@link DEFAULT_CORRELATION_ID_MAX_LENGTH} characters matching
  * {@link DEFAULT_CORRELATION_ID_PATTERN}; otherwise a local ID is used.
- * `maxLength` and `validateIncoming` replace these defaults.
+ * `maxLength` and `validateIncoming` replace those rules for this middleware.
  *
  * @example
  * ```ts
@@ -70,14 +71,16 @@ export interface CorrelationOptions {
      * Maximum accepted incoming correlation-ID length. Longer values are
      * discarded and replaced by the locally resolved/generated ID.
      *
-     * @default 128
+     * @default the `maxLength` of `configureCorrelation`, 128 unless configured
      */
     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.
+     * Validation predicate for incoming IDs; replaces the `validateIncoming` of
+     * `configureCorrelation`, by default the {@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, and the
+     * predicate sees only values of printable ASCII (0x20 to 0x7E) that neither
+     * start nor end with a space.
      *
      * @example
      * ```ts

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

@@ -1 +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"}
+{"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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;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;;;;;;;;;;;;;;OAcG;IACH,gBAAgB,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC;CACvD"}

package/dist/policy/correlation.policy.d.ts

@@ -0,0 +1,89 @@
+/** Why an incoming correlation id was rejected. */
+export type CorrelationRejectionReason = 'not-string' | 'too-long' | 'invalid-character' | 'surrounding-space' | 'rule';
+/** An incoming correlation id that was replaced, as `onRejected` receives it. */
+export interface CorrelationRejection {
+    reason: CorrelationRejectionReason;
+    /**
+     * Where the id arrived: `'http'` for `httpCorrelation`, `'Class.method'` for a
+     * `@WithCorrelation` method, `'runWithCorrelationId'` for a direct call.
+     */
+    source: string;
+    /**
+     * The rejected value's length in characters, `0` when it is not a string. The value
+     * itself is withheld, so a forged id never reaches a log through this report.
+     */
+    length: number;
+}
+/** The rules every incoming correlation id must pass, set with {@link configureCorrelation}. */
+export interface CorrelationPolicy {
+    /**
+     * The longest incoming id accepted, in characters.
+     *
+     * @default 128
+     */
+    maxLength?: number;
+    /**
+     * The application's rule for incoming ids. It replaces the
+     * {@link DEFAULT_CORRELATION_ID_PATTERN} test and sees only ids that pass the built-in
+     * check and `maxLength`; returning `false` or throwing rejects the id. It must accept
+     * the UUIDv7 ids `correlationSource.create()` makes, because the jobs a request
+     * enqueues and the services it calls receive them.
+     */
+    validateIncoming?: (correlationId: string) => boolean;
+    /**
+     * Called once, synchronously, for each incoming id that is replaced. An error it
+     * throws is ignored, so a failing report never fails the work.
+     */
+    onRejected?: (rejection: CorrelationRejection) => void;
+}
+/** The two rules an entry point can replace for itself. */
+type Rules = Required<Omit<CorrelationPolicy, 'onRejected'>>;
+/**
+ * `'checked'`: the entry points that applied the default rule before
+ * `configureCorrelation` existed, `httpCorrelation` and `correlationSource.accepts`.
+ * `'unchecked'`: those that stored any id, `runWithCorrelationId` and `@WithCorrelation`.
+ */
+export type EntryPoint = 'checked' | 'unchecked';
+/**
+ * Sets the rules every incoming correlation id must pass, for the whole process:
+ * `httpCorrelation`, `runWithCorrelationId`, `@WithCorrelation` and
+ * `correlationSource.accepts`, which job contexts use. Call it once at startup, before
+ * the first request. Each call replaces every rule.
+ *
+ * Until it is called, `httpCorrelation` and `correlationSource.accepts` apply the
+ * default rules, and `runWithCorrelationId` and `@WithCorrelation` apply only the
+ * built-in check. Once it is called, even with an empty policy, every entry point
+ * applies its rules. A call without a policy restores the state before the first call.
+ *
+ * Whatever the rules, an id must first be printable ASCII (0x20 to 0x7E) that neither
+ * starts nor ends with a space, and nothing turns that check off. A rejected id is
+ * replaced by the current or a new one and reported to `onRejected`; a missing or empty
+ * id is replaced without a report. The `maxLength` and `validateIncoming` options of
+ * `httpCorrelation`, when given, replace these rules for that middleware.
+ *
+ * @param policy - The rules; an omitted field takes its default. Omit the policy to
+ *   restore the state before the first call.
+ * @throws {TypeError} When `maxLength` is not a positive safe integer.
+ * @example
+ * ```ts
+ * configureCorrelation({
+ *   validateIncoming: (id) => /^[0-9a-f-]{36}$/i.test(id),
+ *   onRejected: ({ reason, source, length }) =>
+ *     logger.warn({ reason, source, length }, 'correlation id replaced'),
+ * });
+ * ```
+ */
+export declare function configureCorrelation(policy?: CorrelationPolicy): void;
+/** Throws unless `maxLength` is absent or a positive safe integer. */
+export declare function assertMaxLength(maxLength: number | undefined): void;
+/** Whether `id` is printable ASCII that neither starts nor ends with a space. */
+export declare function isPortable(id: unknown): id is string;
+/** Whether the rules of a checked entry point accept `id`; reports nothing. */
+export declare function isAccepted(id: string): boolean;
+/**
+ * Returns `id` when the rules of `entryPoint` accept it. Otherwise returns `undefined`
+ * and, unless `id` is missing or empty, reports the rejection as coming from `source`.
+ */
+export declare function admit(id: unknown, source: string, entryPoint: EntryPoint, overrides?: Partial<Rules>): string | undefined;
+export {};
+//# sourceMappingURL=correlation.policy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"correlation.policy.d.ts","sourceRoot":"","sources":["../../src/policy/correlation.policy.ts"],"names":[],"mappings":"AAOA,mDAAmD;AACnD,MAAM,MAAM,0BAA0B,GAClC,YAAY,GACZ,UAAU,GACV,mBAAmB,GACnB,mBAAmB,GACnB,MAAM,CAAC;AAEX,iFAAiF;AACjF,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,0BAA0B,CAAC;IACnC;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,gGAAgG;AAChG,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC;IAEtD;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE,oBAAoB,KAAK,IAAI,CAAC;CACxD;AAED,2DAA2D;AAC3D,KAAK,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,iBAAiB,EAAE,YAAY,CAAC,CAAC,CAAC;AAE7D;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,WAAW,CAAC;AAoBjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAarE;AAED,sEAAsE;AACtE,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CASnE;AAED,iFAAiF;AACjF,wBAAgB,UAAU,CAAC,EAAE,EAAE,OAAO,GAAG,EAAE,IAAI,MAAM,CAEpD;AAED,+EAA+E;AAC/E,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAE9C;AAED;;;GAGG;AACH,wBAAgB,KAAK,CACnB,EAAE,EAAE,OAAO,EACX,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,UAAU,EACtB,SAAS,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,GACzB,MAAM,GAAG,SAAS,CAgBpB"}

package/dist/policy/correlation.policy.js

@@ -0,0 +1,128 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { DEFAULT_CORRELATION_ID_MAX_LENGTH, DEFAULT_CORRELATION_ID_PATTERN, } from '../options/correlation.options.js';
+const PRINTABLE_ASCII = /^[\x20-\x7E]*$/;
+const matchesDefaultPattern = (id) => DEFAULT_CORRELATION_ID_PATTERN.test(id);
+const DEFAULT_RULES = {
+    maxLength: DEFAULT_CORRELATION_ID_MAX_LENGTH,
+    validateIncoming: matchesDefaultPattern,
+};
+const BUILT_IN_CHECK_ONLY = {
+    maxLength: Number.POSITIVE_INFINITY,
+    validateIncoming: () => true,
+};
+let configured;
+let onRejected;
+/**
+ * Sets the rules every incoming correlation id must pass, for the whole process:
+ * `httpCorrelation`, `runWithCorrelationId`, `@WithCorrelation` and
+ * `correlationSource.accepts`, which job contexts use. Call it once at startup, before
+ * the first request. Each call replaces every rule.
+ *
+ * Until it is called, `httpCorrelation` and `correlationSource.accepts` apply the
+ * default rules, and `runWithCorrelationId` and `@WithCorrelation` apply only the
+ * built-in check. Once it is called, even with an empty policy, every entry point
+ * applies its rules. A call without a policy restores the state before the first call.
+ *
+ * Whatever the rules, an id must first be printable ASCII (0x20 to 0x7E) that neither
+ * starts nor ends with a space, and nothing turns that check off. A rejected id is
+ * replaced by the current or a new one and reported to `onRejected`; a missing or empty
+ * id is replaced without a report. The `maxLength` and `validateIncoming` options of
+ * `httpCorrelation`, when given, replace these rules for that middleware.
+ *
+ * @param policy - The rules; an omitted field takes its default. Omit the policy to
+ *   restore the state before the first call.
+ * @throws {TypeError} When `maxLength` is not a positive safe integer.
+ * @example
+ * ```ts
+ * configureCorrelation({
+ *   validateIncoming: (id) => /^[0-9a-f-]{36}$/i.test(id),
+ *   onRejected: ({ reason, source, length }) =>
+ *     logger.warn({ reason, source, length }, 'correlation id replaced'),
+ * });
+ * ```
+ */
+export function configureCorrelation(policy) {
+    if (policy === undefined) {
+        configured = undefined;
+        onRejected = undefined;
+        return;
+    }
+    assertMaxLength(policy.maxLength);
+    configured = {
+        maxLength: policy.maxLength ?? DEFAULT_RULES.maxLength,
+        validateIncoming: policy.validateIncoming ?? DEFAULT_RULES.validateIncoming,
+    };
+    onRejected = policy.onRejected;
+}
+/** Throws unless `maxLength` is absent or a positive safe integer. */
+export function assertMaxLength(maxLength) {
+    if (maxLength !== undefined &&
+        (!Number.isSafeInteger(maxLength) || maxLength <= 0)) {
+        throw new TypeError('Correlation maxLength must be a positive safe integer when provided.');
+    }
+}
+/** Whether `id` is printable ASCII that neither starts nor ends with a space. */
+export function isPortable(id) {
+    return typeof id === 'string' && id !== '' && defectOf(id) === undefined;
+}
+/** Whether the rules of a checked entry point accept `id`; reports nothing. */
+export function isAccepted(id) {
+    return id !== '' && rejectionOf(id, rulesFor('checked')) === undefined;
+}
+/**
+ * Returns `id` when the rules of `entryPoint` accept it. Otherwise returns `undefined`
+ * and, unless `id` is missing or empty, reports the rejection as coming from `source`.
+ */
+export function admit(id, source, entryPoint, overrides) {
+    if (id === undefined || id === null || id === '')
+        return undefined;
+    const rules = rulesFor(entryPoint);
+    const reason = rejectionOf(id, {
+        maxLength: overrides?.maxLength ?? rules.maxLength,
+        validateIncoming: overrides?.validateIncoming ?? rules.validateIncoming,
+    });
+    if (reason === undefined)
+        return id;
+    report({
+        reason,
+        source,
+        length: typeof id === 'string' ? id.length : 0,
+    });
+    return undefined;
+}
+function rulesFor(entryPoint) {
+    if (configured !== undefined)
+        return configured;
+    return entryPoint === 'checked' ? DEFAULT_RULES : BUILT_IN_CHECK_ONLY;
+}
+function rejectionOf(id, { maxLength, validateIncoming }) {
+    if (typeof id !== 'string')
+        return 'not-string';
+    if (id.length > maxLength)
+        return 'too-long';
+    return defectOf(id) ?? (passes(validateIncoming, id) ? undefined : 'rule');
+}
+function defectOf(id) {
+    if (!PRINTABLE_ASCII.test(id))
+        return 'invalid-character';
+    if (id.startsWith(' ') || id.endsWith(' '))
+        return 'surrounding-space';
+    return undefined;
+}
+function passes(validate, id) {
+    try {
+        return validate(id);
+    }
+    catch {
+        return false;
+    }
+}
+function report(rejection) {
+    try {
+        onRejected?.(rejection);
+    }
+    catch {
+        // A failing report must not fail the request or message it describes.
+    }
+}
+//# sourceMappingURL=correlation.policy.js.map

package/dist/policy/correlation.policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlation.policy.js","sourceRoot":"","sources":["../../src/policy/correlation.policy.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cqrs-ddd/pipeline-correlation",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Correlation id propagation for any Node.js application: HTTP middleware, queue and message consumers, cron jobs",
   "author": "Aristotelis",
   "license": "SEE LICENSE IN LICENSE",
@@ -47,8 +47,8 @@
     "vitest": "^5.0.5"
   },
   "dependencies": {
-    "@cqrs-ddd/untyped": "^0.5.1",
-    "@cqrs-ddd/uuidv7": "^0.5.1"
+    "@cqrs-ddd/untyped": "^0.5.2",
+    "@cqrs-ddd/uuidv7": "^0.5.2"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",