logixia 1.12.4 → 1.12.6

package/dist/correlation.js

@@ -0,0 +1,272 @@
+const require_chunk = require('./chunk-nOFOJqeH.js');
+const require_async_context = require('./async-context-CSHWoHMB.js');
+let node_crypto = require("node:crypto");
+node_crypto = require_chunk.__toESM(node_crypto);
+
+//#region src/correlation.ts
+/**
+* Generate a new correlation ID using `crypto.randomUUID()` (available in
+* Node.js 14.17+, all modern browsers, and Edge runtimes).
+*
+* When the Web Crypto global is unavailable (e.g. Node 18 without
+* `--experimental-global-webcrypto`), fall back to `node:crypto`'s
+* `randomUUID`, which returns a proper UUID v4 — matching the shape this
+* function's JSDoc and README promise. `logixia/correlation` is Node-only
+* (it builds on `AsyncLocalStorage`), so importing `node:crypto` is safe here.
+*/
+function generateCorrelationId() {
+	if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") return crypto.randomUUID();
+	return (0, node_crypto.randomUUID)();
+}
+const MAX_INCOMING_ID_LENGTH = 128;
+const VALID_INCOMING_ID = /^[A-Za-z0-9._:-]+$/;
+/**
+* Return an incoming correlation ID only if it is short and made of safe
+* characters. Anything else (over-long, empty, or containing newlines or other
+* control characters) is dropped so the caller generates a fresh ID instead of
+* writing client-supplied text into every log line.
+*/
+function validIncomingId(value) {
+	if (value === void 0 || value.length > MAX_INCOMING_ID_LENGTH) return void 0;
+	return VALID_INCOMING_ID.test(value) ? value : void 0;
+}
+/**
+* Return the correlation ID from the current `LogixiaContext`, or `undefined`
+* when called outside any context scope.
+*/
+function getCurrentCorrelationId() {
+	const ctx = require_async_context.LogixiaContext.get();
+	return ctx === null || ctx === void 0 ? void 0 : ctx.correlationId;
+}
+/**
+* Run `callback` inside a correlation context scope.
+*
+* If a correlation ID is not provided, a new UUID is generated.
+*
+* @example
+* ```ts
+* await withCorrelationId('cid-abc', async () => {
+*   logger.info('Processing message'); // → { correlationId: 'cid-abc', ... }
+*   await callDownstream();            // correlationFetch() picks up cid-abc
+* });
+* ```
+*/
+function withCorrelationId(correlationId, callback) {
+	const id = correlationId ?? generateCorrelationId();
+	return require_async_context.LogixiaContext.run({ correlationId: id }, callback);
+}
+/**
+* Express-compatible middleware that:
+* 1. Reads `X-Correlation-ID` from the incoming request (or generates a new one)
+* 2. Wraps the request in a `LogixiaContext` so all loggers in the handler
+*    automatically include `correlationId`
+* 3. Writes the correlation ID back to the response header (opt-out via options)
+*
+* @example
+* ```ts
+* import { correlationMiddleware } from 'logixia/correlation';
+* app.use(correlationMiddleware());
+* ```
+*/
+function correlationMiddleware(options = {}) {
+	const { header = "x-correlation-id", originServiceHeader = "x-origin-service", generate = generateCorrelationId, setResponseHeader = true } = options;
+	return function logixiaCorrelationMiddleware(req, res, next) {
+		const headers = req["headers"] ?? {};
+		const correlationId = validIncomingId(headers[header.toLowerCase()]) ?? generate();
+		const originService = headers[originServiceHeader.toLowerCase()];
+		if (setResponseHeader) {
+			const setHeader = res["setHeader"];
+			if (typeof setHeader === "function") setHeader.call(res, header, correlationId);
+		}
+		const ctx = {
+			correlationId,
+			...originService !== void 0 ? { originService } : {}
+		};
+		require_async_context.LogixiaContext.run(ctx, next);
+	};
+}
+/**
+* Fastify `onRequest` lifecycle hook — same functionality as `correlationMiddleware`
+* but adapted to Fastify's hook API.
+*
+* @example
+* ```ts
+* import { correlationFastifyHook } from 'logixia/correlation';
+* fastify.addHook('onRequest', correlationFastifyHook());
+* ```
+*/
+function correlationFastifyHook(options = {}) {
+	const { header = "x-correlation-id", originServiceHeader = "x-origin-service", generate = generateCorrelationId, setResponseHeader = true } = options;
+	return function logixiaCorrelationFastifyHook(request, reply, done) {
+		const headers = request["headers"] ?? {};
+		const correlationId = validIncomingId(headers[header.toLowerCase()]) ?? generate();
+		const originService = headers[originServiceHeader.toLowerCase()];
+		if (setResponseHeader) {
+			const replyHeader = reply["header"];
+			if (typeof replyHeader === "function") replyHeader.call(reply, header, correlationId);
+		}
+		const ctx = {
+			correlationId,
+			...originService !== void 0 ? { originService } : {}
+		};
+		require_async_context.LogixiaContext.run(ctx, done);
+	};
+}
+/**
+* A drop-in replacement for `fetch` that automatically injects the current
+* `correlationId` from `LogixiaContext` as an `X-Correlation-ID` request header.
+*
+* Falls back to the global `fetch` when no correlation context is active.
+*
+* @example
+* ```ts
+* import { correlationFetch } from 'logixia/correlation';
+*
+* // Inside a request handler with correlationMiddleware active:
+* const response = await correlationFetch('https://payments.internal/v1/charge', {
+*   method: 'POST',
+*   body: JSON.stringify({ amount: 100 }),
+* });
+* ```
+*/
+async function correlationFetch(input, init = {}, options = {}) {
+	const header = options.header ?? "x-correlation-id";
+	const correlationId = getCurrentCorrelationId();
+	const headers = new Headers(input instanceof Request ? input.headers : void 0);
+	for (const [name, value] of new Headers(init.headers)) headers.set(name, value);
+	if (correlationId && !headers.has(header)) headers.set(header, correlationId);
+	return globalThis.fetch(input, {
+		...init,
+		headers
+	});
+}
+/**
+* Returns an axios request interceptor that automatically injects the current
+* correlation ID into outgoing axios requests.
+*
+* @example
+* ```ts
+* import axios from 'axios';
+* import { createCorrelationAxiosInterceptor } from 'logixia/correlation';
+*
+* axios.interceptors.request.use(createCorrelationAxiosInterceptor());
+* ```
+*/
+function createCorrelationAxiosInterceptor(options = {}) {
+	const header = options.header ?? "x-correlation-id";
+	return function correlationAxiosInterceptor(config) {
+		const correlationId = getCurrentCorrelationId();
+		if (!correlationId) return config;
+		const headers = config["headers"] ?? {};
+		if (!headers[header]) headers[header] = correlationId;
+		return {
+			...config,
+			headers
+		};
+	};
+}
+/**
+* Create a child logger enriched with all correlation-relevant identifiers
+* extracted from the incoming HTTP request.
+*
+* The child logger's every call automatically includes:
+* `correlationId`, `requestId`, `method`, `url`, `userAgent`, `ip`
+*
+* @example
+* ```ts
+* import { childFromRequest } from 'logixia/correlation';
+* import { logger } from 'logixia';
+*
+* app.use((req, res, next) => {
+*   req.logger = childFromRequest(req, logger);
+*   next();
+* });
+*
+* app.get('/orders', (req, res) => {
+*   req.logger.info('Listing orders');  // → correlationId, requestId, method, url ...
+* });
+* ```
+*/
+function childFromRequest(req, logger, options = {}) {
+	var _headers$xForwarded, _req$socket;
+	const correlationHeader = options.correlationHeader ?? "x-correlation-id";
+	const headers = req["headers"] ?? {};
+	const correlationId = validIncomingId(headers[correlationHeader.toLowerCase()]) ?? getCurrentCorrelationId() ?? generateCorrelationId();
+	const method = req["method"];
+	const url = req["url"] ?? req["originalUrl"];
+	const userAgent = headers["user-agent"];
+	const ip = ((_headers$xForwarded = headers["x-forwarded-for"]) === null || _headers$xForwarded === void 0 || (_headers$xForwarded = _headers$xForwarded.split(",")[0]) === null || _headers$xForwarded === void 0 ? void 0 : _headers$xForwarded.trim()) ?? ((_req$socket = req["socket"]) === null || _req$socket === void 0 ? void 0 : _req$socket["remoteAddress"]);
+	return logger.child({
+		correlationId,
+		...method !== void 0 ? { method } : {},
+		...url !== void 0 ? { url } : {},
+		...userAgent !== void 0 ? { userAgent } : {},
+		...ip !== void 0 ? { ip } : {}
+	});
+}
+/**
+* Extract a correlation context from a Kafka / RabbitMQ / SQS message object.
+*
+* Looks for `correlationId`, `correlation_id`, or `x-correlation-id` in
+* `message.headers` (Kafka) or `message.MessageAttributes` (SQS).
+*
+* @example Kafka consumer
+* ```ts
+* import { extractMessageCorrelationId, withCorrelationId } from 'logixia/correlation';
+*
+* consumer.run({
+*   eachMessage: async ({ message }) => {
+*     const correlationId = extractMessageCorrelationId(message);
+*     await withCorrelationId(correlationId, () => processMessage(message));
+*   },
+* });
+* ```
+*/
+function extractMessageCorrelationId(message) {
+	const kafkaHeaders = message["headers"];
+	if (kafkaHeaders) {
+		const raw = kafkaHeaders["x-correlation-id"] ?? kafkaHeaders["correlationId"] ?? kafkaHeaders["correlation_id"];
+		if (raw !== void 0) return Buffer.isBuffer(raw) ? raw.toString("utf8") : String(raw);
+	}
+	const sqsAttrs = message["MessageAttributes"];
+	if (sqsAttrs) {
+		var _sqsAttrs$xCorrelati, _sqsAttrs$correlation, _sqsAttrs$correlation2;
+		return ((_sqsAttrs$xCorrelati = sqsAttrs["x-correlation-id"]) === null || _sqsAttrs$xCorrelati === void 0 ? void 0 : _sqsAttrs$xCorrelati.StringValue) ?? ((_sqsAttrs$correlation = sqsAttrs["correlationId"]) === null || _sqsAttrs$correlation === void 0 ? void 0 : _sqsAttrs$correlation.StringValue) ?? ((_sqsAttrs$correlation2 = sqsAttrs["correlation_id"]) === null || _sqsAttrs$correlation2 === void 0 ? void 0 : _sqsAttrs$correlation2.StringValue);
+	}
+	return message["correlationId"] ?? message["correlation_id"];
+}
+/**
+* Build Kafka message headers containing the current correlation context.
+*
+* @example
+* ```ts
+* import { buildKafkaCorrelationHeaders } from 'logixia/correlation';
+*
+* await producer.send({
+*   topic: 'orders',
+*   messages: [{ value: JSON.stringify(order), headers: buildKafkaCorrelationHeaders() }],
+* });
+* ```
+*/
+function buildKafkaCorrelationHeaders() {
+	const ctx = require_async_context.LogixiaContext.get();
+	const headers = {};
+	const correlationId = ctx === null || ctx === void 0 ? void 0 : ctx.correlationId;
+	if (correlationId) headers["x-correlation-id"] = correlationId;
+	const traceId = ctx === null || ctx === void 0 ? void 0 : ctx.traceId;
+	if (traceId) headers["x-trace-id"] = traceId;
+	return headers;
+}
+
+//#endregion
+exports.buildKafkaCorrelationHeaders = buildKafkaCorrelationHeaders;
+exports.childFromRequest = childFromRequest;
+exports.correlationFastifyHook = correlationFastifyHook;
+exports.correlationFetch = correlationFetch;
+exports.correlationMiddleware = correlationMiddleware;
+exports.createCorrelationAxiosInterceptor = createCorrelationAxiosInterceptor;
+exports.extractMessageCorrelationId = extractMessageCorrelationId;
+exports.generateCorrelationId = generateCorrelationId;
+exports.getCurrentCorrelationId = getCurrentCorrelationId;
+exports.withCorrelationId = withCorrelationId;
+//# sourceMappingURL=correlation.js.map

package/dist/correlation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlation.js","names":["LogixiaContext","ctx: CorrelationContext","headers: Record<string, string>"],"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';\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 `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\nconst MAX_INCOMING_ID_LENGTH = 128;\nconst VALID_INCOMING_ID = /^[A-Za-z0-9._:-]+$/;\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: string | undefined): string | undefined {\n  if (value === undefined || value.length > MAX_INCOMING_ID_LENGTH) return undefined;\n  return VALID_INCOMING_ID.test(value) ? value : undefined;\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    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 correlationId = validIncomingId(headers[header.toLowerCase()]) ?? generate();\n    const originService = 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    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 correlationId = validIncomingId(headers[header.toLowerCase()]) ?? generate();\n    const originService = 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\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`, `requestId`, `method`, `url`, `userAgent`, `ip`\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(ctx: Record<string, unknown>): TLogger }>(\n  req: Record<string, unknown>,\n  logger: TLogger,\n  options: { correlationHeader?: string } = {}\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 userAgent = headers['user-agent'];\n  const ip =\n    (headers['x-forwarded-for'] as string | undefined)?.split(',')[0]?.trim() ??\n    ((req['socket'] as Record<string, unknown> | undefined)?.['remoteAddress'] as\n      string | undefined);\n\n  return logger.child({\n    correlationId,\n    ...(method !== undefined ? { method } : {}),\n    ...(url !== undefined ? { url } : {}),\n    ...(userAgent !== undefined ? { userAgent } : {}),\n    ...(ip !== undefined ? { ip } : {}),\n  });\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 Buffer.isBuffer(raw) ? raw.toString('utf8') : 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 (\n      sqsAttrs['x-correlation-id']?.StringValue ??\n      sqsAttrs['correlationId']?.StringValue ??\n      sqsAttrs['correlation_id']?.StringValue\n    );\n  }\n\n  // AMQP / generic envelope\n  return (\n    (message['correlationId'] as string | undefined) ??\n    (message['correlation_id'] as string | undefined)\n  );\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

@@ -0,0 +1,261 @@
+import { t as LogixiaContext } from "./async-context-CwBNMm2E.mjs";
+import { randomUUID } from "node:crypto";
+
+//#region src/correlation.ts
+/**
+* Generate a new correlation ID using `crypto.randomUUID()` (available in
+* Node.js 14.17+, all modern browsers, and Edge runtimes).
+*
+* When the Web Crypto global is unavailable (e.g. Node 18 without
+* `--experimental-global-webcrypto`), fall back to `node:crypto`'s
+* `randomUUID`, which returns a proper UUID v4 — matching the shape this
+* function's JSDoc and README promise. `logixia/correlation` is Node-only
+* (it builds on `AsyncLocalStorage`), so importing `node:crypto` is safe here.
+*/
+function generateCorrelationId() {
+	if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") return crypto.randomUUID();
+	return randomUUID();
+}
+const MAX_INCOMING_ID_LENGTH = 128;
+const VALID_INCOMING_ID = /^[A-Za-z0-9._:-]+$/;
+/**
+* Return an incoming correlation ID only if it is short and made of safe
+* characters. Anything else (over-long, empty, or containing newlines or other
+* control characters) is dropped so the caller generates a fresh ID instead of
+* writing client-supplied text into every log line.
+*/
+function validIncomingId(value) {
+	if (value === void 0 || value.length > MAX_INCOMING_ID_LENGTH) return void 0;
+	return VALID_INCOMING_ID.test(value) ? value : void 0;
+}
+/**
+* Return the correlation ID from the current `LogixiaContext`, or `undefined`
+* when called outside any context scope.
+*/
+function getCurrentCorrelationId() {
+	const ctx = LogixiaContext.get();
+	return ctx === null || ctx === void 0 ? void 0 : ctx.correlationId;
+}
+/**
+* Run `callback` inside a correlation context scope.
+*
+* If a correlation ID is not provided, a new UUID is generated.
+*
+* @example
+* ```ts
+* await withCorrelationId('cid-abc', async () => {
+*   logger.info('Processing message'); // → { correlationId: 'cid-abc', ... }
+*   await callDownstream();            // correlationFetch() picks up cid-abc
+* });
+* ```
+*/
+function withCorrelationId(correlationId, callback) {
+	const id = correlationId ?? generateCorrelationId();
+	return LogixiaContext.run({ correlationId: id }, callback);
+}
+/**
+* Express-compatible middleware that:
+* 1. Reads `X-Correlation-ID` from the incoming request (or generates a new one)
+* 2. Wraps the request in a `LogixiaContext` so all loggers in the handler
+*    automatically include `correlationId`
+* 3. Writes the correlation ID back to the response header (opt-out via options)
+*
+* @example
+* ```ts
+* import { correlationMiddleware } from 'logixia/correlation';
+* app.use(correlationMiddleware());
+* ```
+*/
+function correlationMiddleware(options = {}) {
+	const { header = "x-correlation-id", originServiceHeader = "x-origin-service", generate = generateCorrelationId, setResponseHeader = true } = options;
+	return function logixiaCorrelationMiddleware(req, res, next) {
+		const headers = req["headers"] ?? {};
+		const correlationId = validIncomingId(headers[header.toLowerCase()]) ?? generate();
+		const originService = headers[originServiceHeader.toLowerCase()];
+		if (setResponseHeader) {
+			const setHeader = res["setHeader"];
+			if (typeof setHeader === "function") setHeader.call(res, header, correlationId);
+		}
+		const ctx = {
+			correlationId,
+			...originService !== void 0 ? { originService } : {}
+		};
+		LogixiaContext.run(ctx, next);
+	};
+}
+/**
+* Fastify `onRequest` lifecycle hook — same functionality as `correlationMiddleware`
+* but adapted to Fastify's hook API.
+*
+* @example
+* ```ts
+* import { correlationFastifyHook } from 'logixia/correlation';
+* fastify.addHook('onRequest', correlationFastifyHook());
+* ```
+*/
+function correlationFastifyHook(options = {}) {
+	const { header = "x-correlation-id", originServiceHeader = "x-origin-service", generate = generateCorrelationId, setResponseHeader = true } = options;
+	return function logixiaCorrelationFastifyHook(request, reply, done) {
+		const headers = request["headers"] ?? {};
+		const correlationId = validIncomingId(headers[header.toLowerCase()]) ?? generate();
+		const originService = headers[originServiceHeader.toLowerCase()];
+		if (setResponseHeader) {
+			const replyHeader = reply["header"];
+			if (typeof replyHeader === "function") replyHeader.call(reply, header, correlationId);
+		}
+		const ctx = {
+			correlationId,
+			...originService !== void 0 ? { originService } : {}
+		};
+		LogixiaContext.run(ctx, done);
+	};
+}
+/**
+* A drop-in replacement for `fetch` that automatically injects the current
+* `correlationId` from `LogixiaContext` as an `X-Correlation-ID` request header.
+*
+* Falls back to the global `fetch` when no correlation context is active.
+*
+* @example
+* ```ts
+* import { correlationFetch } from 'logixia/correlation';
+*
+* // Inside a request handler with correlationMiddleware active:
+* const response = await correlationFetch('https://payments.internal/v1/charge', {
+*   method: 'POST',
+*   body: JSON.stringify({ amount: 100 }),
+* });
+* ```
+*/
+async function correlationFetch(input, init = {}, options = {}) {
+	const header = options.header ?? "x-correlation-id";
+	const correlationId = getCurrentCorrelationId();
+	const headers = new Headers(input instanceof Request ? input.headers : void 0);
+	for (const [name, value] of new Headers(init.headers)) headers.set(name, value);
+	if (correlationId && !headers.has(header)) headers.set(header, correlationId);
+	return globalThis.fetch(input, {
+		...init,
+		headers
+	});
+}
+/**
+* Returns an axios request interceptor that automatically injects the current
+* correlation ID into outgoing axios requests.
+*
+* @example
+* ```ts
+* import axios from 'axios';
+* import { createCorrelationAxiosInterceptor } from 'logixia/correlation';
+*
+* axios.interceptors.request.use(createCorrelationAxiosInterceptor());
+* ```
+*/
+function createCorrelationAxiosInterceptor(options = {}) {
+	const header = options.header ?? "x-correlation-id";
+	return function correlationAxiosInterceptor(config) {
+		const correlationId = getCurrentCorrelationId();
+		if (!correlationId) return config;
+		const headers = config["headers"] ?? {};
+		if (!headers[header]) headers[header] = correlationId;
+		return {
+			...config,
+			headers
+		};
+	};
+}
+/**
+* Create a child logger enriched with all correlation-relevant identifiers
+* extracted from the incoming HTTP request.
+*
+* The child logger's every call automatically includes:
+* `correlationId`, `requestId`, `method`, `url`, `userAgent`, `ip`
+*
+* @example
+* ```ts
+* import { childFromRequest } from 'logixia/correlation';
+* import { logger } from 'logixia';
+*
+* app.use((req, res, next) => {
+*   req.logger = childFromRequest(req, logger);
+*   next();
+* });
+*
+* app.get('/orders', (req, res) => {
+*   req.logger.info('Listing orders');  // → correlationId, requestId, method, url ...
+* });
+* ```
+*/
+function childFromRequest(req, logger, options = {}) {
+	var _headers$xForwarded, _req$socket;
+	const correlationHeader = options.correlationHeader ?? "x-correlation-id";
+	const headers = req["headers"] ?? {};
+	const correlationId = validIncomingId(headers[correlationHeader.toLowerCase()]) ?? getCurrentCorrelationId() ?? generateCorrelationId();
+	const method = req["method"];
+	const url = req["url"] ?? req["originalUrl"];
+	const userAgent = headers["user-agent"];
+	const ip = ((_headers$xForwarded = headers["x-forwarded-for"]) === null || _headers$xForwarded === void 0 || (_headers$xForwarded = _headers$xForwarded.split(",")[0]) === null || _headers$xForwarded === void 0 ? void 0 : _headers$xForwarded.trim()) ?? ((_req$socket = req["socket"]) === null || _req$socket === void 0 ? void 0 : _req$socket["remoteAddress"]);
+	return logger.child({
+		correlationId,
+		...method !== void 0 ? { method } : {},
+		...url !== void 0 ? { url } : {},
+		...userAgent !== void 0 ? { userAgent } : {},
+		...ip !== void 0 ? { ip } : {}
+	});
+}
+/**
+* Extract a correlation context from a Kafka / RabbitMQ / SQS message object.
+*
+* Looks for `correlationId`, `correlation_id`, or `x-correlation-id` in
+* `message.headers` (Kafka) or `message.MessageAttributes` (SQS).
+*
+* @example Kafka consumer
+* ```ts
+* import { extractMessageCorrelationId, withCorrelationId } from 'logixia/correlation';
+*
+* consumer.run({
+*   eachMessage: async ({ message }) => {
+*     const correlationId = extractMessageCorrelationId(message);
+*     await withCorrelationId(correlationId, () => processMessage(message));
+*   },
+* });
+* ```
+*/
+function extractMessageCorrelationId(message) {
+	const kafkaHeaders = message["headers"];
+	if (kafkaHeaders) {
+		const raw = kafkaHeaders["x-correlation-id"] ?? kafkaHeaders["correlationId"] ?? kafkaHeaders["correlation_id"];
+		if (raw !== void 0) return Buffer.isBuffer(raw) ? raw.toString("utf8") : String(raw);
+	}
+	const sqsAttrs = message["MessageAttributes"];
+	if (sqsAttrs) {
+		var _sqsAttrs$xCorrelati, _sqsAttrs$correlation, _sqsAttrs$correlation2;
+		return ((_sqsAttrs$xCorrelati = sqsAttrs["x-correlation-id"]) === null || _sqsAttrs$xCorrelati === void 0 ? void 0 : _sqsAttrs$xCorrelati.StringValue) ?? ((_sqsAttrs$correlation = sqsAttrs["correlationId"]) === null || _sqsAttrs$correlation === void 0 ? void 0 : _sqsAttrs$correlation.StringValue) ?? ((_sqsAttrs$correlation2 = sqsAttrs["correlation_id"]) === null || _sqsAttrs$correlation2 === void 0 ? void 0 : _sqsAttrs$correlation2.StringValue);
+	}
+	return message["correlationId"] ?? message["correlation_id"];
+}
+/**
+* Build Kafka message headers containing the current correlation context.
+*
+* @example
+* ```ts
+* import { buildKafkaCorrelationHeaders } from 'logixia/correlation';
+*
+* await producer.send({
+*   topic: 'orders',
+*   messages: [{ value: JSON.stringify(order), headers: buildKafkaCorrelationHeaders() }],
+* });
+* ```
+*/
+function buildKafkaCorrelationHeaders() {
+	const ctx = LogixiaContext.get();
+	const headers = {};
+	const correlationId = ctx === null || ctx === void 0 ? void 0 : ctx.correlationId;
+	if (correlationId) headers["x-correlation-id"] = correlationId;
+	const traceId = ctx === null || ctx === void 0 ? void 0 : ctx.traceId;
+	if (traceId) headers["x-trace-id"] = traceId;
+	return headers;
+}
+
+//#endregion
+export { buildKafkaCorrelationHeaders, childFromRequest, correlationFastifyHook, correlationFetch, correlationMiddleware, createCorrelationAxiosInterceptor, extractMessageCorrelationId, generateCorrelationId, getCurrentCorrelationId, withCorrelationId };
+//# sourceMappingURL=correlation.mjs.map

package/dist/correlation.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlation.mjs","names":["ctx: CorrelationContext","headers: Record<string, string>"],"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';\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 `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\nconst MAX_INCOMING_ID_LENGTH = 128;\nconst VALID_INCOMING_ID = /^[A-Za-z0-9._:-]+$/;\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: string | undefined): string | undefined {\n  if (value === undefined || value.length > MAX_INCOMING_ID_LENGTH) return undefined;\n  return VALID_INCOMING_ID.test(value) ? value : undefined;\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    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 correlationId = validIncomingId(headers[header.toLowerCase()]) ?? generate();\n    const originService = 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    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 correlationId = validIncomingId(headers[header.toLowerCase()]) ?? generate();\n    const originService = 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\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`, `requestId`, `method`, `url`, `userAgent`, `ip`\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(ctx: Record<string, unknown>): TLogger }>(\n  req: Record<string, unknown>,\n  logger: TLogger,\n  options: { correlationHeader?: string } = {}\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 userAgent = headers['user-agent'];\n  const ip =\n    (headers['x-forwarded-for'] as string | undefined)?.split(',')[0]?.trim() ??\n    ((req['socket'] as Record<string, unknown> | undefined)?.['remoteAddress'] as\n      string | undefined);\n\n  return logger.child({\n    correlationId,\n    ...(method !== undefined ? { method } : {}),\n    ...(url !== undefined ? { url } : {}),\n    ...(userAgent !== undefined ? { userAgent } : {}),\n    ...(ip !== undefined ? { ip } : {}),\n  });\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 Buffer.isBuffer(raw) ? raw.toString('utf8') : 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 (\n      sqsAttrs['x-correlation-id']?.StringValue ??\n      sqsAttrs['correlationId']?.StringValue ??\n      sqsAttrs['correlation_id']?.StringValue\n    );\n  }\n\n  // AMQP / generic envelope\n  return (\n    (message['correlationId'] as string | undefined) ??\n    (message['correlation_id'] as string | undefined)\n  );\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/gcp.d.mts

@@ -0,0 +1,3 @@
+import "./transport.types-B5vcyv2k.mjs";
+import { n as GCPTransport, r as GCPTransportConfig, t as GCPMonitoredResource } from "./gcp.transport-Bi6CUqZR.mjs";
+export { GCPMonitoredResource, GCPTransport, GCPTransportConfig };

package/dist/gcp.d.ts

@@ -0,0 +1,3 @@
+import "./transport.types-BuY84TwO.js";
+import { n as GCPTransport, r as GCPTransportConfig, t as GCPMonitoredResource } from "./gcp.transport-BOhkVKlI.js";
+export { GCPMonitoredResource, GCPTransport, GCPTransportConfig };

package/dist/gcp.js

@@ -0,0 +1,6 @@
+require('./internal-log-BUJYMZbE.js');
+require('./safe-stringify-DWo3aZp_.js');
+require('./batch-buffer-BY-mRWIK.js');
+const require_gcp_transport = require('./gcp.transport-SHdtc1n0.js');
+
+exports.GCPTransport = require_gcp_transport.GCPTransport;

package/dist/gcp.mjs

@@ -0,0 +1,6 @@
+import "./internal-log-Cm8SOWSV.mjs";
+import "./safe-stringify-DJ66tW5I.mjs";
+import "./batch-buffer-PGvSgbmd.mjs";
+import { t as GCPTransport } from "./gcp.transport-BJuNRFe_.mjs";
+
+export { GCPTransport };