@cqrs-ddd/pipeline-correlation 0.5.0 → 0.5.2

package/COMMERCIAL_LICENSE.txt

@@ -9,21 +9,25 @@ This Commercial License Agreement ("Agreement") is a legal agreement between You
 Upon acceptance of this Agreement and compliance with the Payment Terms in Section 2, the Licensor grants You a non-exclusive, worldwide, non-transferable license to use, modify, integrate, and distribute the Software in commercial applications WITHOUT the copyleft obligations of the GNU Affero General Public License v3 (AGPLv3). Under this Agreement, You are NOT required to open-source Your proprietary code that integrates with the Software.
 
 2. PAYMENT TERMS AND REVENUE TIERS
-This license requires an annual fee based on Your (or Your organization's) total gross global revenue for the most recently completed fiscal year. 
+This license requires an annual fee based on Your (or Your organization's) total gross global revenue for the most recently completed fiscal year.
 
-The annual fee is calculated using the following scaled brackets:
+The annual fee is calculated using the following marginal brackets. Each rate applies only to the portion of gross revenue that falls within its bracket, and the annual fee is the sum of the amounts for all brackets:
 
-a) Tier 1: Gross revenue up to $500,000 USD
-   Fee: $0 (Free Commercial Use)
+a) Tier 1: The portion of gross revenue up to $500,000 USD
+   Rate: 0% (Free Commercial Use). If gross revenue does not exceed $500,000 USD, the fee is $0.
 
-b) Tier 2: Gross revenue between $500,001 and $10,000,000 USD
-   Fee: 0.1% of total gross revenue.
+b) Tier 2: The portion of gross revenue above $500,000 USD and up to $10,000,000 USD
+   Rate: 0.1% of that portion.
 
-c) Tier 3: Gross revenue between $10,000,001 and $50,000,000 USD
-   Fee: 0.05% of total gross revenue.
+c) Tier 3: The portion of gross revenue above $10,000,000 USD and up to $50,000,000 USD
+   Rate: 0.05% of that portion.
 
-d) Tier 4: Gross revenue exceeding $50,000,000 USD
-   Fee: 0.01% of total gross revenue, up to a maximum hard cap of $50,000 USD per year.
+d) Tier 4: The portion of gross revenue above $50,000,000 USD
+   Rate: 0.01% of that portion.
+
+The total annual fee never exceeds a maximum hard cap of $50,000 USD per year.
+
+Example: for gross revenue of $20,000,000 USD, the annual fee is 0.1% of $9,500,000 USD ($9,500) plus 0.05% of $10,000,000 USD ($5,000), a total of $14,500 USD.
 
 3. REPORTING AND REMITTANCE
 - Fees are calculated annually and must be remitted to the Licensor within ninety (90) days following the close of Your fiscal year.

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;AA+CvB;;;;;;;;;;;;;;;;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';
 /**
@@ -24,31 +24,37 @@ export function WithCorrelation(pathOrOptions) {
         ? { path: pathOrOptions }
         : (pathOrOptions ?? {});
     const { path = 'data.correlationId', extract } = options;
-    return methodDecorator((originalMethod, _propertyKey) => {
+    const wrap = (originalMethod, _propertyKey) => {
         return function (...args) {
             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, () => {
-                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 runWithIncoming(correlationId, source, () => {
+                const log = logAt(logger, options.logLevel);
+                log?.(`🔗 Starting ${source} with correlationId: ${getCorrelationId()}`);
                 return originalMethod.apply(this, args);
             });
         };
-    });
+    };
+    return methodDecorator(wrap);
+}
+/** The logger method of `logLevel` (default `'debug'`), unless it is `'none'` or missing. */
+function logAt(logger, logLevel) {
+    if (logLevel === 'none')
+        return undefined;
+    const method = logger[(logLevel ?? 'debug')];
+    if (typeof method !== 'function')
+        return undefined;
+    return (message) => method.call(logger, message);
 }
 /**
  * Pre-built extraction presets for {@link WithCorrelation}, for transports whose

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":"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"}
+{"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,CA2C5E"}
+{"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,29 +30,9 @@ 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 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;
-        }
-    };
+    const resolveIncoming = incomingResolver(options);
     return (req, res, next) => {
         const raw = req.headers?.[header];
         const candidate = Array.isArray(raw) ? raw[0] : raw;
@@ -57,7 +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 overrides = {
+        maxLength: options?.maxLength,
+        validateIncoming: options?.validateIncoming,
+    };
+    return (raw) => {
+        if (!acceptIncoming || typeof raw !== 'string')
+            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":"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"}
+{"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.0",
+  "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",
@@ -17,6 +17,14 @@
   "bugs": {
     "url": "https://github.com/aristoteliss/ddd-cqrs/issues"
   },
+  "keywords": [
+    "pipeline",
+    "cqrs",
+    "correlation-id",
+    "request-id",
+    "tracing",
+    "asynclocalstorage"
+  ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -35,12 +43,12 @@
     "access": "public"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "^5.0.3",
-    "vitest": "^5.0.3"
+    "@vitest/coverage-v8": "^5.0.5",
+    "vitest": "^5.0.5"
   },
   "dependencies": {
-    "@cqrs-ddd/uuidv7": "^0.5.0",
-    "@cqrs-ddd/untyped": "^0.5.0"
+    "@cqrs-ddd/untyped": "^0.5.2",
+    "@cqrs-ddd/uuidv7": "^0.5.2"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",