logixia 1.13.0 → 1.13.3

package/dist/trace.utils-CvXgaiQT.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.utils-CvXgaiQT.mjs","names":["resolvedConfig: TraceIdConfig","traceId: string | undefined"],"sources":["../src/utils/trace.utils.ts"],"sourcesContent":["/**\n * Trace ID utilities for Logitron\n */\n\nimport { AsyncLocalStorage } from 'node:async_hooks';\nimport { randomUUID } from 'node:crypto';\n\nimport type { TraceIdConfig, TraceIdExtractorConfig } from '../types';\n\n/** Default key used to store the trace ID in AsyncLocalStorage. */\nexport const TRACE_CONTEXT_KEY = 'traceId' as const;\n\n// ── TraceContext class ────────────────────────────────────────────────────────\n\n/**\n * Singleton that owns the AsyncLocalStorage and the active contextKey.\n *\n * Why a class instead of bare module-level variables?\n *  - The contextKey is user-configurable; encapsulating it here means there is\n *    exactly one place that reads and writes it.\n *  - All helpers (getCurrentTraceId, runWithTraceId, etc.) delegate to this\n *    instance, so the key is always in sync without hidden global state.\n *  - Easier to test: you can reset the singleton between test cases.\n *\n * Usage (advanced):\n *   import { TraceContext } from 'logixia';\n *   TraceContext.instance.contextKey          // → 'traceId' (or custom)\n *   TraceContext.instance.getCurrentTraceId() // same as standalone fn\n */\nexport class TraceContext {\n  private static _instance: TraceContext | null = null;\n\n  readonly storage = new AsyncLocalStorage<Record<string, unknown>>();\n  private _contextKey: string = TRACE_CONTEXT_KEY;\n\n  private constructor() {}\n\n  /** The process-wide singleton. */\n  static get instance(): TraceContext {\n    if (!TraceContext._instance) {\n      TraceContext._instance = new TraceContext();\n    }\n    return TraceContext._instance;\n  }\n\n  /** @internal Reset the singleton (useful in tests). */\n  static _reset(): void {\n    TraceContext._instance = null;\n  }\n\n  // ── Key management ──────────────────────────────────────────────────────────\n\n  /** The AsyncLocalStorage key that holds the trace ID value. */\n  get contextKey(): string {\n    return this._contextKey;\n  }\n\n  /** @internal Called by TraceMiddleware when it boots to register the user's key. */\n  setContextKey(key: string): void {\n    this._contextKey = key;\n  }\n\n  // ── Core operations ─────────────────────────────────────────────────────────\n\n  /** UUID v4 generator (default). */\n  generate(): string {\n    return randomUUID();\n  }\n\n  /** Read the trace ID from the current async context. */\n  getCurrentTraceId(): string | undefined {\n    return this.storage.getStore()?.[this._contextKey] as string | undefined;\n  }\n\n  /**\n   * Mutate the CURRENT async context in-place.\n   *\n   * ⚠️  DEPRECATED — unsafe for concurrent requests.\n   *\n   * Uses `AsyncLocalStorage.enterWith()`, which mutates the current async\n   * execution context and every Promise chain spawned from it. In a server\n   * processing overlapping requests this can cause a trace ID set for one\n   * request to bleed into *other* in-flight requests that share the same\n   * async parent (e.g. a module-level setup function or a cached handler).\n   *\n   * Use {@link run} instead — it scopes the context to a callback so there\n   * is no risk of cross-request leakage.\n   *\n   * @deprecated Use `TraceContext.instance.run(traceId, fn)` — do not call\n   *             `setTraceId` from request-handling code.\n   */\n  setTraceId(traceId: string, data?: Record<string, unknown>): void {\n    const current = this.storage.getStore() ?? {};\n    this.storage.enterWith({ ...current, [this._contextKey]: traceId, ...data });\n  }\n\n  /** Run `fn` inside a new async context that carries `traceId`. */\n  run<T>(traceId: string, fn: () => T, data?: Record<string, unknown>): T {\n    return this.storage.run({ [this._contextKey]: traceId, ...data }, fn);\n  }\n}\n\n// ── Module-level aliases (backwards-compatible public API) ────────────────────\n\n/**\n * The shared AsyncLocalStorage instance.\n * @deprecated Prefer `TraceContext.instance.storage` for new code.\n */\nexport const traceStorage = TraceContext.instance.storage;\n\n/** Returns the key currently used to store the trace ID in AsyncLocalStorage. */\nexport function getTraceContextKey(): string {\n  return TraceContext.instance.contextKey;\n}\n\n/** @internal Called by TraceMiddleware / traceMiddleware() when they boot. */\nexport function _setActiveContextKey(key: string): void {\n  TraceContext.instance.setContextKey(key);\n}\n\n/** Generate a UUID v4 trace ID. */\nexport function generateTraceId(): string {\n  return TraceContext.instance.generate();\n}\n\n/**\n * Get the current trace ID from async context.\n * Returns `undefined` when called outside a traced request.\n */\nexport function getCurrentTraceId(): string | undefined {\n  return TraceContext.instance.getCurrentTraceId();\n}\n\n/**\n * Set trace ID in the CURRENT async context without starting a new one.\n *\n * ⚠️  DEPRECATED — unsafe for concurrent requests.\n *\n * Uses `AsyncLocalStorage.enterWith()`, which mutates the current async\n * execution context and every Promise chain spawned from it. Under load this\n * can cause a trace ID from one request to bleed into others sharing the same\n * async parent.\n *\n * Use {@link runWithTraceId} instead. Migration patterns:\n *\n * **Express / Fastify middleware — before:**\n * ```ts\n * app.use((req, _res, next) => {\n *   setTraceId(req.headers['x-trace-id'] ?? generateTraceId());\n *   next();\n * });\n * ```\n * **after:**\n * ```ts\n * app.use((req, _res, next) => {\n *   runWithTraceId(req.headers['x-trace-id'] ?? generateTraceId(), () => next());\n * });\n * ```\n *\n * **Kafka / queue consumer — before:**\n * ```ts\n * async function handle(msg) {\n *   setTraceId(msg.headers['x-trace-id']);\n *   await processMessage(msg);\n * }\n * ```\n * **after:**\n * ```ts\n * async function handle(msg) {\n *   await runWithTraceId(msg.headers['x-trace-id'], () => processMessage(msg));\n * }\n * ```\n *\n * **Background job — before:**\n * ```ts\n * setTraceId(generateTraceId(), { jobId: job.id });\n * await job.run();\n * ```\n * **after:**\n * ```ts\n * await runWithTraceId(generateTraceId(), () => job.run(), { jobId: job.id });\n * ```\n *\n * @deprecated Use `runWithTraceId(traceId, fn)` — do not call `setTraceId`\n *             from request-handling code.\n */\nexport function setTraceId(traceId: string, data?: Record<string, unknown>): void {\n  TraceContext.instance.setTraceId(traceId, data);\n}\n\n/** Run `fn` inside a new async context carrying `traceId`. */\nexport function runWithTraceId<T>(traceId: string, fn: () => T, data?: Record<string, unknown>): T {\n  return TraceContext.instance.run(traceId, fn, data);\n}\n\n// ── Request extraction ────────────────────────────────────────────────────────\n\n/** Shape that extractTraceId accepts (Express-compatible) */\ninterface RequestLike {\n  headers?: Record<string, string | string[] | undefined>;\n  query?: Record<string, string | string[] | undefined>;\n  body?: Record<string, string | undefined>;\n  params?: Record<string, string | undefined>;\n}\n\n/** Maximum accepted length for an incoming trace / correlation / request ID. */\nexport const MAX_INCOMING_ID_LENGTH = 128;\n\nconst SAFE_INCOMING_ID = /^[A-Za-z0-9._:-]{1,128}$/;\n\n/**\n * Validate an externally supplied identifier (trace ID, correlation ID, origin\n * service name, message-queue ID). Accepts only 1-128 characters from\n * `[A-Za-z0-9._:-]`; surrounding whitespace is trimmed first. Arrays use their\n * first element. Returns the cleaned value, or `undefined` when it is unusable\n * so callers can generate a fresh ID instead of passing client text through.\n */\nexport function sanitizeIncomingId(value: unknown): string | undefined {\n  const first = Array.isArray(value) ? value[0] : value;\n  if (typeof first !== 'string' || first.length > MAX_INCOMING_ID_LENGTH * 2) return undefined;\n  const trimmed = first.trim();\n  return SAFE_INCOMING_ID.test(trimmed) ? trimmed : undefined;\n}\n\n/** W3C trace-context: `version-traceId(32hex)-spanId(16hex)-flags(2hex)`. */\nconst W3C_TRACEPARENT_RE = /^[\\da-f]{2}-([\\da-f]{32})-[\\da-f]{16}-[\\da-f]{2}$/i;\n\n/**\n * Extract the 32-hex trace-id segment from a W3C `traceparent` header value.\n * Returns the parsed trace ID, or the original value unchanged when it is not a\n * well-formed traceparent (so non-W3C propagation still works).\n */\nfunction parseTraceparent(value: string): string {\n  const m = W3C_TRACEPARENT_RE.exec(value);\n  return m ? m[1]! : value;\n}\n\n/** Extract trace ID from request using configuration (header → query → body → params). */\nexport function extractTraceId(\n  request: unknown,\n  config: TraceIdExtractorConfig\n): string | undefined {\n  const req = request as RequestLike;\n\n  if (config.header) {\n    const headers = Array.isArray(config.header) ? config.header : [config.header];\n    for (const header of headers) {\n      const lower = header.toLowerCase();\n      const value = sanitizeIncomingId(req.headers?.[lower]);\n      if (value) return lower === 'traceparent' ? parseTraceparent(value) : value;\n    }\n  }\n\n  if (config.query) {\n    const queries = Array.isArray(config.query) ? config.query : [config.query];\n    for (const query of queries) {\n      const value = sanitizeIncomingId(req.query?.[query]);\n      if (value) return value;\n    }\n  }\n\n  if (config.body) {\n    const bodyFields = Array.isArray(config.body) ? config.body : [config.body];\n    for (const field of bodyFields) {\n      const value = sanitizeIncomingId(req.body?.[field]);\n      if (value) return value;\n    }\n  }\n\n  if (config.params) {\n    const paramFields = Array.isArray(config.params) ? config.params : [config.params];\n    for (const param of paramFields) {\n      const value = sanitizeIncomingId(req.params?.[param]);\n      if (value) return value;\n    }\n  }\n\n  return undefined;\n}\n\n/**\n * Default headers checked for incoming trace ID propagation, in priority order:\n *   traceparent (W3C/OTel) → x-trace-id → x-request-id → x-correlation-id → trace-id\n */\nexport const DEFAULT_TRACE_HEADERS = [\n  'traceparent',\n  'x-trace-id',\n  'x-request-id',\n  'x-correlation-id',\n  'trace-id',\n];\n\n/**\n * Create trace ID middleware for Express/NestJS\n */\nexport function createTraceMiddleware(config: TraceIdConfig) {\n  const defaultExtractor = {\n    header: DEFAULT_TRACE_HEADERS,\n    query: ['traceId', 'trace_id'],\n  };\n  const resolvedConfig: TraceIdConfig = {\n    ...config,\n    extractor: config?.extractor ? { ...defaultExtractor, ...config.extractor } : defaultExtractor,\n  };\n\n  _setActiveContextKey(resolvedConfig.contextKey ?? TRACE_CONTEXT_KEY);\n\n  return (req: unknown, res: unknown, next: () => void) => {\n    let traceId: string | undefined;\n\n    if (resolvedConfig.extractor) {\n      traceId = extractTraceId(req, resolvedConfig.extractor);\n    }\n\n    if (!traceId) {\n      traceId = resolvedConfig.generator ? resolvedConfig.generator() : generateTraceId();\n    }\n\n    (req as Record<string, unknown>).traceId = traceId;\n    // Echo the trace ID back on the response, tolerating different response APIs:\n    // Express/Node use res.setHeader(), Fastify replies use reply.header(). Guard\n    // both and never let a missing/!function method (or already-sent headers)\n    // crash the request — the trace ID is still propagated via async context.\n    const resObj = res as {\n      setHeader?: (k: string, v: string) => void;\n      header?: (k: string, v: string) => void;\n      headersSent?: boolean;\n    };\n    if (!resObj.headersSent) {\n      try {\n        if (typeof resObj.setHeader === 'function') {\n          resObj.setHeader('X-Trace-Id', traceId);\n        } else if (typeof resObj.header === 'function') {\n          resObj.header('X-Trace-Id', traceId);\n        }\n      } catch {\n        /* response not in a header-settable state — context propagation still works */\n      }\n    }\n\n    runWithTraceId(traceId, () => next());\n  };\n}\n"],"mappings":"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"}

package/dist/trace.utils-DpBOLDtq.js

@@ -0,0 +1,358 @@
+const require_chunk = require('./chunk-nOFOJqeH.js');
+let node_crypto = require("node:crypto");
+node_crypto = require_chunk.__toESM(node_crypto);
+let node_async_hooks = require("node:async_hooks");
+node_async_hooks = require_chunk.__toESM(node_async_hooks);
+
+//#region src/utils/trace.utils.ts
+/** Default key used to store the trace ID in AsyncLocalStorage. */
+const TRACE_CONTEXT_KEY = "traceId";
+/**
+* Singleton that owns the AsyncLocalStorage and the active contextKey.
+*
+* Why a class instead of bare module-level variables?
+*  - The contextKey is user-configurable; encapsulating it here means there is
+*    exactly one place that reads and writes it.
+*  - All helpers (getCurrentTraceId, runWithTraceId, etc.) delegate to this
+*    instance, so the key is always in sync without hidden global state.
+*  - Easier to test: you can reset the singleton between test cases.
+*
+* Usage (advanced):
+*   import { TraceContext } from 'logixia';
+*   TraceContext.instance.contextKey          // → 'traceId' (or custom)
+*   TraceContext.instance.getCurrentTraceId() // same as standalone fn
+*/
+var TraceContext = class TraceContext {
+	static #_ = this._instance = null;
+	constructor() {
+		this.storage = new node_async_hooks.AsyncLocalStorage();
+		this._contextKey = TRACE_CONTEXT_KEY;
+	}
+	/** The process-wide singleton. */
+	static get instance() {
+		if (!TraceContext._instance) TraceContext._instance = new TraceContext();
+		return TraceContext._instance;
+	}
+	/** @internal Reset the singleton (useful in tests). */
+	static _reset() {
+		TraceContext._instance = null;
+	}
+	/** The AsyncLocalStorage key that holds the trace ID value. */
+	get contextKey() {
+		return this._contextKey;
+	}
+	/** @internal Called by TraceMiddleware when it boots to register the user's key. */
+	setContextKey(key) {
+		this._contextKey = key;
+	}
+	/** UUID v4 generator (default). */
+	generate() {
+		return (0, node_crypto.randomUUID)();
+	}
+	/** Read the trace ID from the current async context. */
+	getCurrentTraceId() {
+		var _this$storage$getStor;
+		return (_this$storage$getStor = this.storage.getStore()) === null || _this$storage$getStor === void 0 ? void 0 : _this$storage$getStor[this._contextKey];
+	}
+	/**
+	* Mutate the CURRENT async context in-place.
+	*
+	* ⚠️  DEPRECATED — unsafe for concurrent requests.
+	*
+	* Uses `AsyncLocalStorage.enterWith()`, which mutates the current async
+	* execution context and every Promise chain spawned from it. In a server
+	* processing overlapping requests this can cause a trace ID set for one
+	* request to bleed into *other* in-flight requests that share the same
+	* async parent (e.g. a module-level setup function or a cached handler).
+	*
+	* Use {@link run} instead — it scopes the context to a callback so there
+	* is no risk of cross-request leakage.
+	*
+	* @deprecated Use `TraceContext.instance.run(traceId, fn)` — do not call
+	*             `setTraceId` from request-handling code.
+	*/
+	setTraceId(traceId, data) {
+		const current = this.storage.getStore() ?? {};
+		this.storage.enterWith({
+			...current,
+			[this._contextKey]: traceId,
+			...data
+		});
+	}
+	/** Run `fn` inside a new async context that carries `traceId`. */
+	run(traceId, fn, data) {
+		return this.storage.run({
+			[this._contextKey]: traceId,
+			...data
+		}, fn);
+	}
+};
+/**
+* The shared AsyncLocalStorage instance.
+* @deprecated Prefer `TraceContext.instance.storage` for new code.
+*/
+const traceStorage = TraceContext.instance.storage;
+/** Returns the key currently used to store the trace ID in AsyncLocalStorage. */
+function getTraceContextKey() {
+	return TraceContext.instance.contextKey;
+}
+/** @internal Called by TraceMiddleware / traceMiddleware() when they boot. */
+function _setActiveContextKey(key) {
+	TraceContext.instance.setContextKey(key);
+}
+/** Generate a UUID v4 trace ID. */
+function generateTraceId() {
+	return TraceContext.instance.generate();
+}
+/**
+* Get the current trace ID from async context.
+* Returns `undefined` when called outside a traced request.
+*/
+function getCurrentTraceId() {
+	return TraceContext.instance.getCurrentTraceId();
+}
+/**
+* Set trace ID in the CURRENT async context without starting a new one.
+*
+* ⚠️  DEPRECATED — unsafe for concurrent requests.
+*
+* Uses `AsyncLocalStorage.enterWith()`, which mutates the current async
+* execution context and every Promise chain spawned from it. Under load this
+* can cause a trace ID from one request to bleed into others sharing the same
+* async parent.
+*
+* Use {@link runWithTraceId} instead. Migration patterns:
+*
+* **Express / Fastify middleware — before:**
+* ```ts
+* app.use((req, _res, next) => {
+*   setTraceId(req.headers['x-trace-id'] ?? generateTraceId());
+*   next();
+* });
+* ```
+* **after:**
+* ```ts
+* app.use((req, _res, next) => {
+*   runWithTraceId(req.headers['x-trace-id'] ?? generateTraceId(), () => next());
+* });
+* ```
+*
+* **Kafka / queue consumer — before:**
+* ```ts
+* async function handle(msg) {
+*   setTraceId(msg.headers['x-trace-id']);
+*   await processMessage(msg);
+* }
+* ```
+* **after:**
+* ```ts
+* async function handle(msg) {
+*   await runWithTraceId(msg.headers['x-trace-id'], () => processMessage(msg));
+* }
+* ```
+*
+* **Background job — before:**
+* ```ts
+* setTraceId(generateTraceId(), { jobId: job.id });
+* await job.run();
+* ```
+* **after:**
+* ```ts
+* await runWithTraceId(generateTraceId(), () => job.run(), { jobId: job.id });
+* ```
+*
+* @deprecated Use `runWithTraceId(traceId, fn)` — do not call `setTraceId`
+*             from request-handling code.
+*/
+function setTraceId(traceId, data) {
+	TraceContext.instance.setTraceId(traceId, data);
+}
+/** Run `fn` inside a new async context carrying `traceId`. */
+function runWithTraceId(traceId, fn, data) {
+	return TraceContext.instance.run(traceId, fn, data);
+}
+/** Maximum accepted length for an incoming trace / correlation / request ID. */
+const MAX_INCOMING_ID_LENGTH = 128;
+const SAFE_INCOMING_ID = /^[A-Za-z0-9._:-]{1,128}$/;
+/**
+* Validate an externally supplied identifier (trace ID, correlation ID, origin
+* service name, message-queue ID). Accepts only 1-128 characters from
+* `[A-Za-z0-9._:-]`; surrounding whitespace is trimmed first. Arrays use their
+* first element. Returns the cleaned value, or `undefined` when it is unusable
+* so callers can generate a fresh ID instead of passing client text through.
+*/
+function sanitizeIncomingId(value) {
+	const first = Array.isArray(value) ? value[0] : value;
+	if (typeof first !== "string" || first.length > MAX_INCOMING_ID_LENGTH * 2) return void 0;
+	const trimmed = first.trim();
+	return SAFE_INCOMING_ID.test(trimmed) ? trimmed : void 0;
+}
+/** W3C trace-context: `version-traceId(32hex)-spanId(16hex)-flags(2hex)`. */
+const W3C_TRACEPARENT_RE = /^[\da-f]{2}-([\da-f]{32})-[\da-f]{16}-[\da-f]{2}$/i;
+/**
+* Extract the 32-hex trace-id segment from a W3C `traceparent` header value.
+* Returns the parsed trace ID, or the original value unchanged when it is not a
+* well-formed traceparent (so non-W3C propagation still works).
+*/
+function parseTraceparent(value) {
+	const m = W3C_TRACEPARENT_RE.exec(value);
+	return m ? m[1] : value;
+}
+/** Extract trace ID from request using configuration (header → query → body → params). */
+function extractTraceId(request, config) {
+	const req = request;
+	if (config.header) {
+		const headers = Array.isArray(config.header) ? config.header : [config.header];
+		for (const header of headers) {
+			var _req$headers;
+			const lower = header.toLowerCase();
+			const value = sanitizeIncomingId((_req$headers = req.headers) === null || _req$headers === void 0 ? void 0 : _req$headers[lower]);
+			if (value) return lower === "traceparent" ? parseTraceparent(value) : value;
+		}
+	}
+	if (config.query) {
+		const queries = Array.isArray(config.query) ? config.query : [config.query];
+		for (const query of queries) {
+			var _req$query;
+			const value = sanitizeIncomingId((_req$query = req.query) === null || _req$query === void 0 ? void 0 : _req$query[query]);
+			if (value) return value;
+		}
+	}
+	if (config.body) {
+		const bodyFields = Array.isArray(config.body) ? config.body : [config.body];
+		for (const field of bodyFields) {
+			var _req$body;
+			const value = sanitizeIncomingId((_req$body = req.body) === null || _req$body === void 0 ? void 0 : _req$body[field]);
+			if (value) return value;
+		}
+	}
+	if (config.params) {
+		const paramFields = Array.isArray(config.params) ? config.params : [config.params];
+		for (const param of paramFields) {
+			var _req$params;
+			const value = sanitizeIncomingId((_req$params = req.params) === null || _req$params === void 0 ? void 0 : _req$params[param]);
+			if (value) return value;
+		}
+	}
+}
+/**
+* Default headers checked for incoming trace ID propagation, in priority order:
+*   traceparent (W3C/OTel) → x-trace-id → x-request-id → x-correlation-id → trace-id
+*/
+const DEFAULT_TRACE_HEADERS = [
+	"traceparent",
+	"x-trace-id",
+	"x-request-id",
+	"x-correlation-id",
+	"trace-id"
+];
+/**
+* Create trace ID middleware for Express/NestJS
+*/
+function createTraceMiddleware(config) {
+	const defaultExtractor = {
+		header: DEFAULT_TRACE_HEADERS,
+		query: ["traceId", "trace_id"]
+	};
+	const resolvedConfig = {
+		...config,
+		extractor: (config === null || config === void 0 ? void 0 : config.extractor) ? {
+			...defaultExtractor,
+			...config.extractor
+		} : defaultExtractor
+	};
+	_setActiveContextKey(resolvedConfig.contextKey ?? TRACE_CONTEXT_KEY);
+	return (req, res, next) => {
+		let traceId;
+		if (resolvedConfig.extractor) traceId = extractTraceId(req, resolvedConfig.extractor);
+		if (!traceId) traceId = resolvedConfig.generator ? resolvedConfig.generator() : generateTraceId();
+		req.traceId = traceId;
+		const resObj = res;
+		if (!resObj.headersSent) try {
+			if (typeof resObj.setHeader === "function") resObj.setHeader("X-Trace-Id", traceId);
+			else if (typeof resObj.header === "function") resObj.header("X-Trace-Id", traceId);
+		} catch {}
+		runWithTraceId(traceId, () => next());
+	};
+}
+
+//#endregion
+Object.defineProperty(exports, 'DEFAULT_TRACE_HEADERS', {
+  enumerable: true,
+  get: function () {
+    return DEFAULT_TRACE_HEADERS;
+  }
+});
+Object.defineProperty(exports, 'MAX_INCOMING_ID_LENGTH', {
+  enumerable: true,
+  get: function () {
+    return MAX_INCOMING_ID_LENGTH;
+  }
+});
+Object.defineProperty(exports, 'TRACE_CONTEXT_KEY', {
+  enumerable: true,
+  get: function () {
+    return TRACE_CONTEXT_KEY;
+  }
+});
+Object.defineProperty(exports, 'TraceContext', {
+  enumerable: true,
+  get: function () {
+    return TraceContext;
+  }
+});
+Object.defineProperty(exports, '_setActiveContextKey', {
+  enumerable: true,
+  get: function () {
+    return _setActiveContextKey;
+  }
+});
+Object.defineProperty(exports, 'createTraceMiddleware', {
+  enumerable: true,
+  get: function () {
+    return createTraceMiddleware;
+  }
+});
+Object.defineProperty(exports, 'extractTraceId', {
+  enumerable: true,
+  get: function () {
+    return extractTraceId;
+  }
+});
+Object.defineProperty(exports, 'getCurrentTraceId', {
+  enumerable: true,
+  get: function () {
+    return getCurrentTraceId;
+  }
+});
+Object.defineProperty(exports, 'getTraceContextKey', {
+  enumerable: true,
+  get: function () {
+    return getTraceContextKey;
+  }
+});
+Object.defineProperty(exports, 'runWithTraceId', {
+  enumerable: true,
+  get: function () {
+    return runWithTraceId;
+  }
+});
+Object.defineProperty(exports, 'sanitizeIncomingId', {
+  enumerable: true,
+  get: function () {
+    return sanitizeIncomingId;
+  }
+});
+Object.defineProperty(exports, 'setTraceId', {
+  enumerable: true,
+  get: function () {
+    return setTraceId;
+  }
+});
+Object.defineProperty(exports, 'traceStorage', {
+  enumerable: true,
+  get: function () {
+    return traceStorage;
+  }
+});
+//# sourceMappingURL=trace.utils-DpBOLDtq.js.map

package/dist/trace.utils-DpBOLDtq.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.utils-DpBOLDtq.js","names":["AsyncLocalStorage","resolvedConfig: TraceIdConfig","traceId: string | undefined"],"sources":["../src/utils/trace.utils.ts"],"sourcesContent":["/**\n * Trace ID utilities for Logitron\n */\n\nimport { AsyncLocalStorage } from 'node:async_hooks';\nimport { randomUUID } from 'node:crypto';\n\nimport type { TraceIdConfig, TraceIdExtractorConfig } from '../types';\n\n/** Default key used to store the trace ID in AsyncLocalStorage. */\nexport const TRACE_CONTEXT_KEY = 'traceId' as const;\n\n// ── TraceContext class ────────────────────────────────────────────────────────\n\n/**\n * Singleton that owns the AsyncLocalStorage and the active contextKey.\n *\n * Why a class instead of bare module-level variables?\n *  - The contextKey is user-configurable; encapsulating it here means there is\n *    exactly one place that reads and writes it.\n *  - All helpers (getCurrentTraceId, runWithTraceId, etc.) delegate to this\n *    instance, so the key is always in sync without hidden global state.\n *  - Easier to test: you can reset the singleton between test cases.\n *\n * Usage (advanced):\n *   import { TraceContext } from 'logixia';\n *   TraceContext.instance.contextKey          // → 'traceId' (or custom)\n *   TraceContext.instance.getCurrentTraceId() // same as standalone fn\n */\nexport class TraceContext {\n  private static _instance: TraceContext | null = null;\n\n  readonly storage = new AsyncLocalStorage<Record<string, unknown>>();\n  private _contextKey: string = TRACE_CONTEXT_KEY;\n\n  private constructor() {}\n\n  /** The process-wide singleton. */\n  static get instance(): TraceContext {\n    if (!TraceContext._instance) {\n      TraceContext._instance = new TraceContext();\n    }\n    return TraceContext._instance;\n  }\n\n  /** @internal Reset the singleton (useful in tests). */\n  static _reset(): void {\n    TraceContext._instance = null;\n  }\n\n  // ── Key management ──────────────────────────────────────────────────────────\n\n  /** The AsyncLocalStorage key that holds the trace ID value. */\n  get contextKey(): string {\n    return this._contextKey;\n  }\n\n  /** @internal Called by TraceMiddleware when it boots to register the user's key. */\n  setContextKey(key: string): void {\n    this._contextKey = key;\n  }\n\n  // ── Core operations ─────────────────────────────────────────────────────────\n\n  /** UUID v4 generator (default). */\n  generate(): string {\n    return randomUUID();\n  }\n\n  /** Read the trace ID from the current async context. */\n  getCurrentTraceId(): string | undefined {\n    return this.storage.getStore()?.[this._contextKey] as string | undefined;\n  }\n\n  /**\n   * Mutate the CURRENT async context in-place.\n   *\n   * ⚠️  DEPRECATED — unsafe for concurrent requests.\n   *\n   * Uses `AsyncLocalStorage.enterWith()`, which mutates the current async\n   * execution context and every Promise chain spawned from it. In a server\n   * processing overlapping requests this can cause a trace ID set for one\n   * request to bleed into *other* in-flight requests that share the same\n   * async parent (e.g. a module-level setup function or a cached handler).\n   *\n   * Use {@link run} instead — it scopes the context to a callback so there\n   * is no risk of cross-request leakage.\n   *\n   * @deprecated Use `TraceContext.instance.run(traceId, fn)` — do not call\n   *             `setTraceId` from request-handling code.\n   */\n  setTraceId(traceId: string, data?: Record<string, unknown>): void {\n    const current = this.storage.getStore() ?? {};\n    this.storage.enterWith({ ...current, [this._contextKey]: traceId, ...data });\n  }\n\n  /** Run `fn` inside a new async context that carries `traceId`. */\n  run<T>(traceId: string, fn: () => T, data?: Record<string, unknown>): T {\n    return this.storage.run({ [this._contextKey]: traceId, ...data }, fn);\n  }\n}\n\n// ── Module-level aliases (backwards-compatible public API) ────────────────────\n\n/**\n * The shared AsyncLocalStorage instance.\n * @deprecated Prefer `TraceContext.instance.storage` for new code.\n */\nexport const traceStorage = TraceContext.instance.storage;\n\n/** Returns the key currently used to store the trace ID in AsyncLocalStorage. */\nexport function getTraceContextKey(): string {\n  return TraceContext.instance.contextKey;\n}\n\n/** @internal Called by TraceMiddleware / traceMiddleware() when they boot. */\nexport function _setActiveContextKey(key: string): void {\n  TraceContext.instance.setContextKey(key);\n}\n\n/** Generate a UUID v4 trace ID. */\nexport function generateTraceId(): string {\n  return TraceContext.instance.generate();\n}\n\n/**\n * Get the current trace ID from async context.\n * Returns `undefined` when called outside a traced request.\n */\nexport function getCurrentTraceId(): string | undefined {\n  return TraceContext.instance.getCurrentTraceId();\n}\n\n/**\n * Set trace ID in the CURRENT async context without starting a new one.\n *\n * ⚠️  DEPRECATED — unsafe for concurrent requests.\n *\n * Uses `AsyncLocalStorage.enterWith()`, which mutates the current async\n * execution context and every Promise chain spawned from it. Under load this\n * can cause a trace ID from one request to bleed into others sharing the same\n * async parent.\n *\n * Use {@link runWithTraceId} instead. Migration patterns:\n *\n * **Express / Fastify middleware — before:**\n * ```ts\n * app.use((req, _res, next) => {\n *   setTraceId(req.headers['x-trace-id'] ?? generateTraceId());\n *   next();\n * });\n * ```\n * **after:**\n * ```ts\n * app.use((req, _res, next) => {\n *   runWithTraceId(req.headers['x-trace-id'] ?? generateTraceId(), () => next());\n * });\n * ```\n *\n * **Kafka / queue consumer — before:**\n * ```ts\n * async function handle(msg) {\n *   setTraceId(msg.headers['x-trace-id']);\n *   await processMessage(msg);\n * }\n * ```\n * **after:**\n * ```ts\n * async function handle(msg) {\n *   await runWithTraceId(msg.headers['x-trace-id'], () => processMessage(msg));\n * }\n * ```\n *\n * **Background job — before:**\n * ```ts\n * setTraceId(generateTraceId(), { jobId: job.id });\n * await job.run();\n * ```\n * **after:**\n * ```ts\n * await runWithTraceId(generateTraceId(), () => job.run(), { jobId: job.id });\n * ```\n *\n * @deprecated Use `runWithTraceId(traceId, fn)` — do not call `setTraceId`\n *             from request-handling code.\n */\nexport function setTraceId(traceId: string, data?: Record<string, unknown>): void {\n  TraceContext.instance.setTraceId(traceId, data);\n}\n\n/** Run `fn` inside a new async context carrying `traceId`. */\nexport function runWithTraceId<T>(traceId: string, fn: () => T, data?: Record<string, unknown>): T {\n  return TraceContext.instance.run(traceId, fn, data);\n}\n\n// ── Request extraction ────────────────────────────────────────────────────────\n\n/** Shape that extractTraceId accepts (Express-compatible) */\ninterface RequestLike {\n  headers?: Record<string, string | string[] | undefined>;\n  query?: Record<string, string | string[] | undefined>;\n  body?: Record<string, string | undefined>;\n  params?: Record<string, string | undefined>;\n}\n\n/** Maximum accepted length for an incoming trace / correlation / request ID. */\nexport const MAX_INCOMING_ID_LENGTH = 128;\n\nconst SAFE_INCOMING_ID = /^[A-Za-z0-9._:-]{1,128}$/;\n\n/**\n * Validate an externally supplied identifier (trace ID, correlation ID, origin\n * service name, message-queue ID). Accepts only 1-128 characters from\n * `[A-Za-z0-9._:-]`; surrounding whitespace is trimmed first. Arrays use their\n * first element. Returns the cleaned value, or `undefined` when it is unusable\n * so callers can generate a fresh ID instead of passing client text through.\n */\nexport function sanitizeIncomingId(value: unknown): string | undefined {\n  const first = Array.isArray(value) ? value[0] : value;\n  if (typeof first !== 'string' || first.length > MAX_INCOMING_ID_LENGTH * 2) return undefined;\n  const trimmed = first.trim();\n  return SAFE_INCOMING_ID.test(trimmed) ? trimmed : undefined;\n}\n\n/** W3C trace-context: `version-traceId(32hex)-spanId(16hex)-flags(2hex)`. */\nconst W3C_TRACEPARENT_RE = /^[\\da-f]{2}-([\\da-f]{32})-[\\da-f]{16}-[\\da-f]{2}$/i;\n\n/**\n * Extract the 32-hex trace-id segment from a W3C `traceparent` header value.\n * Returns the parsed trace ID, or the original value unchanged when it is not a\n * well-formed traceparent (so non-W3C propagation still works).\n */\nfunction parseTraceparent(value: string): string {\n  const m = W3C_TRACEPARENT_RE.exec(value);\n  return m ? m[1]! : value;\n}\n\n/** Extract trace ID from request using configuration (header → query → body → params). */\nexport function extractTraceId(\n  request: unknown,\n  config: TraceIdExtractorConfig\n): string | undefined {\n  const req = request as RequestLike;\n\n  if (config.header) {\n    const headers = Array.isArray(config.header) ? config.header : [config.header];\n    for (const header of headers) {\n      const lower = header.toLowerCase();\n      const value = sanitizeIncomingId(req.headers?.[lower]);\n      if (value) return lower === 'traceparent' ? parseTraceparent(value) : value;\n    }\n  }\n\n  if (config.query) {\n    const queries = Array.isArray(config.query) ? config.query : [config.query];\n    for (const query of queries) {\n      const value = sanitizeIncomingId(req.query?.[query]);\n      if (value) return value;\n    }\n  }\n\n  if (config.body) {\n    const bodyFields = Array.isArray(config.body) ? config.body : [config.body];\n    for (const field of bodyFields) {\n      const value = sanitizeIncomingId(req.body?.[field]);\n      if (value) return value;\n    }\n  }\n\n  if (config.params) {\n    const paramFields = Array.isArray(config.params) ? config.params : [config.params];\n    for (const param of paramFields) {\n      const value = sanitizeIncomingId(req.params?.[param]);\n      if (value) return value;\n    }\n  }\n\n  return undefined;\n}\n\n/**\n * Default headers checked for incoming trace ID propagation, in priority order:\n *   traceparent (W3C/OTel) → x-trace-id → x-request-id → x-correlation-id → trace-id\n */\nexport const DEFAULT_TRACE_HEADERS = [\n  'traceparent',\n  'x-trace-id',\n  'x-request-id',\n  'x-correlation-id',\n  'trace-id',\n];\n\n/**\n * Create trace ID middleware for Express/NestJS\n */\nexport function createTraceMiddleware(config: TraceIdConfig) {\n  const defaultExtractor = {\n    header: DEFAULT_TRACE_HEADERS,\n    query: ['traceId', 'trace_id'],\n  };\n  const resolvedConfig: TraceIdConfig = {\n    ...config,\n    extractor: config?.extractor ? { ...defaultExtractor, ...config.extractor } : defaultExtractor,\n  };\n\n  _setActiveContextKey(resolvedConfig.contextKey ?? TRACE_CONTEXT_KEY);\n\n  return (req: unknown, res: unknown, next: () => void) => {\n    let traceId: string | undefined;\n\n    if (resolvedConfig.extractor) {\n      traceId = extractTraceId(req, resolvedConfig.extractor);\n    }\n\n    if (!traceId) {\n      traceId = resolvedConfig.generator ? resolvedConfig.generator() : generateTraceId();\n    }\n\n    (req as Record<string, unknown>).traceId = traceId;\n    // Echo the trace ID back on the response, tolerating different response APIs:\n    // Express/Node use res.setHeader(), Fastify replies use reply.header(). Guard\n    // both and never let a missing/!function method (or already-sent headers)\n    // crash the request — the trace ID is still propagated via async context.\n    const resObj = res as {\n      setHeader?: (k: string, v: string) => void;\n      header?: (k: string, v: string) => void;\n      headersSent?: boolean;\n    };\n    if (!resObj.headersSent) {\n      try {\n        if (typeof resObj.setHeader === 'function') {\n          resObj.setHeader('X-Trace-Id', traceId);\n        } else if (typeof resObj.header === 'function') {\n          resObj.header('X-Trace-Id', traceId);\n        }\n      } catch {\n        /* response not in a header-settable state — context propagation still works */\n      }\n    }\n\n    runWithTraceId(traceId, () => next());\n  };\n}\n"],"mappings":"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"}