@cqrs-ddd/pipeline-correlation 0.5.0

package/README.md

@@ -0,0 +1,32 @@
+# @cqrs-ddd/pipeline-correlation
+
+Correlation id propagation for any Node.js application: an HTTP middleware
+(`httpCorrelation()`, for Node's `http` server, Express or Connect), the
+`@WithCorrelation()` method decorator for queue and message consumers and cron jobs
+(both TypeScript decorator modes), a gRPC extraction preset (`CorrelationFrom.grpc()`), and
+`correlationSource` for `createPipeline({ sources })` of `@cqrs-ddd/pipeline`.
+
+**Documentation:** [guide](https://aristoteliss.github.io/ddd-cqrs/packages/pipeline-correlation/) · [API reference](https://aristoteliss.github.io/ddd-cqrs/api/cqrs-ddd/pipeline-correlation/) · [all packages](https://aristoteliss.github.io/ddd-cqrs/)
+
+## Installation
+
+```bash
+pnpm add @cqrs-ddd/pipeline-correlation
+```
+
+Requires Node.js 22.12 or later. Published as an ES module; a CommonJS application loads
+it with `require()`.
+
+## Example
+
+```ts
+import { getCorrelationId, httpCorrelation } from '@cqrs-ddd/pipeline-correlation';
+
+app.use(httpCorrelation());
+app.get('/ping', (_req, res) => res.send(getCorrelationId()));
+```
+
+## License
+
+Dual-licensed under **AGPLv3** and a **Commercial License**. See `LICENSE` and
+`COMMERCIAL_LICENSE.txt`.

package/dist/constants/correlation.constants.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Default HTTP header name used for distributed correlation tracing.
+ */
+export declare const DEFAULT_CORRELATION_HEADER = "x-correlation-id";
+//# sourceMappingURL=correlation.constants.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"correlation.constants.d.ts","sourceRoot":"","sources":["../../src/constants/correlation.constants.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,eAAO,MAAM,0BAA0B,qBAAqB,CAAC"}

package/dist/constants/correlation.constants.js

@@ -0,0 +1,6 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+/**
+ * Default HTTP header name used for distributed correlation tracing.
+ */
+export const DEFAULT_CORRELATION_HEADER = 'x-correlation-id';
+//# sourceMappingURL=correlation.constants.js.map

package/dist/constants/correlation.constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlation.constants.js","sourceRoot":"","sources":["../../src/constants/correlation.constants.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE;;GAEG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,kBAAkB,CAAC"}

package/dist/correlation.store.d.ts

@@ -0,0 +1,174 @@
+/**
+ * The correlation id as a context source, for `createPipeline({ sources })`
+ * of `@cqrs-ddd/pipeline` and the job context registration of
+ * `@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}.
+ *
+ * @example
+ * ```ts
+ * createPipeline({ sources: { correlationId: correlationSource } });
+ * ```
+ */
+export declare const correlationSource: {
+    readonly current: () => string | undefined;
+    readonly run: <T>(value: string | undefined, fn: () => T) => T;
+    readonly create: () => string;
+    readonly accepts: (id: string) => boolean;
+};
+/**
+ * Run a callback within a correlation context.
+ *
+ * Use this in **non-HTTP entry points** (queue workers, message consumers,
+ * 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`.
+ *
+ * @example
+ * ```ts
+ * // BullMQ worker
+ * new Worker('emails', (job) =>
+ *   runWithCorrelationId(job.data.correlationId, () => sendEmail(job.data)),
+ * );
+ *
+ * // RabbitMQ consumer (amqplib)
+ * channel.consume('users', (message) =>
+ *   runWithCorrelationId(message.properties.correlationId, () =>
+ *     onUserCreated(JSON.parse(message.content.toString())),
+ *   ),
+ * );
+ *
+ * // Scheduled job: no incoming id, so a new one is made
+ * setInterval(() => runWithCorrelationId(undefined, () => hourlySync()), 3_600_000);
+ * ```
+ *
+ * @param correlationId - The correlation ID to propagate. If falsy, falls back to {@link getCorrelationId}.
+ * @param fn - The callback to execute within the correlation context.
+ */
+export declare function runWithCorrelationId<T>(correlationId: string | undefined, fn: () => T): T;
+/**
+ * Read the current correlation ID.
+ *
+ * It is the correlation id set by {@link runWithCorrelationId}, the HTTP
+ * middleware, or a running pipeline. Outside any, a new UUIDv7 is generated on
+ * each call, so it always returns a string.
+ *
+ * @example
+ * ```ts
+ * import { getCorrelationId } from '@cqrs-ddd/pipeline-correlation';
+ *
+ * class EmailWorker {
+ *   @WithCorrelation()
+ *   async process(job: Job) {
+ *     console.log(`Processing with correlation: ${getCorrelationId()}`);
+ *     await sendEmail(job.data);
+ *   }
+ * }
+ * ```
+ */
+export declare function getCorrelationId(): string;
+/**
+ * Utility type that adds a `correlationId` field to any data shape.
+ *
+ * Use it to type BullMQ job data, RabbitMQ payloads, Kafka messages, etc.
+ * so that the correlation ID is part of the contract.
+ *
+ * @example
+ * ```ts
+ * interface WelcomeEmailJobData {
+ *   userId: string;
+ *   email: string;
+ * }
+ *
+ * // Queue typed as Queue<WithCorrelationId<WelcomeEmailJobData>>
+ * await queue.add('send', addCorrelationId({ userId, email }));
+ * ```
+ */
+export type WithCorrelationId<T = Record<string, unknown>> = T & {
+    correlationId: string;
+};
+/**
+ * Stamp the current correlation ID onto a data object.
+ *
+ * This is the **producer-side** counterpart to {@link WithCorrelation}:
+ * - `addCorrelationId(data)` → stamps the ID when **enqueuing** a job / publishing a message
+ * - `@WithCorrelation()` → extracts the ID when **processing** the job / handling the message
+ *
+ * Both default to the `'correlationId'` key, so they work together out of the box.
+ *
+ * @throws {TypeError} If `data` is not a plain object.
+ *
+ * @example
+ * ```ts
+ * // Bull / BullMQ
+ * await queue.add('send-email', addCorrelationId({ userId, email }));
+ *
+ * // RabbitMQ (ClientProxy)
+ * this.client.emit('user.created', addCorrelationId(payload));
+ *
+ * // Kafka
+ * await this.producer.send({
+ *   topic: 'orders',
+ *   messages: [{ value: JSON.stringify(addCorrelationId(order)) }],
+ * });
+ *
+ * // PostgreSQL NOTIFY
+ * await sql`SELECT pg_notify('events', ${JSON.stringify(addCorrelationId(data))})`;
+ *
+ * // ⚠️ Arrays must be wrapped — passing one directly throws:
+ * // addCorrelationId([item1, item2]);           // ❌ TypeError
+ * addCorrelationId({ items: [item1, item2] });   // ✅
+ * ```
+ *
+ * @param data - The payload to enrich. Must be a plain object, **not** an array.
+ *              A shallow copy is returned; the original is not mutated.
+ * @returns A new object with `correlationId` added.
+ */
+export declare function addCorrelationId<T extends Record<string, unknown>>(data: T): WithCorrelationId<T>;
+/**
+ * Return a headers object stamped with the current correlation ID.
+ *
+ * Use this for **header-based** transports (Kafka, NATS, gRPC metadata, HTTP)
+ * where the correlation ID belongs in message headers / metadata — **not** in
+ * the data payload.
+ *
+ * For transports without native headers (Bull/BullMQ, PostgreSQL NOTIFY), use
+ * {@link addCorrelationId} instead.
+ *
+ * @param key - Header name. Defaults to `'x-correlation-id'`.
+ * @returns `{ [key]: correlationId }` — spread into your transport's headers.
+ *
+ * @example
+ * ```ts
+ * // Kafka
+ * await producer.send({
+ *   topic: 'orders',
+ *   messages: [{ value: JSON.stringify(order), headers: correlationHeaders() }],
+ * });
+ *
+ * // RabbitMQ (amqplib) — AMQP has a first-class correlationId property:
+ * channel.publish(exchange, key, buffer, { correlationId: getCorrelationId() });
+ * // …or in headers:
+ * channel.publish(exchange, key, buffer, { headers: correlationHeaders() });
+ *
+ * // NATS
+ * const headers = nats.headers();
+ * Object.entries(correlationHeaders()).forEach(([k, v]) => headers.set(k, v));
+ * nc.publish(subject, payload, { headers });
+ *
+ * // HTTP (outgoing)
+ * await fetch(url, { headers: { ...correlationHeaders(), 'content-type': 'application/json' } });
+ * ```
+ */
+export declare function correlationHeaders(key?: string): Record<string, string>;
+//# sourceMappingURL=correlation.store.d.ts.map

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

@@ -0,0 +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"}

package/dist/correlation.store.js

@@ -0,0 +1,176 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+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';
+const correlation = new AsyncLocalStorage();
+/**
+ * The correlation id as a context source, for `createPipeline({ sources })`
+ * of `@cqrs-ddd/pipeline` and the job context registration of
+ * `@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}.
+ *
+ * @example
+ * ```ts
+ * createPipeline({ sources: { correlationId: correlationSource } });
+ * ```
+ */
+export const correlationSource = {
+    current: () => correlation.getStore(),
+    run: (value, fn) => correlation.run(value, fn),
+    create: () => uuidv7(),
+    accepts: (id) => id.length <= DEFAULT_CORRELATION_ID_MAX_LENGTH &&
+        DEFAULT_CORRELATION_ID_PATTERN.test(id),
+};
+/**
+ * Run a callback within a correlation context.
+ *
+ * Use this in **non-HTTP entry points** (queue workers, message consumers,
+ * 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`.
+ *
+ * @example
+ * ```ts
+ * // BullMQ worker
+ * new Worker('emails', (job) =>
+ *   runWithCorrelationId(job.data.correlationId, () => sendEmail(job.data)),
+ * );
+ *
+ * // RabbitMQ consumer (amqplib)
+ * channel.consume('users', (message) =>
+ *   runWithCorrelationId(message.properties.correlationId, () =>
+ *     onUserCreated(JSON.parse(message.content.toString())),
+ *   ),
+ * );
+ *
+ * // Scheduled job: no incoming id, so a new one is made
+ * setInterval(() => runWithCorrelationId(undefined, () => hourlySync()), 3_600_000);
+ * ```
+ *
+ * @param correlationId - The correlation ID to propagate. If falsy, falls back to {@link getCorrelationId}.
+ * @param fn - The callback to execute within the correlation context.
+ */
+export function runWithCorrelationId(correlationId, fn) {
+    return correlation.run(correlationId || getCorrelationId(), fn);
+}
+/**
+ * Read the current correlation ID.
+ *
+ * It is the correlation id set by {@link runWithCorrelationId}, the HTTP
+ * middleware, or a running pipeline. Outside any, a new UUIDv7 is generated on
+ * each call, so it always returns a string.
+ *
+ * @example
+ * ```ts
+ * import { getCorrelationId } from '@cqrs-ddd/pipeline-correlation';
+ *
+ * class EmailWorker {
+ *   @WithCorrelation()
+ *   async process(job: Job) {
+ *     console.log(`Processing with correlation: ${getCorrelationId()}`);
+ *     await sendEmail(job.data);
+ *   }
+ * }
+ * ```
+ */
+export function getCorrelationId() {
+    return correlation.getStore() || correlationSource.create();
+}
+/**
+ * Stamp the current correlation ID onto a data object.
+ *
+ * This is the **producer-side** counterpart to {@link WithCorrelation}:
+ * - `addCorrelationId(data)` → stamps the ID when **enqueuing** a job / publishing a message
+ * - `@WithCorrelation()` → extracts the ID when **processing** the job / handling the message
+ *
+ * Both default to the `'correlationId'` key, so they work together out of the box.
+ *
+ * @throws {TypeError} If `data` is not a plain object.
+ *
+ * @example
+ * ```ts
+ * // Bull / BullMQ
+ * await queue.add('send-email', addCorrelationId({ userId, email }));
+ *
+ * // RabbitMQ (ClientProxy)
+ * this.client.emit('user.created', addCorrelationId(payload));
+ *
+ * // Kafka
+ * await this.producer.send({
+ *   topic: 'orders',
+ *   messages: [{ value: JSON.stringify(addCorrelationId(order)) }],
+ * });
+ *
+ * // PostgreSQL NOTIFY
+ * await sql`SELECT pg_notify('events', ${JSON.stringify(addCorrelationId(data))})`;
+ *
+ * // ⚠️ Arrays must be wrapped — passing one directly throws:
+ * // addCorrelationId([item1, item2]);           // ❌ TypeError
+ * addCorrelationId({ items: [item1, item2] });   // ✅
+ * ```
+ *
+ * @param data - The payload to enrich. Must be a plain object, **not** an array.
+ *              A shallow copy is returned; the original is not mutated.
+ * @returns A new object with `correlationId` added.
+ */
+export function addCorrelationId(data) {
+    const prototype = data !== null && typeof data === 'object'
+        ? Object.getPrototypeOf(data)
+        : undefined;
+    if (prototype !== Object.prototype && prototype !== null) {
+        throw new TypeError('addCorrelationId(data) requires a plain object payload. ' +
+            'Wrap arrays and class instances in a plain object first.');
+    }
+    return { ...data, correlationId: getCorrelationId() };
+}
+/**
+ * Return a headers object stamped with the current correlation ID.
+ *
+ * Use this for **header-based** transports (Kafka, NATS, gRPC metadata, HTTP)
+ * where the correlation ID belongs in message headers / metadata — **not** in
+ * the data payload.
+ *
+ * For transports without native headers (Bull/BullMQ, PostgreSQL NOTIFY), use
+ * {@link addCorrelationId} instead.
+ *
+ * @param key - Header name. Defaults to `'x-correlation-id'`.
+ * @returns `{ [key]: correlationId }` — spread into your transport's headers.
+ *
+ * @example
+ * ```ts
+ * // Kafka
+ * await producer.send({
+ *   topic: 'orders',
+ *   messages: [{ value: JSON.stringify(order), headers: correlationHeaders() }],
+ * });
+ *
+ * // RabbitMQ (amqplib) — AMQP has a first-class correlationId property:
+ * channel.publish(exchange, key, buffer, { correlationId: getCorrelationId() });
+ * // …or in headers:
+ * channel.publish(exchange, key, buffer, { headers: correlationHeaders() });
+ *
+ * // NATS
+ * const headers = nats.headers();
+ * Object.entries(correlationHeaders()).forEach(([k, v]) => headers.set(k, v));
+ * nc.publish(subject, payload, { headers });
+ *
+ * // HTTP (outgoing)
+ * await fetch(url, { headers: { ...correlationHeaders(), 'content-type': 'application/json' } });
+ * ```
+ */
+export function correlationHeaders(key = DEFAULT_CORRELATION_HEADER) {
+    return { [key]: getCorrelationId() };
+}
+//# sourceMappingURL=correlation.store.js.map

package/dist/correlation.store.js.map

@@ -0,0 +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"}

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

@@ -0,0 +1,184 @@
+import { type DualMethodDecorator } from '../helpers/method-decorator.js';
+/**
+ * A function that extracts the correlation ID from the method arguments.
+ *
+ * Receives the same arguments the decorated method receives.
+ * Return `undefined` to keep the current id, or get a new one from
+ * `correlationSource.create()` when there is none.
+ */
+export type CorrelationExtractor = (...args: unknown[]) => string | undefined;
+/**
+ * Options for the {@link WithCorrelation} decorator.
+ */
+export interface CorrelationDecoratorOptions {
+    /**
+     * Property path (dot-notation) to the correlation ID in the **first argument**.
+     *
+     * - For Bull: `'data.correlationId'` (default)
+     * - For a flat object: `'correlationId'`
+     * - For deeply nested: `'metadata.tracing.correlationId'`
+     *
+     * Ignored when `extract` is provided.
+     *
+     * @default 'data.correlationId'
+     */
+    path?: string;
+    /**
+     * Custom extractor function. Receives all method arguments.
+     * Takes precedence over `path`.
+     *
+     * @example
+     * ```ts
+     * // RabbitMQ
+     * extract: (data, ctx) => ctx.getMessage().properties.correlationId
+     *
+     * // Kafka
+     * extract: (data, ctx) =>
+     *   ctx.getMessage().headers?.['x-correlation-id']?.toString()
+     * ```
+     */
+    extract?: CorrelationExtractor;
+    /**
+     * Log level for the start of the method execution.
+     *
+     * - Any {@link LogLevel} value routes to the logger method of that name (`'log'`, `'debug'`, `'verbose'`, `'warn'`, `'error'`).
+     * - `'none'` suppresses the log message entirely.
+     *
+     * A pino-backed logger maps the levels as `'verbose'` → `trace`, `'debug'` → `debug`,
+     * `'log'` → `info`, `'warn'` → `warn`, `'error'` → `error`, `'fatal'` → `fatal`.
+     *
+     * @default 'debug'
+     *
+     * @example
+     * ```ts
+     * // Uses default 'debug' level
+     * @WithCorrelation()
+     *
+     * // Log at 'verbose' level
+     * @WithCorrelation({ logLevel: 'verbose' })
+     *
+     * // Suppress the log message
+     * @WithCorrelation({ logLevel: 'none' })
+     * ```
+     */
+    logLevel?: LogLevel | 'none';
+    /**
+     * Logger to write through instead of the decorated instance's `logger` property or
+     * `console`.
+     *
+     * Accepts any object with the methods of {@link CorrelationLogger}
+     * (e.g. a Pino or Winston adapter).
+     *
+     * @example
+     * ```ts
+     * @WithCorrelation({ logger: myPinoLogger })
+     * async handleJob(job: Job) { ... }
+     * ```
+     */
+    logger?: CorrelationLogger;
+}
+/** The levels `@WithCorrelation` logs at, named as NestJS names them. */
+export type LogLevel = 'log' | 'error' | 'warn' | 'debug' | 'verbose' | 'fatal';
+/**
+ * The logger `@WithCorrelation` writes through; `console`, a NestJS `LoggerService` and
+ * pino or winston adapters satisfy it.
+ */
+export interface CorrelationLogger {
+    log(message: unknown, ...optionalParams: unknown[]): unknown;
+    warn(message: unknown, ...optionalParams: unknown[]): unknown;
+    debug?(message: unknown, ...optionalParams: unknown[]): unknown;
+    verbose?(message: unknown, ...optionalParams: unknown[]): unknown;
+    error?(message: unknown, ...optionalParams: unknown[]): unknown;
+    fatal?(message: unknown, ...optionalParams: unknown[]): unknown;
+}
+/**
+ * Queue-agnostic `MethodDecorator` that propagates a correlation ID into the
+ * pipeline's async-local correlation context.
+ *
+ * Place it **under** any transport or scheduling decorator a framework adds. It does
+ * 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.
+ *
+ * **⚠️ Array payloads:**
+ * When using the default dot-path extraction, the first argument must be an
+ * object (e.g. a Bull `Job`). If it is an array, the dot-path cannot resolve
+ * and the decorator logs a warning at runtime. For transports that
+ * deliver an array as the first argument, use the `extract` option:
+ * ```ts
+ * @WithCorrelation({ extract: (items) => items?.[0]?.correlationId })
+ * ```
+ *
+ * Inside the method body, read the active ID with:
+ * ```ts
+ * import { getCorrelationId } from '@cqrs-ddd/pipeline-correlation';
+ * const id = getCorrelationId();
+ * ```
+ *
+ * @example
+ * ```ts
+ * class Consumers {
+ *   // BullMQ job (default path: data.correlationId)
+ *   @WithCorrelation()
+ *   async sendEmail(job: Job) {
+ *     await mailer.send(job.data);
+ *   }
+ *
+ *   // Another key in the job data
+ *   @WithCorrelation('data.x-request-id')
+ *   async sendSms(job: Job) {}
+ *
+ *   // RabbitMQ message (amqplib)
+ *   @WithCorrelation({ extract: (message) => message.properties.correlationId })
+ *   async onUserCreated(message: ConsumeMessage) {}
+ *
+ *   // Kafka message (kafkajs)
+ *   @WithCorrelation({
+ *     extract: ({ message }) => message.headers?.['x-correlation-id']?.toString(),
+ *   })
+ *   async onOrderPlaced(payload: EachMessagePayload) {}
+ *
+ *   // PostgreSQL LISTEN/NOTIFY
+ *   @WithCorrelation({ path: 'correlationId' })
+ *   async onNotification(notification: { correlationId?: string }) {}
+ *
+ *   // Scheduled job: no id in the arguments, so a new one is made
+ *   @WithCorrelation()
+ *   async hourlySync() {}
+ * }
+ * ```
+ */
+export declare function WithCorrelation(): DualMethodDecorator;
+export declare function WithCorrelation(path: string): DualMethodDecorator;
+export declare function WithCorrelation(options: CorrelationDecoratorOptions): DualMethodDecorator;
+/**
+ * Pre-built extraction presets for {@link WithCorrelation}, for transports whose
+ * handlers receive the correlation id in metadata rather than in the payload.
+ *
+ * For transports that carry it in the payload (BullMQ, PostgreSQL NOTIFY), use
+ * the bare `@WithCorrelation()` or a `path`; for any other shape, an `extract`
+ * function.
+ *
+ * @example
+ * ```ts
+ * class Users {
+ *   // gRPC (@grpc/grpc-js): (request, metadata)
+ *   @WithCorrelation(CorrelationFrom.grpc())
+ *   async findOne(request: FindOneRequest, metadata: Metadata) {}
+ * }
+ * ```
+ */
+export declare const CorrelationFrom: {
+    /**
+     * gRPC — extracts from gRPC `Metadata` (second argument).
+     *
+     * In gRPC handlers the signature is `(data, metadata, call)`.
+     *
+     * @param key - Metadata key. Defaults to `'x-correlation-id'`.
+     */
+    readonly grpc: (key?: string) => CorrelationDecoratorOptions;
+};
+//# sourceMappingURL=with-correlation.decorator.d.ts.map

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

@@ -0,0 +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"}