logixia 2.0.4 → 2.0.6

package/dist/correlation.d.mts

@@ -1,55 +1,4 @@
-/**
- * logixia — Microservices Correlation ID Propagation
- *
- * Provides zero-boilerplate correlation ID generation and propagation for
- * distributed systems. A single correlation ID travels through every service
- * in a request fan-out, making it trivial to join logs across services.
- *
- * Features:
- *  - UUID v4 correlation ID generation (via `crypto.randomUUID()`)
- *  - Express / Fastify / NestJS incoming-request middleware
- *  - `correlationFetch()` — wraps global `fetch`, auto-injects `X-Correlation-ID`
- *  - `createCorrelationAxiosInterceptor()` — axios request interceptor
- *  - `childFromRequest(req, logger)` — child logger with all request identifiers
- *  - Kafka / SQS / RabbitMQ message context helpers
- *  - Integration with `LogixiaContext` (AsyncLocalStorage) so every `logger.info()`
- *    call automatically includes the correlationId without per-call passing.
- *
- * @example Express middleware
- * ```ts
- * import { correlationMiddleware } from 'logixia/correlation';
- * import { logger } from 'logixia';
- *
- * app.use(correlationMiddleware());
- *
- * app.get('/orders', (req, res) => {
- *   // correlationId is automatically in every log inside this request
- *   logger.info('Listing orders');
- *   res.json({ ok: true });
- * });
- * ```
- *
- * @example Outbound fetch with correlation
- * ```ts
- * import { correlationFetch } from 'logixia/correlation';
- *
- * // Reads correlationId from current LogixiaContext and injects it as header
- * const data = await correlationFetch('https://payments.internal/charge', {
- *   method: 'POST',
- *   body: JSON.stringify({ amount: 100 }),
- * });
- * ```
- *
- * @example Manual correlation context
- * ```ts
- * import { withCorrelationId } from 'logixia/correlation';
- *
- * await withCorrelationId('trace-abc-123', async () => {
- *   // All logs and outbound fetch calls in here carry 'trace-abc-123'
- *   await processOrder();
- * });
- * ```
- */
+import { n as HttpResponseShape, t as HttpRequestShape } from "./http-shapes-BnBkJcid.mjs";
 /** Fields injected into the log context by the correlation middleware. */
 export interface CorrelationContext {
   correlationId: string;
@@ -132,7 +81,7 @@ export declare function withCorrelationId<T>(correlationId: string | undefined,
  * app.use(correlationMiddleware());
  * ```
  */
-export declare function correlationMiddleware(options?: CorrelationMiddlewareOptions): (req: Record<string, unknown>, res: Record<string, unknown>, next: () => void) => void;
+export declare function correlationMiddleware(options?: CorrelationMiddlewareOptions): (req: HttpRequestShape, res: HttpResponseShape, next: () => void) => void;
 /**
  * Fastify `onRequest` lifecycle hook — same functionality as `correlationMiddleware`
  * but adapted to Fastify's hook API.
@@ -143,7 +92,7 @@ export declare function correlationMiddleware(options?: CorrelationMiddlewareOpt
  * fastify.addHook('onRequest', correlationFastifyHook());
  * ```
  */
-export declare function correlationFastifyHook(options?: CorrelationMiddlewareOptions): (request: Record<string, unknown>, reply: Record<string, unknown>, done: () => void) => void;
+export declare function correlationFastifyHook(options?: CorrelationMiddlewareOptions): (request: HttpRequestShape, reply: HttpResponseShape, done: () => void) => void;
 /**
  * A drop-in replacement for `fetch` that automatically injects the current
  * `correlationId` from `LogixiaContext` as an `X-Correlation-ID` request header.
@@ -223,7 +172,7 @@ export interface ChildFromRequestOptions {
  */
 export declare function childFromRequest<TLogger extends {
   child(...args: never[]): TLogger;
-}>(req: Record<string, unknown>, logger: TLogger, options?: ChildFromRequestOptions): TLogger;
+}>(req: HttpRequestShape, logger: TLogger, options?: ChildFromRequestOptions): TLogger;
 /**
  * Extract a correlation context from a Kafka / RabbitMQ / SQS message object.
  *

package/dist/correlation.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"correlation.d.mts","names":[],"sources":["../src/correlation.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA6DiB;EACf;EACA;;EAEA;;GAEC;;iBAGc;;;;;EAKf;;;;;EAKA;;;;;EAKA;;;;;;;EAOA;;;;;;EAMA;;;;;;;;;;;;wBAec;;;;;wBAwBA;;;;;;;;;;;;;;wBAkBA,kBAAkB,GAAG,mCAAmC,gBAAgB,IAAI;;;;;;;;;;;;;;wBAoB5E,sBAAsB,UAAS,gCAU3C,KAAK,yBACL,KAAK,yBACL;;;;;;;;;;;wBAqCY,uBAAuB,UAAS,gCAU5C,SAAS,yBACT,OAAO,yBACP;;;;;;;;;;;;;;;;;;wBA4CkB,iBACpB,gBAAgB,MAAM,SACtB,OAAM,aACN;EAAW;IACV,QAAQ;;;;;;;;;;;;;wBAwCK,kCACd;EAAW;KACT,QAAQ,4BAA4B;iBAuBvB;;EAEf;;;;;;;EAOA;;;;;;;EAOA;;;;;;;;;;;;;;;;;;;;;;;;;;wBA2Bc,iBAAiB;EAAkB,SAAS,gBAAgB;GAC1E,KAAK,yBACL,QAAQ,SACR,UAAS,0BACR;;;;;;;;;;;;;;;;;;;wBA+Ea,4BAA4B,SAAS;;;;;;;;;;;;;;wBAyCrC,gCAAgC"}
+{"version":3,"file":"correlation.d.mts","names":[],"sources":["../src/correlation.ts"],"mappings":";;iBA8DiB;EACf;EACA;;EAEA;;GAEC;;iBAGc;;;;;EAKf;;;;;EAKA;;;;;EAKA;;;;;;;EAOA;;;;;;EAMA;;;;;;;;;;;;wBAec;;;;;wBAwBA;;;;;;;;;;;;;;wBAkBA,kBAAkB,GAAG,mCAAmC,gBAAgB,IAAI;;;;;;;;;;;;;;wBAoB5E,sBAAsB,UAAS,gCAU3C,KAAK,kBACL,KAAK,mBACL;;;;;;;;;;;wBAkCY,uBAAuB,UAAS,gCAU5C,SAAS,kBACT,OAAO,mBACP;;;;;;;;;;;;;;;;;;wBAyCkB,iBACpB,gBAAgB,MAAM,SACtB,OAAM,aACN;EAAW;IACV,QAAQ;;;;;;;;;;;;;wBAwCK,kCACd;EAAW;KACT,QAAQ,4BAA4B;iBAuBvB;;EAEf;;;;;;;EAOA;;;;;;;EAOA;;;;;;;;;;;;;;;;;;;;;;;;;;wBA2Bc,iBAAiB;EAAkB,SAAS,gBAAgB;GAC1E,KAAK,kBACL,QAAQ,SACR,UAAS,0BACR;;;;;;;;;;;;;;;;;;;wBA+Ea,4BAA4B,SAAS;;;;;;;;;;;;;;wBAyCrC,gCAAgC"}

package/dist/correlation.d.ts

@@ -1,55 +1,4 @@
-/**
- * logixia — Microservices Correlation ID Propagation
- *
- * Provides zero-boilerplate correlation ID generation and propagation for
- * distributed systems. A single correlation ID travels through every service
- * in a request fan-out, making it trivial to join logs across services.
- *
- * Features:
- *  - UUID v4 correlation ID generation (via `crypto.randomUUID()`)
- *  - Express / Fastify / NestJS incoming-request middleware
- *  - `correlationFetch()` — wraps global `fetch`, auto-injects `X-Correlation-ID`
- *  - `createCorrelationAxiosInterceptor()` — axios request interceptor
- *  - `childFromRequest(req, logger)` — child logger with all request identifiers
- *  - Kafka / SQS / RabbitMQ message context helpers
- *  - Integration with `LogixiaContext` (AsyncLocalStorage) so every `logger.info()`
- *    call automatically includes the correlationId without per-call passing.
- *
- * @example Express middleware
- * ```ts
- * import { correlationMiddleware } from 'logixia/correlation';
- * import { logger } from 'logixia';
- *
- * app.use(correlationMiddleware());
- *
- * app.get('/orders', (req, res) => {
- *   // correlationId is automatically in every log inside this request
- *   logger.info('Listing orders');
- *   res.json({ ok: true });
- * });
- * ```
- *
- * @example Outbound fetch with correlation
- * ```ts
- * import { correlationFetch } from 'logixia/correlation';
- *
- * // Reads correlationId from current LogixiaContext and injects it as header
- * const data = await correlationFetch('https://payments.internal/charge', {
- *   method: 'POST',
- *   body: JSON.stringify({ amount: 100 }),
- * });
- * ```
- *
- * @example Manual correlation context
- * ```ts
- * import { withCorrelationId } from 'logixia/correlation';
- *
- * await withCorrelationId('trace-abc-123', async () => {
- *   // All logs and outbound fetch calls in here carry 'trace-abc-123'
- *   await processOrder();
- * });
- * ```
- */
+import { n as HttpResponseShape, t as HttpRequestShape } from "./http-shapes-BnBkJcid.js";
 /** Fields injected into the log context by the correlation middleware. */
 export interface CorrelationContext {
   correlationId: string;
@@ -132,7 +81,7 @@ export declare function withCorrelationId<T>(correlationId: string | undefined,
  * app.use(correlationMiddleware());
  * ```
  */
-export declare function correlationMiddleware(options?: CorrelationMiddlewareOptions): (req: Record<string, unknown>, res: Record<string, unknown>, next: () => void) => void;
+export declare function correlationMiddleware(options?: CorrelationMiddlewareOptions): (req: HttpRequestShape, res: HttpResponseShape, next: () => void) => void;
 /**
  * Fastify `onRequest` lifecycle hook — same functionality as `correlationMiddleware`
  * but adapted to Fastify's hook API.
@@ -143,7 +92,7 @@ export declare function correlationMiddleware(options?: CorrelationMiddlewareOpt
  * fastify.addHook('onRequest', correlationFastifyHook());
  * ```
  */
-export declare function correlationFastifyHook(options?: CorrelationMiddlewareOptions): (request: Record<string, unknown>, reply: Record<string, unknown>, done: () => void) => void;
+export declare function correlationFastifyHook(options?: CorrelationMiddlewareOptions): (request: HttpRequestShape, reply: HttpResponseShape, done: () => void) => void;
 /**
  * A drop-in replacement for `fetch` that automatically injects the current
  * `correlationId` from `LogixiaContext` as an `X-Correlation-ID` request header.
@@ -223,7 +172,7 @@ export interface ChildFromRequestOptions {
  */
 export declare function childFromRequest<TLogger extends {
   child(...args: never[]): TLogger;
-}>(req: Record<string, unknown>, logger: TLogger, options?: ChildFromRequestOptions): TLogger;
+}>(req: HttpRequestShape, logger: TLogger, options?: ChildFromRequestOptions): TLogger;
 /**
  * Extract a correlation context from a Kafka / RabbitMQ / SQS message object.
  *

package/dist/correlation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"correlation.d.ts","names":[],"sources":["../src/correlation.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA6DiB;EACf;EACA;;EAEA;;GAEC;;iBAGc;;;;;EAKf;;;;;EAKA;;;;;EAKA;;;;;;;EAOA;;;;;;EAMA;;;;;;;;;;;;wBAec;;;;;wBAwBA;;;;;;;;;;;;;;wBAkBA,kBAAkB,GAAG,mCAAmC,gBAAgB,IAAI;;;;;;;;;;;;;;wBAoB5E,sBAAsB,UAAS,gCAU3C,KAAK,yBACL,KAAK,yBACL;;;;;;;;;;;wBAqCY,uBAAuB,UAAS,gCAU5C,SAAS,yBACT,OAAO,yBACP;;;;;;;;;;;;;;;;;;wBA4CkB,iBACpB,gBAAgB,MAAM,SACtB,OAAM,aACN;EAAW;IACV,QAAQ;;;;;;;;;;;;;wBAwCK,kCACd;EAAW;KACT,QAAQ,4BAA4B;iBAuBvB;;EAEf;;;;;;;EAOA;;;;;;;EAOA;;;;;;;;;;;;;;;;;;;;;;;;;;wBA2Bc,iBAAiB;EAAkB,SAAS,gBAAgB;GAC1E,KAAK,yBACL,QAAQ,SACR,UAAS,0BACR;;;;;;;;;;;;;;;;;;;wBA+Ea,4BAA4B,SAAS;;;;;;;;;;;;;;wBAyCrC,gCAAgC"}
+{"version":3,"file":"correlation.d.ts","names":[],"sources":["../src/correlation.ts"],"mappings":";;iBA8DiB;EACf;EACA;;EAEA;;GAEC;;iBAGc;;;;;EAKf;;;;;EAKA;;;;;EAKA;;;;;;;EAOA;;;;;;EAMA;;;;;;;;;;;;wBAec;;;;;wBAwBA;;;;;;;;;;;;;;wBAkBA,kBAAkB,GAAG,mCAAmC,gBAAgB,IAAI;;;;;;;;;;;;;;wBAoB5E,sBAAsB,UAAS,gCAU3C,KAAK,kBACL,KAAK,mBACL;;;;;;;;;;;wBAkCY,uBAAuB,UAAS,gCAU5C,SAAS,kBACT,OAAO,mBACP;;;;;;;;;;;;;;;;;;wBAyCkB,iBACpB,gBAAgB,MAAM,SACtB,OAAM,aACN;EAAW;IACV,QAAQ;;;;;;;;;;;;;wBAwCK,kCACd;EAAW;KACT,QAAQ,4BAA4B;iBAuBvB;;EAEf;;;;;;;EAOA;;;;;;;EAOA;;;;;;;;;;;;;;;;;;;;;;;;;;wBA2Bc,iBAAiB;EAAkB,SAAS,gBAAgB;GAC1E,KAAK,kBACL,QAAQ,SACR,UAAS,0BACR;;;;;;;;;;;;;;;;;;;wBA+Ea,4BAA4B,SAAS;;;;;;;;;;;;;;wBAyCrC,gCAAgC"}

package/dist/correlation.js

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_request_trace = require("./request-trace-wTJdKp6-.js");
-const require_async_context = require("./async-context-DTQgi8f7.js");
+const require_request_trace = require("./request-trace-ByujsUZk.js");
+const require_async_context = require("./async-context-DUFMDYAr.js");
 let node_crypto = require("node:crypto");
 // src/correlation.ts
 /**
@@ -120,12 +120,12 @@ function withCorrelationId(correlationId, callback) {
 function correlationMiddleware(options = {}) {
 	const { header = "x-correlation-id", originServiceHeader = "x-origin-service", generate = generateCorrelationId, trustIncoming = true, setResponseHeader = true } = options;
 	return function logixiaCorrelationMiddleware(req, res, next) {
-		const headers = req["headers"] ?? {};
+		const headers = req.headers ?? {};
 		const correlationId = (trustIncoming ? validIncomingId(headers[header.toLowerCase()]) : void 0) ?? generate();
 		const originService = validIncomingId(headers[originServiceHeader.toLowerCase()]);
 		if (setResponseHeader) {
-			const setHeader = res["setHeader"];
-			if (typeof setHeader === "function") setHeader.call(res, header, correlationId);
+			var _res$setHeader;
+			(_res$setHeader = res.setHeader) === null || _res$setHeader === void 0 || _res$setHeader.call(res, header, correlationId);
 		}
 		const ctx = {
 			correlationId,
@@ -147,12 +147,12 @@ function correlationMiddleware(options = {}) {
 function correlationFastifyHook(options = {}) {
 	const { header = "x-correlation-id", originServiceHeader = "x-origin-service", generate = generateCorrelationId, trustIncoming = true, setResponseHeader = true } = options;
 	return function logixiaCorrelationFastifyHook(request, reply, done) {
-		const headers = request["headers"] ?? {};
+		const headers = request.headers ?? {};
 		const correlationId = (trustIncoming ? validIncomingId(headers[header.toLowerCase()]) : void 0) ?? generate();
 		const originService = validIncomingId(headers[originServiceHeader.toLowerCase()]);
 		if (setResponseHeader) {
-			const replyHeader = reply["header"];
-			if (typeof replyHeader === "function") replyHeader.call(reply, header, correlationId);
+			var _reply$header;
+			(_reply$header = reply.header) === null || _reply$header === void 0 || _reply$header.call(reply, header, correlationId);
 		}
 		const ctx = {
 			correlationId,
@@ -242,10 +242,10 @@ const MAX_IP_LENGTH = 64;
 */
 function childFromRequest(req, logger, options = {}) {
 	const correlationHeader = options.correlationHeader ?? "x-correlation-id";
-	const headers = req["headers"] ?? {};
+	const headers = req.headers ?? {};
 	const correlationId = validIncomingId(headers[correlationHeader.toLowerCase()]) ?? getCurrentCorrelationId() ?? generateCorrelationId();
-	const method = req["method"];
-	const url = req["url"] ?? req["originalUrl"];
+	const method = req.method;
+	const url = req.url ?? req.originalUrl;
 	const rawUserAgent = headers["user-agent"];
 	const userAgent = typeof rawUserAgent === "string" ? rawUserAgent.slice(0, MAX_USER_AGENT_LENGTH) : void 0;
 	const ip = resolveClientIp(req, headers, options.trustProxy === true);
@@ -274,9 +274,9 @@ function resolveClientIp(req, headers, trustProxy) {
 		const first = typeof forwarded === "string" ? (_forwarded$split$ = forwarded.split(",")[0]) === null || _forwarded$split$ === void 0 ? void 0 : _forwarded$split$.trim() : void 0;
 		if (first) return first.slice(0, MAX_IP_LENGTH);
 	}
-	const fromReq = req["ip"];
+	const fromReq = req.ip;
 	if (typeof fromReq === "string" && fromReq) return fromReq.slice(0, MAX_IP_LENGTH);
-	const remote = (_req$socket = req["socket"]) === null || _req$socket === void 0 ? void 0 : _req$socket["remoteAddress"];
+	const remote = (_req$socket = req.socket) === null || _req$socket === void 0 ? void 0 : _req$socket.remoteAddress;
 	return typeof remote === "string" ? remote.slice(0, MAX_IP_LENGTH) : void 0;
 }
 /**

package/dist/correlation.js.map

@@ -1 +1 @@
-{"version":3,"file":"correlation.js","names":["randomUUID","sanitizeIncomingId","LogixiaContext"],"sources":["../src/correlation.ts"],"sourcesContent":["/**\n * logixia — Microservices Correlation ID Propagation\n *\n * Provides zero-boilerplate correlation ID generation and propagation for\n * distributed systems. A single correlation ID travels through every service\n * in a request fan-out, making it trivial to join logs across services.\n *\n * Features:\n *  - UUID v4 correlation ID generation (via `crypto.randomUUID()`)\n *  - Express / Fastify / NestJS incoming-request middleware\n *  - `correlationFetch()` — wraps global `fetch`, auto-injects `X-Correlation-ID`\n *  - `createCorrelationAxiosInterceptor()` — axios request interceptor\n *  - `childFromRequest(req, logger)` — child logger with all request identifiers\n *  - Kafka / SQS / RabbitMQ message context helpers\n *  - Integration with `LogixiaContext` (AsyncLocalStorage) so every `logger.info()`\n *    call automatically includes the correlationId without per-call passing.\n *\n * @example Express middleware\n * ```ts\n * import { correlationMiddleware } from 'logixia/correlation';\n * import { logger } from 'logixia';\n *\n * app.use(correlationMiddleware());\n *\n * app.get('/orders', (req, res) => {\n *   // correlationId is automatically in every log inside this request\n *   logger.info('Listing orders');\n *   res.json({ ok: true });\n * });\n * ```\n *\n * @example Outbound fetch with correlation\n * ```ts\n * import { correlationFetch } from 'logixia/correlation';\n *\n * // Reads correlationId from current LogixiaContext and injects it as header\n * const data = await correlationFetch('https://payments.internal/charge', {\n *   method: 'POST',\n *   body: JSON.stringify({ amount: 100 }),\n * });\n * ```\n *\n * @example Manual correlation context\n * ```ts\n * import { withCorrelationId } from 'logixia/correlation';\n *\n * await withCorrelationId('trace-abc-123', async () => {\n *   // All logs and outbound fetch calls in here carry 'trace-abc-123'\n *   await processOrder();\n * });\n * ```\n */\n\nimport { randomUUID } from 'node:crypto';\n\nimport { LogixiaContext } from './context/async-context';\nimport { sanitizeIncomingId } from './utils/trace.utils';\n\n// ── Types ─────────────────────────────────────────────────────────────────────\n\n/** Fields injected into the log context by the correlation middleware. */\nexport interface CorrelationContext {\n  correlationId: string;\n  traceId?: string;\n  /** Service that originated the request (from `X-Origin-Service` header). */\n  originService?: string;\n  /** Index signature so CorrelationContext is assignable to LogContext. */\n  [key: string]: unknown;\n}\n\nexport interface CorrelationMiddlewareOptions {\n  /**\n   * HTTP header to read/write the correlation ID from/to.\n   * @default 'x-correlation-id'\n   */\n  header?: string;\n  /**\n   * HTTP header for the originating service name.\n   * @default 'x-origin-service'\n   */\n  originServiceHeader?: string;\n  /**\n   * Function to generate a new correlation ID when none is present in the request.\n   * @default () => crypto.randomUUID()\n   */\n  generate?: () => string;\n  /**\n   * When `false`, the incoming correlation header is ignored and a new ID is\n   * always generated. Use this at the edge when client-supplied IDs should not\n   * be trusted.\n   * @default true\n   */\n  trustIncoming?: boolean;\n  /**\n   * When `true`, the response will include the correlation ID header so\n   * clients can log it client-side.\n   * @default true\n   */\n  setResponseHeader?: boolean;\n}\n\n// ── ID generation ─────────────────────────────────────────────────────────────\n\n/**\n * Generate a new correlation ID using `crypto.randomUUID()` (available in\n * Node.js 14.17+, all modern browsers, and Edge runtimes).\n *\n * When the Web Crypto global is unavailable (e.g. Node 18 without\n * `--experimental-global-webcrypto`), fall back to `node:crypto`'s\n * `randomUUID`, which returns a proper UUID v4 — matching the shape this\n * function's JSDoc and README promise. `logixia/correlation` is Node-only\n * (it builds on `AsyncLocalStorage`), so importing `node:crypto` is safe here.\n */\nexport function generateCorrelationId(): string {\n  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {\n    return crypto.randomUUID();\n  }\n  return randomUUID();\n}\n\n/**\n * Return an incoming correlation ID only if it is short and made of safe\n * characters. Anything else (over-long, empty, or containing newlines or other\n * control characters) is dropped so the caller generates a fresh ID instead of\n * writing client-supplied text into every log line.\n */\nfunction validIncomingId(value: unknown): string | undefined {\n  if (typeof value === 'string' && value.trim() !== value) return undefined;\n  return sanitizeIncomingId(value);\n}\n\n// ── Context helpers ───────────────────────────────────────────────────────────\n\n/**\n * Return the correlation ID from the current `LogixiaContext`, or `undefined`\n * when called outside any context scope.\n */\nexport function getCurrentCorrelationId(): string | undefined {\n  const ctx = LogixiaContext.get();\n  return ctx?.correlationId as string | undefined;\n}\n\n/**\n * Run `callback` inside a correlation context scope.\n *\n * If a correlation ID is not provided, a new UUID is generated.\n *\n * @example\n * ```ts\n * await withCorrelationId('cid-abc', async () => {\n *   logger.info('Processing message'); // → { correlationId: 'cid-abc', ... }\n *   await callDownstream();            // correlationFetch() picks up cid-abc\n * });\n * ```\n */\nexport function withCorrelationId<T>(correlationId: string | undefined, callback: () => T): T {\n  const id = correlationId ?? generateCorrelationId();\n  return LogixiaContext.run({ correlationId: id }, callback);\n}\n\n// ── Express / Connect middleware ──────────────────────────────────────────────\n\n/**\n * Express-compatible middleware that:\n * 1. Reads `X-Correlation-ID` from the incoming request (or generates a new one)\n * 2. Wraps the request in a `LogixiaContext` so all loggers in the handler\n *    automatically include `correlationId`\n * 3. Writes the correlation ID back to the response header (opt-out via options)\n *\n * @example\n * ```ts\n * import { correlationMiddleware } from 'logixia/correlation';\n * app.use(correlationMiddleware());\n * ```\n */\nexport function correlationMiddleware(options: CorrelationMiddlewareOptions = {}) {\n  const {\n    header = 'x-correlation-id',\n    originServiceHeader = 'x-origin-service',\n    generate = generateCorrelationId,\n    trustIncoming = true,\n    setResponseHeader = true,\n  } = options;\n\n  return function logixiaCorrelationMiddleware(\n    req: Record<string, unknown>,\n    res: Record<string, unknown>,\n    next: () => void\n  ): void {\n    const headers = (req['headers'] ?? {}) as Record<string, string | undefined>;\n\n    // Node lower-cases incoming header names, so look up with lower-cased keys.\n    const incomingId = trustIncoming ? validIncomingId(headers[header.toLowerCase()]) : undefined;\n    const correlationId = incomingId ?? generate();\n    const originService = validIncomingId(headers[originServiceHeader.toLowerCase()]);\n\n    if (setResponseHeader) {\n      const setHeader = res['setHeader'] as ((name: string, value: string) => void) | undefined;\n      if (typeof setHeader === 'function') {\n        setHeader.call(res, header, correlationId);\n      }\n    }\n\n    const ctx: CorrelationContext = {\n      correlationId,\n      ...(originService !== undefined ? { originService } : {}),\n    };\n\n    LogixiaContext.run(ctx, next);\n  };\n}\n\n// ── Fastify hook ──────────────────────────────────────────────────────────────\n\n/**\n * Fastify `onRequest` lifecycle hook — same functionality as `correlationMiddleware`\n * but adapted to Fastify's hook API.\n *\n * @example\n * ```ts\n * import { correlationFastifyHook } from 'logixia/correlation';\n * fastify.addHook('onRequest', correlationFastifyHook());\n * ```\n */\nexport function correlationFastifyHook(options: CorrelationMiddlewareOptions = {}) {\n  const {\n    header = 'x-correlation-id',\n    originServiceHeader = 'x-origin-service',\n    generate = generateCorrelationId,\n    trustIncoming = true,\n    setResponseHeader = true,\n  } = options;\n\n  return function logixiaCorrelationFastifyHook(\n    request: Record<string, unknown>,\n    reply: Record<string, unknown>,\n    done: () => void\n  ): void {\n    const headers = (request['headers'] ?? {}) as Record<string, string | undefined>;\n\n    // Node lower-cases incoming header names, so look up with lower-cased keys.\n    const incomingId = trustIncoming ? validIncomingId(headers[header.toLowerCase()]) : undefined;\n    const correlationId = incomingId ?? generate();\n    const originService = validIncomingId(headers[originServiceHeader.toLowerCase()]);\n\n    if (setResponseHeader) {\n      const replyHeader = reply['header'] as ((name: string, value: string) => void) | undefined;\n      if (typeof replyHeader === 'function') {\n        replyHeader.call(reply, header, correlationId);\n      }\n    }\n\n    const ctx: CorrelationContext = {\n      correlationId,\n      ...(originService !== undefined ? { originService } : {}),\n    };\n\n    LogixiaContext.run(ctx, done);\n  };\n}\n\n// ── Outbound fetch wrapper ────────────────────────────────────────────────────\n\n/**\n * A drop-in replacement for `fetch` that automatically injects the current\n * `correlationId` from `LogixiaContext` as an `X-Correlation-ID` request header.\n *\n * Falls back to the global `fetch` when no correlation context is active.\n *\n * @example\n * ```ts\n * import { correlationFetch } from 'logixia/correlation';\n *\n * // Inside a request handler with correlationMiddleware active:\n * const response = await correlationFetch('https://payments.internal/v1/charge', {\n *   method: 'POST',\n *   body: JSON.stringify({ amount: 100 }),\n * });\n * ```\n */\nexport async function correlationFetch(\n  input: string | URL | Request,\n  init: RequestInit = {},\n  options: { header?: string } = {}\n): Promise<Response> {\n  const header = options.header ?? 'x-correlation-id';\n  const correlationId = getCurrentCorrelationId();\n\n  // `init.headers` can be a plain object, a `Headers` instance, or an array of\n  // `[name, value]` tuples. Spreading it into a plain object loses everything\n  // but the object form: a `Headers` instance has no own enumerable properties,\n  // and an array spread yields numeric indices. `Headers` accepts all three, is\n  // case-insensitive, and is the shape `fetch` expects back.\n  //\n  // A `Request` carries headers of its own, and `fetch(request, { headers })`\n  // replaces them rather than merging them, so they are seeded first and the\n  // caller's `init.headers` is applied on top. Without this, accepting a\n  // `Request` here would drop its headers, which is the same defect one input\n  // shape over.\n  const headers = new Headers(input instanceof Request ? input.headers : undefined);\n  for (const [name, value] of new Headers(init.headers)) {\n    headers.set(name, value);\n  }\n  if (correlationId && !headers.has(header)) {\n    headers.set(header, correlationId);\n  }\n\n  return globalThis.fetch(input, { ...init, headers });\n}\n\n// ── Axios interceptor factory ─────────────────────────────────────────────────\n\n/**\n * Returns an axios request interceptor that automatically injects the current\n * correlation ID into outgoing axios requests.\n *\n * @example\n * ```ts\n * import axios from 'axios';\n * import { createCorrelationAxiosInterceptor } from 'logixia/correlation';\n *\n * axios.interceptors.request.use(createCorrelationAxiosInterceptor());\n * ```\n */\nexport function createCorrelationAxiosInterceptor(\n  options: { header?: string } = {}\n): (config: Record<string, unknown>) => Record<string, unknown> {\n  const header = options.header ?? 'x-correlation-id';\n\n  return function correlationAxiosInterceptor(\n    config: Record<string, unknown>\n  ): Record<string, unknown> {\n    const correlationId = getCurrentCorrelationId();\n    if (!correlationId) return config;\n\n    const headers = (config['headers'] ?? {}) as Record<string, unknown>;\n    if (!headers[header]) {\n      headers[header] = correlationId;\n    }\n\n    return { ...config, headers };\n  };\n}\n\n// ── Child logger from request ─────────────────────────────────────────────────\n\nconst MAX_USER_AGENT_LENGTH = 512;\nconst MAX_IP_LENGTH = 64;\n\nexport interface ChildFromRequestOptions {\n  /** Header to read the correlation ID from. @default 'x-correlation-id' */\n  correlationHeader?: string;\n  /**\n   * Take the client IP from the first `X-Forwarded-For` entry. Only enable this\n   * when the app sits behind a proxy that overwrites the header; otherwise any\n   * client can choose the logged IP.\n   * @default false\n   */\n  trustProxy?: boolean;\n  /**\n   * Context name passed as the first argument to `logger.child(context, data)`.\n   * When omitted, logixia loggers (detected by their `getContext` /\n   * `getAvailableTransports` methods) get `child('request', fields)` and any other\n   * logger gets `child(fields)`.\n   */\n  childContext?: string;\n}\n\n/**\n * Create a child logger enriched with all correlation-relevant identifiers\n * extracted from the incoming HTTP request.\n *\n * The child logger's every call automatically includes:\n * `correlationId`, `method`, `url`, `userAgent`, `ip`\n *\n * The IP comes from `req.ip` / the socket address unless `trustProxy` is set.\n *\n * @example\n * ```ts\n * import { childFromRequest } from 'logixia/correlation';\n * import { logger } from 'logixia';\n *\n * app.use((req, res, next) => {\n *   req.logger = childFromRequest(req, logger);\n *   next();\n * });\n *\n * app.get('/orders', (req, res) => {\n *   req.logger.info('Listing orders');  // → correlationId, requestId, method, url ...\n * });\n * ```\n */\nexport function childFromRequest<TLogger extends { child(...args: never[]): TLogger }>(\n  req: Record<string, unknown>,\n  logger: TLogger,\n  options: ChildFromRequestOptions = {}\n): TLogger {\n  const correlationHeader = options.correlationHeader ?? 'x-correlation-id';\n\n  const headers = (req['headers'] ?? {}) as Record<string, string | undefined>;\n  // Node lower-cases incoming header names, so look up with a lower-cased key.\n  const correlationId =\n    validIncomingId(headers[correlationHeader.toLowerCase()]) ??\n    getCurrentCorrelationId() ??\n    generateCorrelationId();\n\n  const method = req['method'] as string | undefined;\n  const url = (req['url'] as string | undefined) ?? (req['originalUrl'] as string | undefined);\n  const rawUserAgent = headers['user-agent'];\n  const userAgent =\n    typeof rawUserAgent === 'string' ? rawUserAgent.slice(0, MAX_USER_AGENT_LENGTH) : undefined;\n  const ip = resolveClientIp(req, headers, options.trustProxy === true);\n\n  const fields = {\n    correlationId,\n    ...(method !== undefined ? { method } : {}),\n    ...(url !== undefined ? { url } : {}),\n    ...(userAgent !== undefined ? { userAgent } : {}),\n    ...(ip !== undefined ? { ip } : {}),\n  };\n\n  const child = logger.child as (...args: unknown[]) => TLogger;\n  if (options.childContext !== undefined) {\n    return child.call(logger, options.childContext, fields);\n  }\n  // logixia's ILogger.child(context: string, data?) takes a string namespace;\n  // pino/winston-style loggers take a bindings object.\n  if (usesStringContext(logger)) {\n    return child.call(logger, 'request', fields);\n  }\n  return child.call(logger, fields);\n}\n\n/** ILogger implementations (LogixiaLogger, LogixiaLoggerService, mock logger) expose these methods. */\nfunction usesStringContext(logger: object): boolean {\n  const l = logger as Record<string, unknown>;\n  return typeof l['getContext'] === 'function' || typeof l['getAvailableTransports'] === 'function';\n}\n\nfunction resolveClientIp(\n  req: Record<string, unknown>,\n  headers: Record<string, string | undefined>,\n  trustProxy: boolean\n): string | undefined {\n  if (trustProxy) {\n    const forwarded = headers['x-forwarded-for'];\n    const first = typeof forwarded === 'string' ? forwarded.split(',')[0]?.trim() : undefined;\n    if (first) return first.slice(0, MAX_IP_LENGTH);\n  }\n  const fromReq = req['ip'];\n  if (typeof fromReq === 'string' && fromReq) return fromReq.slice(0, MAX_IP_LENGTH);\n  const remote = (req['socket'] as Record<string, unknown> | undefined)?.['remoteAddress'];\n  return typeof remote === 'string' ? remote.slice(0, MAX_IP_LENGTH) : undefined;\n}\n\n// ── Message queue helpers ─────────────────────────────────────────────────────\n\n/**\n * Extract a correlation context from a Kafka / RabbitMQ / SQS message object.\n *\n * Looks for `correlationId`, `correlation_id`, or `x-correlation-id` in\n * `message.headers` (Kafka) or `message.MessageAttributes` (SQS).\n *\n * @example Kafka consumer\n * ```ts\n * import { extractMessageCorrelationId, withCorrelationId } from 'logixia/correlation';\n *\n * consumer.run({\n *   eachMessage: async ({ message }) => {\n *     const correlationId = extractMessageCorrelationId(message);\n *     await withCorrelationId(correlationId, () => processMessage(message));\n *   },\n * });\n * ```\n */\nexport function extractMessageCorrelationId(message: Record<string, unknown>): string | undefined {\n  // Kafka: message.headers is Record<string, Buffer | string>\n  const kafkaHeaders = message['headers'] as Record<string, Buffer | string> | undefined;\n  if (kafkaHeaders) {\n    const raw =\n      kafkaHeaders['x-correlation-id'] ??\n      kafkaHeaders['correlationId'] ??\n      kafkaHeaders['correlation_id'];\n    if (raw !== undefined) {\n      return validIncomingId(Buffer.isBuffer(raw) ? raw.toString('utf8', 0, 512) : String(raw));\n    }\n  }\n\n  // SQS: message.MessageAttributes\n  const sqsAttrs = message['MessageAttributes'] as\n    Record<string, { StringValue?: string }> | undefined;\n  if (sqsAttrs) {\n    return validIncomingId(\n      sqsAttrs['x-correlation-id']?.StringValue ??\n        sqsAttrs['correlationId']?.StringValue ??\n        sqsAttrs['correlation_id']?.StringValue\n    );\n  }\n\n  // AMQP / generic envelope\n  return validIncomingId(message['correlationId'] ?? message['correlation_id']);\n}\n\n/**\n * Build Kafka message headers containing the current correlation context.\n *\n * @example\n * ```ts\n * import { buildKafkaCorrelationHeaders } from 'logixia/correlation';\n *\n * await producer.send({\n *   topic: 'orders',\n *   messages: [{ value: JSON.stringify(order), headers: buildKafkaCorrelationHeaders() }],\n * });\n * ```\n */\nexport function buildKafkaCorrelationHeaders(): Record<string, string> {\n  const ctx = LogixiaContext.get();\n  const headers: Record<string, string> = {};\n\n  const correlationId = ctx?.correlationId as string | undefined;\n  if (correlationId) headers['x-correlation-id'] = correlationId;\n\n  const traceId = ctx?.traceId as string | undefined;\n  if (traceId) headers['x-trace-id'] = traceId;\n\n  return headers;\n}\n"],"mappings":"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"}
+{"version":3,"file":"correlation.js","names":["randomUUID","sanitizeIncomingId","LogixiaContext"],"sources":["../src/correlation.ts"],"sourcesContent":["/**\n * logixia — Microservices Correlation ID Propagation\n *\n * Provides zero-boilerplate correlation ID generation and propagation for\n * distributed systems. A single correlation ID travels through every service\n * in a request fan-out, making it trivial to join logs across services.\n *\n * Features:\n *  - UUID v4 correlation ID generation (via `crypto.randomUUID()`)\n *  - Express / Fastify / NestJS incoming-request middleware\n *  - `correlationFetch()` — wraps global `fetch`, auto-injects `X-Correlation-ID`\n *  - `createCorrelationAxiosInterceptor()` — axios request interceptor\n *  - `childFromRequest(req, logger)` — child logger with all request identifiers\n *  - Kafka / SQS / RabbitMQ message context helpers\n *  - Integration with `LogixiaContext` (AsyncLocalStorage) so every `logger.info()`\n *    call automatically includes the correlationId without per-call passing.\n *\n * @example Express middleware\n * ```ts\n * import { correlationMiddleware } from 'logixia/correlation';\n * import { logger } from 'logixia';\n *\n * app.use(correlationMiddleware());\n *\n * app.get('/orders', (req, res) => {\n *   // correlationId is automatically in every log inside this request\n *   logger.info('Listing orders');\n *   res.json({ ok: true });\n * });\n * ```\n *\n * @example Outbound fetch with correlation\n * ```ts\n * import { correlationFetch } from 'logixia/correlation';\n *\n * // Reads correlationId from current LogixiaContext and injects it as header\n * const data = await correlationFetch('https://payments.internal/charge', {\n *   method: 'POST',\n *   body: JSON.stringify({ amount: 100 }),\n * });\n * ```\n *\n * @example Manual correlation context\n * ```ts\n * import { withCorrelationId } from 'logixia/correlation';\n *\n * await withCorrelationId('trace-abc-123', async () => {\n *   // All logs and outbound fetch calls in here carry 'trace-abc-123'\n *   await processOrder();\n * });\n * ```\n */\n\nimport { randomUUID } from 'node:crypto';\n\nimport { LogixiaContext } from './context/async-context';\nimport type { HttpRequestShape, HttpResponseShape } from './types/http-shapes';\nimport { sanitizeIncomingId } from './utils/trace.utils';\n\n// ── Types ─────────────────────────────────────────────────────────────────────\n\n/** Fields injected into the log context by the correlation middleware. */\nexport interface CorrelationContext {\n  correlationId: string;\n  traceId?: string;\n  /** Service that originated the request (from `X-Origin-Service` header). */\n  originService?: string;\n  /** Index signature so CorrelationContext is assignable to LogContext. */\n  [key: string]: unknown;\n}\n\nexport interface CorrelationMiddlewareOptions {\n  /**\n   * HTTP header to read/write the correlation ID from/to.\n   * @default 'x-correlation-id'\n   */\n  header?: string;\n  /**\n   * HTTP header for the originating service name.\n   * @default 'x-origin-service'\n   */\n  originServiceHeader?: string;\n  /**\n   * Function to generate a new correlation ID when none is present in the request.\n   * @default () => crypto.randomUUID()\n   */\n  generate?: () => string;\n  /**\n   * When `false`, the incoming correlation header is ignored and a new ID is\n   * always generated. Use this at the edge when client-supplied IDs should not\n   * be trusted.\n   * @default true\n   */\n  trustIncoming?: boolean;\n  /**\n   * When `true`, the response will include the correlation ID header so\n   * clients can log it client-side.\n   * @default true\n   */\n  setResponseHeader?: boolean;\n}\n\n// ── ID generation ─────────────────────────────────────────────────────────────\n\n/**\n * Generate a new correlation ID using `crypto.randomUUID()` (available in\n * Node.js 14.17+, all modern browsers, and Edge runtimes).\n *\n * When the Web Crypto global is unavailable (e.g. Node 18 without\n * `--experimental-global-webcrypto`), fall back to `node:crypto`'s\n * `randomUUID`, which returns a proper UUID v4 — matching the shape this\n * function's JSDoc and README promise. `logixia/correlation` is Node-only\n * (it builds on `AsyncLocalStorage`), so importing `node:crypto` is safe here.\n */\nexport function generateCorrelationId(): string {\n  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {\n    return crypto.randomUUID();\n  }\n  return randomUUID();\n}\n\n/**\n * Return an incoming correlation ID only if it is short and made of safe\n * characters. Anything else (over-long, empty, or containing newlines or other\n * control characters) is dropped so the caller generates a fresh ID instead of\n * writing client-supplied text into every log line.\n */\nfunction validIncomingId(value: unknown): string | undefined {\n  if (typeof value === 'string' && value.trim() !== value) return undefined;\n  return sanitizeIncomingId(value);\n}\n\n// ── Context helpers ───────────────────────────────────────────────────────────\n\n/**\n * Return the correlation ID from the current `LogixiaContext`, or `undefined`\n * when called outside any context scope.\n */\nexport function getCurrentCorrelationId(): string | undefined {\n  const ctx = LogixiaContext.get();\n  return ctx?.correlationId as string | undefined;\n}\n\n/**\n * Run `callback` inside a correlation context scope.\n *\n * If a correlation ID is not provided, a new UUID is generated.\n *\n * @example\n * ```ts\n * await withCorrelationId('cid-abc', async () => {\n *   logger.info('Processing message'); // → { correlationId: 'cid-abc', ... }\n *   await callDownstream();            // correlationFetch() picks up cid-abc\n * });\n * ```\n */\nexport function withCorrelationId<T>(correlationId: string | undefined, callback: () => T): T {\n  const id = correlationId ?? generateCorrelationId();\n  return LogixiaContext.run({ correlationId: id }, callback);\n}\n\n// ── Express / Connect middleware ──────────────────────────────────────────────\n\n/**\n * Express-compatible middleware that:\n * 1. Reads `X-Correlation-ID` from the incoming request (or generates a new one)\n * 2. Wraps the request in a `LogixiaContext` so all loggers in the handler\n *    automatically include `correlationId`\n * 3. Writes the correlation ID back to the response header (opt-out via options)\n *\n * @example\n * ```ts\n * import { correlationMiddleware } from 'logixia/correlation';\n * app.use(correlationMiddleware());\n * ```\n */\nexport function correlationMiddleware(options: CorrelationMiddlewareOptions = {}) {\n  const {\n    header = 'x-correlation-id',\n    originServiceHeader = 'x-origin-service',\n    generate = generateCorrelationId,\n    trustIncoming = true,\n    setResponseHeader = true,\n  } = options;\n\n  return function logixiaCorrelationMiddleware(\n    req: HttpRequestShape,\n    res: HttpResponseShape,\n    next: () => void\n  ): void {\n    const headers = req.headers ?? {};\n\n    // Node lower-cases incoming header names, so look up with lower-cased keys.\n    const incomingId = trustIncoming ? validIncomingId(headers[header.toLowerCase()]) : undefined;\n    const correlationId = incomingId ?? generate();\n    const originService = validIncomingId(headers[originServiceHeader.toLowerCase()]);\n\n    if (setResponseHeader) {\n      res.setHeader?.(header, correlationId);\n    }\n\n    const ctx: CorrelationContext = {\n      correlationId,\n      ...(originService !== undefined ? { originService } : {}),\n    };\n\n    LogixiaContext.run(ctx, next);\n  };\n}\n\n// ── Fastify hook ──────────────────────────────────────────────────────────────\n\n/**\n * Fastify `onRequest` lifecycle hook — same functionality as `correlationMiddleware`\n * but adapted to Fastify's hook API.\n *\n * @example\n * ```ts\n * import { correlationFastifyHook } from 'logixia/correlation';\n * fastify.addHook('onRequest', correlationFastifyHook());\n * ```\n */\nexport function correlationFastifyHook(options: CorrelationMiddlewareOptions = {}) {\n  const {\n    header = 'x-correlation-id',\n    originServiceHeader = 'x-origin-service',\n    generate = generateCorrelationId,\n    trustIncoming = true,\n    setResponseHeader = true,\n  } = options;\n\n  return function logixiaCorrelationFastifyHook(\n    request: HttpRequestShape,\n    reply: HttpResponseShape,\n    done: () => void\n  ): void {\n    const headers = request.headers ?? {};\n\n    // Node lower-cases incoming header names, so look up with lower-cased keys.\n    const incomingId = trustIncoming ? validIncomingId(headers[header.toLowerCase()]) : undefined;\n    const correlationId = incomingId ?? generate();\n    const originService = validIncomingId(headers[originServiceHeader.toLowerCase()]);\n\n    if (setResponseHeader) {\n      reply.header?.(header, correlationId);\n    }\n\n    const ctx: CorrelationContext = {\n      correlationId,\n      ...(originService !== undefined ? { originService } : {}),\n    };\n\n    LogixiaContext.run(ctx, done);\n  };\n}\n\n// ── Outbound fetch wrapper ────────────────────────────────────────────────────\n\n/**\n * A drop-in replacement for `fetch` that automatically injects the current\n * `correlationId` from `LogixiaContext` as an `X-Correlation-ID` request header.\n *\n * Falls back to the global `fetch` when no correlation context is active.\n *\n * @example\n * ```ts\n * import { correlationFetch } from 'logixia/correlation';\n *\n * // Inside a request handler with correlationMiddleware active:\n * const response = await correlationFetch('https://payments.internal/v1/charge', {\n *   method: 'POST',\n *   body: JSON.stringify({ amount: 100 }),\n * });\n * ```\n */\nexport async function correlationFetch(\n  input: string | URL | Request,\n  init: RequestInit = {},\n  options: { header?: string } = {}\n): Promise<Response> {\n  const header = options.header ?? 'x-correlation-id';\n  const correlationId = getCurrentCorrelationId();\n\n  // `init.headers` can be a plain object, a `Headers` instance, or an array of\n  // `[name, value]` tuples. Spreading it into a plain object loses everything\n  // but the object form: a `Headers` instance has no own enumerable properties,\n  // and an array spread yields numeric indices. `Headers` accepts all three, is\n  // case-insensitive, and is the shape `fetch` expects back.\n  //\n  // A `Request` carries headers of its own, and `fetch(request, { headers })`\n  // replaces them rather than merging them, so they are seeded first and the\n  // caller's `init.headers` is applied on top. Without this, accepting a\n  // `Request` here would drop its headers, which is the same defect one input\n  // shape over.\n  const headers = new Headers(input instanceof Request ? input.headers : undefined);\n  for (const [name, value] of new Headers(init.headers)) {\n    headers.set(name, value);\n  }\n  if (correlationId && !headers.has(header)) {\n    headers.set(header, correlationId);\n  }\n\n  return globalThis.fetch(input, { ...init, headers });\n}\n\n// ── Axios interceptor factory ─────────────────────────────────────────────────\n\n/**\n * Returns an axios request interceptor that automatically injects the current\n * correlation ID into outgoing axios requests.\n *\n * @example\n * ```ts\n * import axios from 'axios';\n * import { createCorrelationAxiosInterceptor } from 'logixia/correlation';\n *\n * axios.interceptors.request.use(createCorrelationAxiosInterceptor());\n * ```\n */\nexport function createCorrelationAxiosInterceptor(\n  options: { header?: string } = {}\n): (config: Record<string, unknown>) => Record<string, unknown> {\n  const header = options.header ?? 'x-correlation-id';\n\n  return function correlationAxiosInterceptor(\n    config: Record<string, unknown>\n  ): Record<string, unknown> {\n    const correlationId = getCurrentCorrelationId();\n    if (!correlationId) return config;\n\n    const headers = (config['headers'] ?? {}) as Record<string, unknown>;\n    if (!headers[header]) {\n      headers[header] = correlationId;\n    }\n\n    return { ...config, headers };\n  };\n}\n\n// ── Child logger from request ─────────────────────────────────────────────────\n\nconst MAX_USER_AGENT_LENGTH = 512;\nconst MAX_IP_LENGTH = 64;\n\nexport interface ChildFromRequestOptions {\n  /** Header to read the correlation ID from. @default 'x-correlation-id' */\n  correlationHeader?: string;\n  /**\n   * Take the client IP from the first `X-Forwarded-For` entry. Only enable this\n   * when the app sits behind a proxy that overwrites the header; otherwise any\n   * client can choose the logged IP.\n   * @default false\n   */\n  trustProxy?: boolean;\n  /**\n   * Context name passed as the first argument to `logger.child(context, data)`.\n   * When omitted, logixia loggers (detected by their `getContext` /\n   * `getAvailableTransports` methods) get `child('request', fields)` and any other\n   * logger gets `child(fields)`.\n   */\n  childContext?: string;\n}\n\n/**\n * Create a child logger enriched with all correlation-relevant identifiers\n * extracted from the incoming HTTP request.\n *\n * The child logger's every call automatically includes:\n * `correlationId`, `method`, `url`, `userAgent`, `ip`\n *\n * The IP comes from `req.ip` / the socket address unless `trustProxy` is set.\n *\n * @example\n * ```ts\n * import { childFromRequest } from 'logixia/correlation';\n * import { logger } from 'logixia';\n *\n * app.use((req, res, next) => {\n *   req.logger = childFromRequest(req, logger);\n *   next();\n * });\n *\n * app.get('/orders', (req, res) => {\n *   req.logger.info('Listing orders');  // → correlationId, requestId, method, url ...\n * });\n * ```\n */\nexport function childFromRequest<TLogger extends { child(...args: never[]): TLogger }>(\n  req: HttpRequestShape,\n  logger: TLogger,\n  options: ChildFromRequestOptions = {}\n): TLogger {\n  const correlationHeader = options.correlationHeader ?? 'x-correlation-id';\n\n  const headers = req.headers ?? {};\n  // Node lower-cases incoming header names, so look up with a lower-cased key.\n  const correlationId =\n    validIncomingId(headers[correlationHeader.toLowerCase()]) ??\n    getCurrentCorrelationId() ??\n    generateCorrelationId();\n\n  const method = req.method;\n  const url = req.url ?? req.originalUrl;\n  const rawUserAgent = headers['user-agent'];\n  const userAgent =\n    typeof rawUserAgent === 'string' ? rawUserAgent.slice(0, MAX_USER_AGENT_LENGTH) : undefined;\n  const ip = resolveClientIp(req, headers, options.trustProxy === true);\n\n  const fields = {\n    correlationId,\n    ...(method !== undefined ? { method } : {}),\n    ...(url !== undefined ? { url } : {}),\n    ...(userAgent !== undefined ? { userAgent } : {}),\n    ...(ip !== undefined ? { ip } : {}),\n  };\n\n  const child = logger.child as (...args: unknown[]) => TLogger;\n  if (options.childContext !== undefined) {\n    return child.call(logger, options.childContext, fields);\n  }\n  // logixia's ILogger.child(context: string, data?) takes a string namespace;\n  // pino/winston-style loggers take a bindings object.\n  if (usesStringContext(logger)) {\n    return child.call(logger, 'request', fields);\n  }\n  return child.call(logger, fields);\n}\n\n/** ILogger implementations (LogixiaLogger, LogixiaLoggerService, mock logger) expose these methods. */\nfunction usesStringContext(logger: object): boolean {\n  const l = logger as Record<string, unknown>;\n  return typeof l['getContext'] === 'function' || typeof l['getAvailableTransports'] === 'function';\n}\n\nfunction resolveClientIp(\n  req: HttpRequestShape,\n  headers: Record<string, string | string[] | undefined>,\n  trustProxy: boolean\n): string | undefined {\n  if (trustProxy) {\n    const forwarded = headers['x-forwarded-for'];\n    const first = typeof forwarded === 'string' ? forwarded.split(',')[0]?.trim() : undefined;\n    if (first) return first.slice(0, MAX_IP_LENGTH);\n  }\n  const fromReq = req.ip;\n  if (typeof fromReq === 'string' && fromReq) return fromReq.slice(0, MAX_IP_LENGTH);\n  const remote = req.socket?.remoteAddress;\n  return typeof remote === 'string' ? remote.slice(0, MAX_IP_LENGTH) : undefined;\n}\n\n// ── Message queue helpers ─────────────────────────────────────────────────────\n\n/**\n * Extract a correlation context from a Kafka / RabbitMQ / SQS message object.\n *\n * Looks for `correlationId`, `correlation_id`, or `x-correlation-id` in\n * `message.headers` (Kafka) or `message.MessageAttributes` (SQS).\n *\n * @example Kafka consumer\n * ```ts\n * import { extractMessageCorrelationId, withCorrelationId } from 'logixia/correlation';\n *\n * consumer.run({\n *   eachMessage: async ({ message }) => {\n *     const correlationId = extractMessageCorrelationId(message);\n *     await withCorrelationId(correlationId, () => processMessage(message));\n *   },\n * });\n * ```\n */\nexport function extractMessageCorrelationId(message: Record<string, unknown>): string | undefined {\n  // Kafka: message.headers is Record<string, Buffer | string>\n  const kafkaHeaders = message['headers'] as Record<string, Buffer | string> | undefined;\n  if (kafkaHeaders) {\n    const raw =\n      kafkaHeaders['x-correlation-id'] ??\n      kafkaHeaders['correlationId'] ??\n      kafkaHeaders['correlation_id'];\n    if (raw !== undefined) {\n      return validIncomingId(Buffer.isBuffer(raw) ? raw.toString('utf8', 0, 512) : String(raw));\n    }\n  }\n\n  // SQS: message.MessageAttributes\n  const sqsAttrs = message['MessageAttributes'] as\n    Record<string, { StringValue?: string }> | undefined;\n  if (sqsAttrs) {\n    return validIncomingId(\n      sqsAttrs['x-correlation-id']?.StringValue ??\n        sqsAttrs['correlationId']?.StringValue ??\n        sqsAttrs['correlation_id']?.StringValue\n    );\n  }\n\n  // AMQP / generic envelope\n  return validIncomingId(message['correlationId'] ?? message['correlation_id']);\n}\n\n/**\n * Build Kafka message headers containing the current correlation context.\n *\n * @example\n * ```ts\n * import { buildKafkaCorrelationHeaders } from 'logixia/correlation';\n *\n * await producer.send({\n *   topic: 'orders',\n *   messages: [{ value: JSON.stringify(order), headers: buildKafkaCorrelationHeaders() }],\n * });\n * ```\n */\nexport function buildKafkaCorrelationHeaders(): Record<string, string> {\n  const ctx = LogixiaContext.get();\n  const headers: Record<string, string> = {};\n\n  const correlationId = ctx?.correlationId as string | undefined;\n  if (correlationId) headers['x-correlation-id'] = correlationId;\n\n  const traceId = ctx?.traceId as string | undefined;\n  if (traceId) headers['x-trace-id'] = traceId;\n\n  return headers;\n}\n"],"mappings":"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"}

package/dist/correlation.mjs

@@ -1,5 +1,5 @@
-import { p as sanitizeIncomingId } from "./request-trace-C_fvIDv4.mjs";
-import { t as LogixiaContext } from "./async-context-B05ArHgM.mjs";
+import { p as sanitizeIncomingId } from "./request-trace-BgNykH9M.mjs";
+import { t as LogixiaContext } from "./async-context-2mbUKhcl.mjs";
 import { randomUUID } from "node:crypto";
 // src/correlation.ts
 /**
@@ -119,12 +119,12 @@ function withCorrelationId(correlationId, callback) {
 function correlationMiddleware(options = {}) {
 	const { header = "x-correlation-id", originServiceHeader = "x-origin-service", generate = generateCorrelationId, trustIncoming = true, setResponseHeader = true } = options;
 	return function logixiaCorrelationMiddleware(req, res, next) {
-		const headers = req["headers"] ?? {};
+		const headers = req.headers ?? {};
 		const correlationId = (trustIncoming ? validIncomingId(headers[header.toLowerCase()]) : void 0) ?? generate();
 		const originService = validIncomingId(headers[originServiceHeader.toLowerCase()]);
 		if (setResponseHeader) {
-			const setHeader = res["setHeader"];
-			if (typeof setHeader === "function") setHeader.call(res, header, correlationId);
+			var _res$setHeader;
+			(_res$setHeader = res.setHeader) === null || _res$setHeader === void 0 || _res$setHeader.call(res, header, correlationId);
 		}
 		const ctx = {
 			correlationId,
@@ -146,12 +146,12 @@ function correlationMiddleware(options = {}) {
 function correlationFastifyHook(options = {}) {
 	const { header = "x-correlation-id", originServiceHeader = "x-origin-service", generate = generateCorrelationId, trustIncoming = true, setResponseHeader = true } = options;
 	return function logixiaCorrelationFastifyHook(request, reply, done) {
-		const headers = request["headers"] ?? {};
+		const headers = request.headers ?? {};
 		const correlationId = (trustIncoming ? validIncomingId(headers[header.toLowerCase()]) : void 0) ?? generate();
 		const originService = validIncomingId(headers[originServiceHeader.toLowerCase()]);
 		if (setResponseHeader) {
-			const replyHeader = reply["header"];
-			if (typeof replyHeader === "function") replyHeader.call(reply, header, correlationId);
+			var _reply$header;
+			(_reply$header = reply.header) === null || _reply$header === void 0 || _reply$header.call(reply, header, correlationId);
 		}
 		const ctx = {
 			correlationId,
@@ -241,10 +241,10 @@ const MAX_IP_LENGTH = 64;
 */
 function childFromRequest(req, logger, options = {}) {
 	const correlationHeader = options.correlationHeader ?? "x-correlation-id";
-	const headers = req["headers"] ?? {};
+	const headers = req.headers ?? {};
 	const correlationId = validIncomingId(headers[correlationHeader.toLowerCase()]) ?? getCurrentCorrelationId() ?? generateCorrelationId();
-	const method = req["method"];
-	const url = req["url"] ?? req["originalUrl"];
+	const method = req.method;
+	const url = req.url ?? req.originalUrl;
 	const rawUserAgent = headers["user-agent"];
 	const userAgent = typeof rawUserAgent === "string" ? rawUserAgent.slice(0, MAX_USER_AGENT_LENGTH) : void 0;
 	const ip = resolveClientIp(req, headers, options.trustProxy === true);
@@ -273,9 +273,9 @@ function resolveClientIp(req, headers, trustProxy) {
 		const first = typeof forwarded === "string" ? (_forwarded$split$ = forwarded.split(",")[0]) === null || _forwarded$split$ === void 0 ? void 0 : _forwarded$split$.trim() : void 0;
 		if (first) return first.slice(0, MAX_IP_LENGTH);
 	}
-	const fromReq = req["ip"];
+	const fromReq = req.ip;
 	if (typeof fromReq === "string" && fromReq) return fromReq.slice(0, MAX_IP_LENGTH);
-	const remote = (_req$socket = req["socket"]) === null || _req$socket === void 0 ? void 0 : _req$socket["remoteAddress"];
+	const remote = (_req$socket = req.socket) === null || _req$socket === void 0 ? void 0 : _req$socket.remoteAddress;
 	return typeof remote === "string" ? remote.slice(0, MAX_IP_LENGTH) : void 0;
 }
 /**

package/dist/correlation.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"correlation.mjs","names":[],"sources":["../src/correlation.ts"],"sourcesContent":["/**\n * logixia — Microservices Correlation ID Propagation\n *\n * Provides zero-boilerplate correlation ID generation and propagation for\n * distributed systems. A single correlation ID travels through every service\n * in a request fan-out, making it trivial to join logs across services.\n *\n * Features:\n *  - UUID v4 correlation ID generation (via `crypto.randomUUID()`)\n *  - Express / Fastify / NestJS incoming-request middleware\n *  - `correlationFetch()` — wraps global `fetch`, auto-injects `X-Correlation-ID`\n *  - `createCorrelationAxiosInterceptor()` — axios request interceptor\n *  - `childFromRequest(req, logger)` — child logger with all request identifiers\n *  - Kafka / SQS / RabbitMQ message context helpers\n *  - Integration with `LogixiaContext` (AsyncLocalStorage) so every `logger.info()`\n *    call automatically includes the correlationId without per-call passing.\n *\n * @example Express middleware\n * ```ts\n * import { correlationMiddleware } from 'logixia/correlation';\n * import { logger } from 'logixia';\n *\n * app.use(correlationMiddleware());\n *\n * app.get('/orders', (req, res) => {\n *   // correlationId is automatically in every log inside this request\n *   logger.info('Listing orders');\n *   res.json({ ok: true });\n * });\n * ```\n *\n * @example Outbound fetch with correlation\n * ```ts\n * import { correlationFetch } from 'logixia/correlation';\n *\n * // Reads correlationId from current LogixiaContext and injects it as header\n * const data = await correlationFetch('https://payments.internal/charge', {\n *   method: 'POST',\n *   body: JSON.stringify({ amount: 100 }),\n * });\n * ```\n *\n * @example Manual correlation context\n * ```ts\n * import { withCorrelationId } from 'logixia/correlation';\n *\n * await withCorrelationId('trace-abc-123', async () => {\n *   // All logs and outbound fetch calls in here carry 'trace-abc-123'\n *   await processOrder();\n * });\n * ```\n */\n\nimport { randomUUID } from 'node:crypto';\n\nimport { LogixiaContext } from './context/async-context';\nimport { sanitizeIncomingId } from './utils/trace.utils';\n\n// ── Types ─────────────────────────────────────────────────────────────────────\n\n/** Fields injected into the log context by the correlation middleware. */\nexport interface CorrelationContext {\n  correlationId: string;\n  traceId?: string;\n  /** Service that originated the request (from `X-Origin-Service` header). */\n  originService?: string;\n  /** Index signature so CorrelationContext is assignable to LogContext. */\n  [key: string]: unknown;\n}\n\nexport interface CorrelationMiddlewareOptions {\n  /**\n   * HTTP header to read/write the correlation ID from/to.\n   * @default 'x-correlation-id'\n   */\n  header?: string;\n  /**\n   * HTTP header for the originating service name.\n   * @default 'x-origin-service'\n   */\n  originServiceHeader?: string;\n  /**\n   * Function to generate a new correlation ID when none is present in the request.\n   * @default () => crypto.randomUUID()\n   */\n  generate?: () => string;\n  /**\n   * When `false`, the incoming correlation header is ignored and a new ID is\n   * always generated. Use this at the edge when client-supplied IDs should not\n   * be trusted.\n   * @default true\n   */\n  trustIncoming?: boolean;\n  /**\n   * When `true`, the response will include the correlation ID header so\n   * clients can log it client-side.\n   * @default true\n   */\n  setResponseHeader?: boolean;\n}\n\n// ── ID generation ─────────────────────────────────────────────────────────────\n\n/**\n * Generate a new correlation ID using `crypto.randomUUID()` (available in\n * Node.js 14.17+, all modern browsers, and Edge runtimes).\n *\n * When the Web Crypto global is unavailable (e.g. Node 18 without\n * `--experimental-global-webcrypto`), fall back to `node:crypto`'s\n * `randomUUID`, which returns a proper UUID v4 — matching the shape this\n * function's JSDoc and README promise. `logixia/correlation` is Node-only\n * (it builds on `AsyncLocalStorage`), so importing `node:crypto` is safe here.\n */\nexport function generateCorrelationId(): string {\n  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {\n    return crypto.randomUUID();\n  }\n  return randomUUID();\n}\n\n/**\n * Return an incoming correlation ID only if it is short and made of safe\n * characters. Anything else (over-long, empty, or containing newlines or other\n * control characters) is dropped so the caller generates a fresh ID instead of\n * writing client-supplied text into every log line.\n */\nfunction validIncomingId(value: unknown): string | undefined {\n  if (typeof value === 'string' && value.trim() !== value) return undefined;\n  return sanitizeIncomingId(value);\n}\n\n// ── Context helpers ───────────────────────────────────────────────────────────\n\n/**\n * Return the correlation ID from the current `LogixiaContext`, or `undefined`\n * when called outside any context scope.\n */\nexport function getCurrentCorrelationId(): string | undefined {\n  const ctx = LogixiaContext.get();\n  return ctx?.correlationId as string | undefined;\n}\n\n/**\n * Run `callback` inside a correlation context scope.\n *\n * If a correlation ID is not provided, a new UUID is generated.\n *\n * @example\n * ```ts\n * await withCorrelationId('cid-abc', async () => {\n *   logger.info('Processing message'); // → { correlationId: 'cid-abc', ... }\n *   await callDownstream();            // correlationFetch() picks up cid-abc\n * });\n * ```\n */\nexport function withCorrelationId<T>(correlationId: string | undefined, callback: () => T): T {\n  const id = correlationId ?? generateCorrelationId();\n  return LogixiaContext.run({ correlationId: id }, callback);\n}\n\n// ── Express / Connect middleware ──────────────────────────────────────────────\n\n/**\n * Express-compatible middleware that:\n * 1. Reads `X-Correlation-ID` from the incoming request (or generates a new one)\n * 2. Wraps the request in a `LogixiaContext` so all loggers in the handler\n *    automatically include `correlationId`\n * 3. Writes the correlation ID back to the response header (opt-out via options)\n *\n * @example\n * ```ts\n * import { correlationMiddleware } from 'logixia/correlation';\n * app.use(correlationMiddleware());\n * ```\n */\nexport function correlationMiddleware(options: CorrelationMiddlewareOptions = {}) {\n  const {\n    header = 'x-correlation-id',\n    originServiceHeader = 'x-origin-service',\n    generate = generateCorrelationId,\n    trustIncoming = true,\n    setResponseHeader = true,\n  } = options;\n\n  return function logixiaCorrelationMiddleware(\n    req: Record<string, unknown>,\n    res: Record<string, unknown>,\n    next: () => void\n  ): void {\n    const headers = (req['headers'] ?? {}) as Record<string, string | undefined>;\n\n    // Node lower-cases incoming header names, so look up with lower-cased keys.\n    const incomingId = trustIncoming ? validIncomingId(headers[header.toLowerCase()]) : undefined;\n    const correlationId = incomingId ?? generate();\n    const originService = validIncomingId(headers[originServiceHeader.toLowerCase()]);\n\n    if (setResponseHeader) {\n      const setHeader = res['setHeader'] as ((name: string, value: string) => void) | undefined;\n      if (typeof setHeader === 'function') {\n        setHeader.call(res, header, correlationId);\n      }\n    }\n\n    const ctx: CorrelationContext = {\n      correlationId,\n      ...(originService !== undefined ? { originService } : {}),\n    };\n\n    LogixiaContext.run(ctx, next);\n  };\n}\n\n// ── Fastify hook ──────────────────────────────────────────────────────────────\n\n/**\n * Fastify `onRequest` lifecycle hook — same functionality as `correlationMiddleware`\n * but adapted to Fastify's hook API.\n *\n * @example\n * ```ts\n * import { correlationFastifyHook } from 'logixia/correlation';\n * fastify.addHook('onRequest', correlationFastifyHook());\n * ```\n */\nexport function correlationFastifyHook(options: CorrelationMiddlewareOptions = {}) {\n  const {\n    header = 'x-correlation-id',\n    originServiceHeader = 'x-origin-service',\n    generate = generateCorrelationId,\n    trustIncoming = true,\n    setResponseHeader = true,\n  } = options;\n\n  return function logixiaCorrelationFastifyHook(\n    request: Record<string, unknown>,\n    reply: Record<string, unknown>,\n    done: () => void\n  ): void {\n    const headers = (request['headers'] ?? {}) as Record<string, string | undefined>;\n\n    // Node lower-cases incoming header names, so look up with lower-cased keys.\n    const incomingId = trustIncoming ? validIncomingId(headers[header.toLowerCase()]) : undefined;\n    const correlationId = incomingId ?? generate();\n    const originService = validIncomingId(headers[originServiceHeader.toLowerCase()]);\n\n    if (setResponseHeader) {\n      const replyHeader = reply['header'] as ((name: string, value: string) => void) | undefined;\n      if (typeof replyHeader === 'function') {\n        replyHeader.call(reply, header, correlationId);\n      }\n    }\n\n    const ctx: CorrelationContext = {\n      correlationId,\n      ...(originService !== undefined ? { originService } : {}),\n    };\n\n    LogixiaContext.run(ctx, done);\n  };\n}\n\n// ── Outbound fetch wrapper ────────────────────────────────────────────────────\n\n/**\n * A drop-in replacement for `fetch` that automatically injects the current\n * `correlationId` from `LogixiaContext` as an `X-Correlation-ID` request header.\n *\n * Falls back to the global `fetch` when no correlation context is active.\n *\n * @example\n * ```ts\n * import { correlationFetch } from 'logixia/correlation';\n *\n * // Inside a request handler with correlationMiddleware active:\n * const response = await correlationFetch('https://payments.internal/v1/charge', {\n *   method: 'POST',\n *   body: JSON.stringify({ amount: 100 }),\n * });\n * ```\n */\nexport async function correlationFetch(\n  input: string | URL | Request,\n  init: RequestInit = {},\n  options: { header?: string } = {}\n): Promise<Response> {\n  const header = options.header ?? 'x-correlation-id';\n  const correlationId = getCurrentCorrelationId();\n\n  // `init.headers` can be a plain object, a `Headers` instance, or an array of\n  // `[name, value]` tuples. Spreading it into a plain object loses everything\n  // but the object form: a `Headers` instance has no own enumerable properties,\n  // and an array spread yields numeric indices. `Headers` accepts all three, is\n  // case-insensitive, and is the shape `fetch` expects back.\n  //\n  // A `Request` carries headers of its own, and `fetch(request, { headers })`\n  // replaces them rather than merging them, so they are seeded first and the\n  // caller's `init.headers` is applied on top. Without this, accepting a\n  // `Request` here would drop its headers, which is the same defect one input\n  // shape over.\n  const headers = new Headers(input instanceof Request ? input.headers : undefined);\n  for (const [name, value] of new Headers(init.headers)) {\n    headers.set(name, value);\n  }\n  if (correlationId && !headers.has(header)) {\n    headers.set(header, correlationId);\n  }\n\n  return globalThis.fetch(input, { ...init, headers });\n}\n\n// ── Axios interceptor factory ─────────────────────────────────────────────────\n\n/**\n * Returns an axios request interceptor that automatically injects the current\n * correlation ID into outgoing axios requests.\n *\n * @example\n * ```ts\n * import axios from 'axios';\n * import { createCorrelationAxiosInterceptor } from 'logixia/correlation';\n *\n * axios.interceptors.request.use(createCorrelationAxiosInterceptor());\n * ```\n */\nexport function createCorrelationAxiosInterceptor(\n  options: { header?: string } = {}\n): (config: Record<string, unknown>) => Record<string, unknown> {\n  const header = options.header ?? 'x-correlation-id';\n\n  return function correlationAxiosInterceptor(\n    config: Record<string, unknown>\n  ): Record<string, unknown> {\n    const correlationId = getCurrentCorrelationId();\n    if (!correlationId) return config;\n\n    const headers = (config['headers'] ?? {}) as Record<string, unknown>;\n    if (!headers[header]) {\n      headers[header] = correlationId;\n    }\n\n    return { ...config, headers };\n  };\n}\n\n// ── Child logger from request ─────────────────────────────────────────────────\n\nconst MAX_USER_AGENT_LENGTH = 512;\nconst MAX_IP_LENGTH = 64;\n\nexport interface ChildFromRequestOptions {\n  /** Header to read the correlation ID from. @default 'x-correlation-id' */\n  correlationHeader?: string;\n  /**\n   * Take the client IP from the first `X-Forwarded-For` entry. Only enable this\n   * when the app sits behind a proxy that overwrites the header; otherwise any\n   * client can choose the logged IP.\n   * @default false\n   */\n  trustProxy?: boolean;\n  /**\n   * Context name passed as the first argument to `logger.child(context, data)`.\n   * When omitted, logixia loggers (detected by their `getContext` /\n   * `getAvailableTransports` methods) get `child('request', fields)` and any other\n   * logger gets `child(fields)`.\n   */\n  childContext?: string;\n}\n\n/**\n * Create a child logger enriched with all correlation-relevant identifiers\n * extracted from the incoming HTTP request.\n *\n * The child logger's every call automatically includes:\n * `correlationId`, `method`, `url`, `userAgent`, `ip`\n *\n * The IP comes from `req.ip` / the socket address unless `trustProxy` is set.\n *\n * @example\n * ```ts\n * import { childFromRequest } from 'logixia/correlation';\n * import { logger } from 'logixia';\n *\n * app.use((req, res, next) => {\n *   req.logger = childFromRequest(req, logger);\n *   next();\n * });\n *\n * app.get('/orders', (req, res) => {\n *   req.logger.info('Listing orders');  // → correlationId, requestId, method, url ...\n * });\n * ```\n */\nexport function childFromRequest<TLogger extends { child(...args: never[]): TLogger }>(\n  req: Record<string, unknown>,\n  logger: TLogger,\n  options: ChildFromRequestOptions = {}\n): TLogger {\n  const correlationHeader = options.correlationHeader ?? 'x-correlation-id';\n\n  const headers = (req['headers'] ?? {}) as Record<string, string | undefined>;\n  // Node lower-cases incoming header names, so look up with a lower-cased key.\n  const correlationId =\n    validIncomingId(headers[correlationHeader.toLowerCase()]) ??\n    getCurrentCorrelationId() ??\n    generateCorrelationId();\n\n  const method = req['method'] as string | undefined;\n  const url = (req['url'] as string | undefined) ?? (req['originalUrl'] as string | undefined);\n  const rawUserAgent = headers['user-agent'];\n  const userAgent =\n    typeof rawUserAgent === 'string' ? rawUserAgent.slice(0, MAX_USER_AGENT_LENGTH) : undefined;\n  const ip = resolveClientIp(req, headers, options.trustProxy === true);\n\n  const fields = {\n    correlationId,\n    ...(method !== undefined ? { method } : {}),\n    ...(url !== undefined ? { url } : {}),\n    ...(userAgent !== undefined ? { userAgent } : {}),\n    ...(ip !== undefined ? { ip } : {}),\n  };\n\n  const child = logger.child as (...args: unknown[]) => TLogger;\n  if (options.childContext !== undefined) {\n    return child.call(logger, options.childContext, fields);\n  }\n  // logixia's ILogger.child(context: string, data?) takes a string namespace;\n  // pino/winston-style loggers take a bindings object.\n  if (usesStringContext(logger)) {\n    return child.call(logger, 'request', fields);\n  }\n  return child.call(logger, fields);\n}\n\n/** ILogger implementations (LogixiaLogger, LogixiaLoggerService, mock logger) expose these methods. */\nfunction usesStringContext(logger: object): boolean {\n  const l = logger as Record<string, unknown>;\n  return typeof l['getContext'] === 'function' || typeof l['getAvailableTransports'] === 'function';\n}\n\nfunction resolveClientIp(\n  req: Record<string, unknown>,\n  headers: Record<string, string | undefined>,\n  trustProxy: boolean\n): string | undefined {\n  if (trustProxy) {\n    const forwarded = headers['x-forwarded-for'];\n    const first = typeof forwarded === 'string' ? forwarded.split(',')[0]?.trim() : undefined;\n    if (first) return first.slice(0, MAX_IP_LENGTH);\n  }\n  const fromReq = req['ip'];\n  if (typeof fromReq === 'string' && fromReq) return fromReq.slice(0, MAX_IP_LENGTH);\n  const remote = (req['socket'] as Record<string, unknown> | undefined)?.['remoteAddress'];\n  return typeof remote === 'string' ? remote.slice(0, MAX_IP_LENGTH) : undefined;\n}\n\n// ── Message queue helpers ─────────────────────────────────────────────────────\n\n/**\n * Extract a correlation context from a Kafka / RabbitMQ / SQS message object.\n *\n * Looks for `correlationId`, `correlation_id`, or `x-correlation-id` in\n * `message.headers` (Kafka) or `message.MessageAttributes` (SQS).\n *\n * @example Kafka consumer\n * ```ts\n * import { extractMessageCorrelationId, withCorrelationId } from 'logixia/correlation';\n *\n * consumer.run({\n *   eachMessage: async ({ message }) => {\n *     const correlationId = extractMessageCorrelationId(message);\n *     await withCorrelationId(correlationId, () => processMessage(message));\n *   },\n * });\n * ```\n */\nexport function extractMessageCorrelationId(message: Record<string, unknown>): string | undefined {\n  // Kafka: message.headers is Record<string, Buffer | string>\n  const kafkaHeaders = message['headers'] as Record<string, Buffer | string> | undefined;\n  if (kafkaHeaders) {\n    const raw =\n      kafkaHeaders['x-correlation-id'] ??\n      kafkaHeaders['correlationId'] ??\n      kafkaHeaders['correlation_id'];\n    if (raw !== undefined) {\n      return validIncomingId(Buffer.isBuffer(raw) ? raw.toString('utf8', 0, 512) : String(raw));\n    }\n  }\n\n  // SQS: message.MessageAttributes\n  const sqsAttrs = message['MessageAttributes'] as\n    Record<string, { StringValue?: string }> | undefined;\n  if (sqsAttrs) {\n    return validIncomingId(\n      sqsAttrs['x-correlation-id']?.StringValue ??\n        sqsAttrs['correlationId']?.StringValue ??\n        sqsAttrs['correlation_id']?.StringValue\n    );\n  }\n\n  // AMQP / generic envelope\n  return validIncomingId(message['correlationId'] ?? message['correlation_id']);\n}\n\n/**\n * Build Kafka message headers containing the current correlation context.\n *\n * @example\n * ```ts\n * import { buildKafkaCorrelationHeaders } from 'logixia/correlation';\n *\n * await producer.send({\n *   topic: 'orders',\n *   messages: [{ value: JSON.stringify(order), headers: buildKafkaCorrelationHeaders() }],\n * });\n * ```\n */\nexport function buildKafkaCorrelationHeaders(): Record<string, string> {\n  const ctx = LogixiaContext.get();\n  const headers: Record<string, string> = {};\n\n  const correlationId = ctx?.correlationId as string | undefined;\n  if (correlationId) headers['x-correlation-id'] = correlationId;\n\n  const traceId = ctx?.traceId as string | undefined;\n  if (traceId) headers['x-trace-id'] = traceId;\n\n  return headers;\n}\n"],"mappings":"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"}
+{"version":3,"file":"correlation.mjs","names":[],"sources":["../src/correlation.ts"],"sourcesContent":["/**\n * logixia — Microservices Correlation ID Propagation\n *\n * Provides zero-boilerplate correlation ID generation and propagation for\n * distributed systems. A single correlation ID travels through every service\n * in a request fan-out, making it trivial to join logs across services.\n *\n * Features:\n *  - UUID v4 correlation ID generation (via `crypto.randomUUID()`)\n *  - Express / Fastify / NestJS incoming-request middleware\n *  - `correlationFetch()` — wraps global `fetch`, auto-injects `X-Correlation-ID`\n *  - `createCorrelationAxiosInterceptor()` — axios request interceptor\n *  - `childFromRequest(req, logger)` — child logger with all request identifiers\n *  - Kafka / SQS / RabbitMQ message context helpers\n *  - Integration with `LogixiaContext` (AsyncLocalStorage) so every `logger.info()`\n *    call automatically includes the correlationId without per-call passing.\n *\n * @example Express middleware\n * ```ts\n * import { correlationMiddleware } from 'logixia/correlation';\n * import { logger } from 'logixia';\n *\n * app.use(correlationMiddleware());\n *\n * app.get('/orders', (req, res) => {\n *   // correlationId is automatically in every log inside this request\n *   logger.info('Listing orders');\n *   res.json({ ok: true });\n * });\n * ```\n *\n * @example Outbound fetch with correlation\n * ```ts\n * import { correlationFetch } from 'logixia/correlation';\n *\n * // Reads correlationId from current LogixiaContext and injects it as header\n * const data = await correlationFetch('https://payments.internal/charge', {\n *   method: 'POST',\n *   body: JSON.stringify({ amount: 100 }),\n * });\n * ```\n *\n * @example Manual correlation context\n * ```ts\n * import { withCorrelationId } from 'logixia/correlation';\n *\n * await withCorrelationId('trace-abc-123', async () => {\n *   // All logs and outbound fetch calls in here carry 'trace-abc-123'\n *   await processOrder();\n * });\n * ```\n */\n\nimport { randomUUID } from 'node:crypto';\n\nimport { LogixiaContext } from './context/async-context';\nimport type { HttpRequestShape, HttpResponseShape } from './types/http-shapes';\nimport { sanitizeIncomingId } from './utils/trace.utils';\n\n// ── Types ─────────────────────────────────────────────────────────────────────\n\n/** Fields injected into the log context by the correlation middleware. */\nexport interface CorrelationContext {\n  correlationId: string;\n  traceId?: string;\n  /** Service that originated the request (from `X-Origin-Service` header). */\n  originService?: string;\n  /** Index signature so CorrelationContext is assignable to LogContext. */\n  [key: string]: unknown;\n}\n\nexport interface CorrelationMiddlewareOptions {\n  /**\n   * HTTP header to read/write the correlation ID from/to.\n   * @default 'x-correlation-id'\n   */\n  header?: string;\n  /**\n   * HTTP header for the originating service name.\n   * @default 'x-origin-service'\n   */\n  originServiceHeader?: string;\n  /**\n   * Function to generate a new correlation ID when none is present in the request.\n   * @default () => crypto.randomUUID()\n   */\n  generate?: () => string;\n  /**\n   * When `false`, the incoming correlation header is ignored and a new ID is\n   * always generated. Use this at the edge when client-supplied IDs should not\n   * be trusted.\n   * @default true\n   */\n  trustIncoming?: boolean;\n  /**\n   * When `true`, the response will include the correlation ID header so\n   * clients can log it client-side.\n   * @default true\n   */\n  setResponseHeader?: boolean;\n}\n\n// ── ID generation ─────────────────────────────────────────────────────────────\n\n/**\n * Generate a new correlation ID using `crypto.randomUUID()` (available in\n * Node.js 14.17+, all modern browsers, and Edge runtimes).\n *\n * When the Web Crypto global is unavailable (e.g. Node 18 without\n * `--experimental-global-webcrypto`), fall back to `node:crypto`'s\n * `randomUUID`, which returns a proper UUID v4 — matching the shape this\n * function's JSDoc and README promise. `logixia/correlation` is Node-only\n * (it builds on `AsyncLocalStorage`), so importing `node:crypto` is safe here.\n */\nexport function generateCorrelationId(): string {\n  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {\n    return crypto.randomUUID();\n  }\n  return randomUUID();\n}\n\n/**\n * Return an incoming correlation ID only if it is short and made of safe\n * characters. Anything else (over-long, empty, or containing newlines or other\n * control characters) is dropped so the caller generates a fresh ID instead of\n * writing client-supplied text into every log line.\n */\nfunction validIncomingId(value: unknown): string | undefined {\n  if (typeof value === 'string' && value.trim() !== value) return undefined;\n  return sanitizeIncomingId(value);\n}\n\n// ── Context helpers ───────────────────────────────────────────────────────────\n\n/**\n * Return the correlation ID from the current `LogixiaContext`, or `undefined`\n * when called outside any context scope.\n */\nexport function getCurrentCorrelationId(): string | undefined {\n  const ctx = LogixiaContext.get();\n  return ctx?.correlationId as string | undefined;\n}\n\n/**\n * Run `callback` inside a correlation context scope.\n *\n * If a correlation ID is not provided, a new UUID is generated.\n *\n * @example\n * ```ts\n * await withCorrelationId('cid-abc', async () => {\n *   logger.info('Processing message'); // → { correlationId: 'cid-abc', ... }\n *   await callDownstream();            // correlationFetch() picks up cid-abc\n * });\n * ```\n */\nexport function withCorrelationId<T>(correlationId: string | undefined, callback: () => T): T {\n  const id = correlationId ?? generateCorrelationId();\n  return LogixiaContext.run({ correlationId: id }, callback);\n}\n\n// ── Express / Connect middleware ──────────────────────────────────────────────\n\n/**\n * Express-compatible middleware that:\n * 1. Reads `X-Correlation-ID` from the incoming request (or generates a new one)\n * 2. Wraps the request in a `LogixiaContext` so all loggers in the handler\n *    automatically include `correlationId`\n * 3. Writes the correlation ID back to the response header (opt-out via options)\n *\n * @example\n * ```ts\n * import { correlationMiddleware } from 'logixia/correlation';\n * app.use(correlationMiddleware());\n * ```\n */\nexport function correlationMiddleware(options: CorrelationMiddlewareOptions = {}) {\n  const {\n    header = 'x-correlation-id',\n    originServiceHeader = 'x-origin-service',\n    generate = generateCorrelationId,\n    trustIncoming = true,\n    setResponseHeader = true,\n  } = options;\n\n  return function logixiaCorrelationMiddleware(\n    req: HttpRequestShape,\n    res: HttpResponseShape,\n    next: () => void\n  ): void {\n    const headers = req.headers ?? {};\n\n    // Node lower-cases incoming header names, so look up with lower-cased keys.\n    const incomingId = trustIncoming ? validIncomingId(headers[header.toLowerCase()]) : undefined;\n    const correlationId = incomingId ?? generate();\n    const originService = validIncomingId(headers[originServiceHeader.toLowerCase()]);\n\n    if (setResponseHeader) {\n      res.setHeader?.(header, correlationId);\n    }\n\n    const ctx: CorrelationContext = {\n      correlationId,\n      ...(originService !== undefined ? { originService } : {}),\n    };\n\n    LogixiaContext.run(ctx, next);\n  };\n}\n\n// ── Fastify hook ──────────────────────────────────────────────────────────────\n\n/**\n * Fastify `onRequest` lifecycle hook — same functionality as `correlationMiddleware`\n * but adapted to Fastify's hook API.\n *\n * @example\n * ```ts\n * import { correlationFastifyHook } from 'logixia/correlation';\n * fastify.addHook('onRequest', correlationFastifyHook());\n * ```\n */\nexport function correlationFastifyHook(options: CorrelationMiddlewareOptions = {}) {\n  const {\n    header = 'x-correlation-id',\n    originServiceHeader = 'x-origin-service',\n    generate = generateCorrelationId,\n    trustIncoming = true,\n    setResponseHeader = true,\n  } = options;\n\n  return function logixiaCorrelationFastifyHook(\n    request: HttpRequestShape,\n    reply: HttpResponseShape,\n    done: () => void\n  ): void {\n    const headers = request.headers ?? {};\n\n    // Node lower-cases incoming header names, so look up with lower-cased keys.\n    const incomingId = trustIncoming ? validIncomingId(headers[header.toLowerCase()]) : undefined;\n    const correlationId = incomingId ?? generate();\n    const originService = validIncomingId(headers[originServiceHeader.toLowerCase()]);\n\n    if (setResponseHeader) {\n      reply.header?.(header, correlationId);\n    }\n\n    const ctx: CorrelationContext = {\n      correlationId,\n      ...(originService !== undefined ? { originService } : {}),\n    };\n\n    LogixiaContext.run(ctx, done);\n  };\n}\n\n// ── Outbound fetch wrapper ────────────────────────────────────────────────────\n\n/**\n * A drop-in replacement for `fetch` that automatically injects the current\n * `correlationId` from `LogixiaContext` as an `X-Correlation-ID` request header.\n *\n * Falls back to the global `fetch` when no correlation context is active.\n *\n * @example\n * ```ts\n * import { correlationFetch } from 'logixia/correlation';\n *\n * // Inside a request handler with correlationMiddleware active:\n * const response = await correlationFetch('https://payments.internal/v1/charge', {\n *   method: 'POST',\n *   body: JSON.stringify({ amount: 100 }),\n * });\n * ```\n */\nexport async function correlationFetch(\n  input: string | URL | Request,\n  init: RequestInit = {},\n  options: { header?: string } = {}\n): Promise<Response> {\n  const header = options.header ?? 'x-correlation-id';\n  const correlationId = getCurrentCorrelationId();\n\n  // `init.headers` can be a plain object, a `Headers` instance, or an array of\n  // `[name, value]` tuples. Spreading it into a plain object loses everything\n  // but the object form: a `Headers` instance has no own enumerable properties,\n  // and an array spread yields numeric indices. `Headers` accepts all three, is\n  // case-insensitive, and is the shape `fetch` expects back.\n  //\n  // A `Request` carries headers of its own, and `fetch(request, { headers })`\n  // replaces them rather than merging them, so they are seeded first and the\n  // caller's `init.headers` is applied on top. Without this, accepting a\n  // `Request` here would drop its headers, which is the same defect one input\n  // shape over.\n  const headers = new Headers(input instanceof Request ? input.headers : undefined);\n  for (const [name, value] of new Headers(init.headers)) {\n    headers.set(name, value);\n  }\n  if (correlationId && !headers.has(header)) {\n    headers.set(header, correlationId);\n  }\n\n  return globalThis.fetch(input, { ...init, headers });\n}\n\n// ── Axios interceptor factory ─────────────────────────────────────────────────\n\n/**\n * Returns an axios request interceptor that automatically injects the current\n * correlation ID into outgoing axios requests.\n *\n * @example\n * ```ts\n * import axios from 'axios';\n * import { createCorrelationAxiosInterceptor } from 'logixia/correlation';\n *\n * axios.interceptors.request.use(createCorrelationAxiosInterceptor());\n * ```\n */\nexport function createCorrelationAxiosInterceptor(\n  options: { header?: string } = {}\n): (config: Record<string, unknown>) => Record<string, unknown> {\n  const header = options.header ?? 'x-correlation-id';\n\n  return function correlationAxiosInterceptor(\n    config: Record<string, unknown>\n  ): Record<string, unknown> {\n    const correlationId = getCurrentCorrelationId();\n    if (!correlationId) return config;\n\n    const headers = (config['headers'] ?? {}) as Record<string, unknown>;\n    if (!headers[header]) {\n      headers[header] = correlationId;\n    }\n\n    return { ...config, headers };\n  };\n}\n\n// ── Child logger from request ─────────────────────────────────────────────────\n\nconst MAX_USER_AGENT_LENGTH = 512;\nconst MAX_IP_LENGTH = 64;\n\nexport interface ChildFromRequestOptions {\n  /** Header to read the correlation ID from. @default 'x-correlation-id' */\n  correlationHeader?: string;\n  /**\n   * Take the client IP from the first `X-Forwarded-For` entry. Only enable this\n   * when the app sits behind a proxy that overwrites the header; otherwise any\n   * client can choose the logged IP.\n   * @default false\n   */\n  trustProxy?: boolean;\n  /**\n   * Context name passed as the first argument to `logger.child(context, data)`.\n   * When omitted, logixia loggers (detected by their `getContext` /\n   * `getAvailableTransports` methods) get `child('request', fields)` and any other\n   * logger gets `child(fields)`.\n   */\n  childContext?: string;\n}\n\n/**\n * Create a child logger enriched with all correlation-relevant identifiers\n * extracted from the incoming HTTP request.\n *\n * The child logger's every call automatically includes:\n * `correlationId`, `method`, `url`, `userAgent`, `ip`\n *\n * The IP comes from `req.ip` / the socket address unless `trustProxy` is set.\n *\n * @example\n * ```ts\n * import { childFromRequest } from 'logixia/correlation';\n * import { logger } from 'logixia';\n *\n * app.use((req, res, next) => {\n *   req.logger = childFromRequest(req, logger);\n *   next();\n * });\n *\n * app.get('/orders', (req, res) => {\n *   req.logger.info('Listing orders');  // → correlationId, requestId, method, url ...\n * });\n * ```\n */\nexport function childFromRequest<TLogger extends { child(...args: never[]): TLogger }>(\n  req: HttpRequestShape,\n  logger: TLogger,\n  options: ChildFromRequestOptions = {}\n): TLogger {\n  const correlationHeader = options.correlationHeader ?? 'x-correlation-id';\n\n  const headers = req.headers ?? {};\n  // Node lower-cases incoming header names, so look up with a lower-cased key.\n  const correlationId =\n    validIncomingId(headers[correlationHeader.toLowerCase()]) ??\n    getCurrentCorrelationId() ??\n    generateCorrelationId();\n\n  const method = req.method;\n  const url = req.url ?? req.originalUrl;\n  const rawUserAgent = headers['user-agent'];\n  const userAgent =\n    typeof rawUserAgent === 'string' ? rawUserAgent.slice(0, MAX_USER_AGENT_LENGTH) : undefined;\n  const ip = resolveClientIp(req, headers, options.trustProxy === true);\n\n  const fields = {\n    correlationId,\n    ...(method !== undefined ? { method } : {}),\n    ...(url !== undefined ? { url } : {}),\n    ...(userAgent !== undefined ? { userAgent } : {}),\n    ...(ip !== undefined ? { ip } : {}),\n  };\n\n  const child = logger.child as (...args: unknown[]) => TLogger;\n  if (options.childContext !== undefined) {\n    return child.call(logger, options.childContext, fields);\n  }\n  // logixia's ILogger.child(context: string, data?) takes a string namespace;\n  // pino/winston-style loggers take a bindings object.\n  if (usesStringContext(logger)) {\n    return child.call(logger, 'request', fields);\n  }\n  return child.call(logger, fields);\n}\n\n/** ILogger implementations (LogixiaLogger, LogixiaLoggerService, mock logger) expose these methods. */\nfunction usesStringContext(logger: object): boolean {\n  const l = logger as Record<string, unknown>;\n  return typeof l['getContext'] === 'function' || typeof l['getAvailableTransports'] === 'function';\n}\n\nfunction resolveClientIp(\n  req: HttpRequestShape,\n  headers: Record<string, string | string[] | undefined>,\n  trustProxy: boolean\n): string | undefined {\n  if (trustProxy) {\n    const forwarded = headers['x-forwarded-for'];\n    const first = typeof forwarded === 'string' ? forwarded.split(',')[0]?.trim() : undefined;\n    if (first) return first.slice(0, MAX_IP_LENGTH);\n  }\n  const fromReq = req.ip;\n  if (typeof fromReq === 'string' && fromReq) return fromReq.slice(0, MAX_IP_LENGTH);\n  const remote = req.socket?.remoteAddress;\n  return typeof remote === 'string' ? remote.slice(0, MAX_IP_LENGTH) : undefined;\n}\n\n// ── Message queue helpers ─────────────────────────────────────────────────────\n\n/**\n * Extract a correlation context from a Kafka / RabbitMQ / SQS message object.\n *\n * Looks for `correlationId`, `correlation_id`, or `x-correlation-id` in\n * `message.headers` (Kafka) or `message.MessageAttributes` (SQS).\n *\n * @example Kafka consumer\n * ```ts\n * import { extractMessageCorrelationId, withCorrelationId } from 'logixia/correlation';\n *\n * consumer.run({\n *   eachMessage: async ({ message }) => {\n *     const correlationId = extractMessageCorrelationId(message);\n *     await withCorrelationId(correlationId, () => processMessage(message));\n *   },\n * });\n * ```\n */\nexport function extractMessageCorrelationId(message: Record<string, unknown>): string | undefined {\n  // Kafka: message.headers is Record<string, Buffer | string>\n  const kafkaHeaders = message['headers'] as Record<string, Buffer | string> | undefined;\n  if (kafkaHeaders) {\n    const raw =\n      kafkaHeaders['x-correlation-id'] ??\n      kafkaHeaders['correlationId'] ??\n      kafkaHeaders['correlation_id'];\n    if (raw !== undefined) {\n      return validIncomingId(Buffer.isBuffer(raw) ? raw.toString('utf8', 0, 512) : String(raw));\n    }\n  }\n\n  // SQS: message.MessageAttributes\n  const sqsAttrs = message['MessageAttributes'] as\n    Record<string, { StringValue?: string }> | undefined;\n  if (sqsAttrs) {\n    return validIncomingId(\n      sqsAttrs['x-correlation-id']?.StringValue ??\n        sqsAttrs['correlationId']?.StringValue ??\n        sqsAttrs['correlation_id']?.StringValue\n    );\n  }\n\n  // AMQP / generic envelope\n  return validIncomingId(message['correlationId'] ?? message['correlation_id']);\n}\n\n/**\n * Build Kafka message headers containing the current correlation context.\n *\n * @example\n * ```ts\n * import { buildKafkaCorrelationHeaders } from 'logixia/correlation';\n *\n * await producer.send({\n *   topic: 'orders',\n *   messages: [{ value: JSON.stringify(order), headers: buildKafkaCorrelationHeaders() }],\n * });\n * ```\n */\nexport function buildKafkaCorrelationHeaders(): Record<string, string> {\n  const ctx = LogixiaContext.get();\n  const headers: Record<string, string> = {};\n\n  const correlationId = ctx?.correlationId as string | undefined;\n  if (correlationId) headers['x-correlation-id'] = correlationId;\n\n  const traceId = ctx?.traceId as string | undefined;\n  if (traceId) headers['x-trace-id'] = traceId;\n\n  return headers;\n}\n"],"mappings":"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"}

package/dist/{entry-fields-RLd1jCoR.js → entry-fields-BSLkzw18.js}

@@ -1,6 +1,6 @@
+const require_own_property = require("./own-property-BWkibepN.js");
 // src/transports/entry-fields.ts
 const PAYLOAD_PREFIX = "data_";
-const UNSAFE_KEYS = /* @__PURE__ */ new Set(["__proto__"]);
 /**
 * Copies `core` and then the user payload into one object. The core fields stay
 * authoritative: a payload key that matches a core key (even one whose value is
@@ -8,6 +8,10 @@ const UNSAFE_KEYS = /* @__PURE__ */ new Set(["__proto__"]);
 * prefix is repeated until the name is free of core keys and of every other
 * payload key, so the result does not depend on key order and a payload's own
 * `data_level` stays where it is.
+*
+* Exception: a payload `traceId` equal to the core `traceId` is a duplicate (the
+* context middleware copies the trace id into the payload) and is dropped rather
+* than emitted again as `data_traceId`. A different value is still kept.
 */
 function mergeCoreFields(core, data, extraReserved = []) {
 	const merged = { ...core };
@@ -15,7 +19,8 @@ function mergeCoreFields(core, data, extraReserved = []) {
 	const reserved = /* @__PURE__ */ new Set([...Object.keys(core), ...extraReserved]);
 	const payloadKeys = new Set(Object.keys(data));
 	for (const key of payloadKeys) {
-		if (UNSAFE_KEYS.has(key)) continue;
+		if (require_own_property.isProtoKey(key)) continue;
+		if (key === "traceId" && core["traceId"] !== void 0 && data[key] === core["traceId"]) continue;
 		let target = key;
 		if (reserved.has(target)) do
 			target = `${PAYLOAD_PREFIX}${target}`;
@@ -31,4 +36,4 @@ Object.defineProperty(exports, "mergeCoreFields", {
 	}
 });
 
-//# sourceMappingURL=entry-fields-RLd1jCoR.js.map
+//# sourceMappingURL=entry-fields-BSLkzw18.js.map

package/dist/entry-fields-BSLkzw18.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry-fields-BSLkzw18.js","names":["isProtoKey"],"sources":["../src/transports/entry-fields.ts"],"sourcesContent":["import { isProtoKey } from '../utils/own-property';\n\nconst PAYLOAD_PREFIX = 'data_';\n\n/**\n * Copies `core` and then the user payload into one object. The core fields stay\n * authoritative: a payload key that matches a core key (even one whose value is\n * undefined) or a reserved name is kept under a `data_` prefix instead. The\n * prefix is repeated until the name is free of core keys and of every other\n * payload key, so the result does not depend on key order and a payload's own\n * `data_level` stays where it is.\n *\n * Exception: a payload `traceId` equal to the core `traceId` is a duplicate (the\n * context middleware copies the trace id into the payload) and is dropped rather\n * than emitted again as `data_traceId`. A different value is still kept.\n */\nexport function mergeCoreFields(\n  core: Record<string, unknown>,\n  data: Record<string, unknown> | undefined,\n  extraReserved: readonly string[] = []\n): Record<string, unknown> {\n  const merged: Record<string, unknown> = { ...core };\n  if (!data) return merged;\n  const reserved = new Set([...Object.keys(core), ...extraReserved]);\n  const payloadKeys = new Set(Object.keys(data));\n  for (const key of payloadKeys) {\n    if (isProtoKey(key)) continue;\n    if (key === 'traceId' && core['traceId'] !== undefined && data[key] === core['traceId'])\n      continue;\n    let target = key;\n    if (reserved.has(target)) {\n      do {\n        target = `${PAYLOAD_PREFIX}${target}`;\n      } while (reserved.has(target) || payloadKeys.has(target));\n    }\n    merged[target] = data[key];\n  }\n  return merged;\n}\n"],"mappings":";;AAEA,MAAM,iBAAiB;;;;;;;;;;;;;AAcvB,SAAgB,gBACd,MACA,MACA,gBAAmC,CAAC,GACX;CACzB,MAAM,SAAkC,EAAE,GAAG,KAAK;CAClD,IAAI,CAAC,MAAM,OAAO;CAClB,MAAM,2BAAW,IAAI,IAAI,CAAC,GAAG,OAAO,KAAK,IAAI,GAAG,GAAG,aAAa,CAAC;CACjE,MAAM,cAAc,IAAI,IAAI,OAAO,KAAK,IAAI,CAAC;CAC7C,KAAK,MAAM,OAAO,aAAa;EAC7B,IAAIA,qBAAAA,WAAW,GAAG,GAAG;EACrB,IAAI,QAAQ,aAAa,KAAK,eAAe,KAAA,KAAa,KAAK,SAAS,KAAK,YAC3E;EACF,IAAI,SAAS;EACb,IAAI,SAAS,IAAI,MAAM,GACrB;GACE,SAAS,GAAG,iBAAiB;SACtB,SAAS,IAAI,MAAM,KAAK,YAAY,IAAI,MAAM;EAEzD,OAAO,UAAU,KAAK;CACxB;CACA,OAAO;AACT"}