logixia 1.7.0 → 1.7.1

package/dist/{logitron-logger.module-BcCtbMEe.js → logitron-logger.module-BI5eI4X9.js}

@@ -812,51 +812,116 @@ var v4_default = v4;
 
 //#endregion
 //#region src/utils/trace.utils.ts
-/** The key under which the trace ID is stored in AsyncLocalStorage. */
+/** Default key used to store the trace ID in AsyncLocalStorage. */
 const TRACE_CONTEXT_KEY = "traceId";
-const traceStorage = new node_async_hooks.AsyncLocalStorage();
 /**
-* Default trace ID generator using UUID v4
+* 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 v4_default();
+	}
+	/** 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.
+	*
+	* ⚠️  Uses `enterWith()` — prefer `run()` when you can wrap the operation
+	* in a callback, as it scopes the context to the callback only.
+	*/
+	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 v4_default();
+	return TraceContext.instance.generate();
 }
 /**
-* Get current trace ID from async context
+* Get the current trace ID from async context.
+* Returns `undefined` when called outside a traced request.
 */
 function getCurrentTraceId() {
-	const store = traceStorage.getStore();
-	return store === null || store === void 0 ? void 0 : store.traceId;
+	return TraceContext.instance.getCurrentTraceId();
 }
 /**
 * Set trace ID in the CURRENT async context without starting a new one.
 *
-* ⚠️  Uses `enterWith()` which mutates the context for the current async
-* execution and ALL futures spawned from it. Prefer `runWithTraceId()` when
-* you can wrap the operation in a callback, as it creates a properly-scoped
-* child context. Use `setTraceId()` only when you cannot use `runWithTraceId()`
-* (e.g., inside a class constructor or a non-callback async entry point).
+* ⚠️  Uses `enterWith()` — mutates the context for the current async execution
+* and all futures spawned from it. Prefer `runWithTraceId()` when you can wrap
+* the operation in a callback.
 */
 function setTraceId(traceId, data) {
-	const currentStore = traceStorage.getStore() ?? {};
-	traceStorage.enterWith({
-		...currentStore,
-		traceId,
-		...data
-	});
+	TraceContext.instance.setTraceId(traceId, data);
 }
-/**
-* Run function with trace ID context
-*/
+/** Run `fn` inside a new async context carrying `traceId`. */
 function runWithTraceId(traceId, fn, data) {
-	return traceStorage.run({
-		traceId,
-		...data
-	}, fn);
+	return TraceContext.instance.run(traceId, fn, data);
 }
-/**
-* Extract trace ID from request using configuration
-*/
+/** Extract trace ID from request using configuration (header → query → body → params). */
 function extractTraceId(request, config) {
 	const req = request;
 	if (config.header) {
@@ -896,7 +961,7 @@ function extractTraceId(request, config) {
 * 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$1 = [
+const DEFAULT_TRACE_HEADERS = [
 	"traceparent",
 	"x-trace-id",
 	"x-request-id",
@@ -908,7 +973,7 @@ const DEFAULT_TRACE_HEADERS$1 = [
 */
 function createTraceMiddleware(config) {
 	const defaultExtractor = {
-		header: DEFAULT_TRACE_HEADERS$1,
+		header: DEFAULT_TRACE_HEADERS,
 		query: ["traceId", "trace_id"]
 	};
 	const resolvedConfig = {
@@ -918,15 +983,14 @@ function createTraceMiddleware(config) {
 			...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;
 		res.setHeader("X-Trace-Id", traceId);
-		runWithTraceId(traceId, () => {
-			next();
-		}, { requestId: req["id"] || req["requestId"] || generateTraceId() });
+		runWithTraceId(traceId, () => next(), { requestId: req["id"] || req["requestId"] || generateTraceId() });
 	};
 }
 
@@ -985,7 +1049,7 @@ var LogixiaLogger = class LogixiaLogger {
 		this.timers = /* @__PURE__ */ new Map();
 		this.contextData = {};
 		this.fieldState = /* @__PURE__ */ new Map();
-		this.fallbackTraceId = generateTraceId();
+		this.fallbackTraceId = TraceContext.instance.generate();
 		this._levelValues = /* @__PURE__ */ new Map();
 		this._minLevelValue = 2;
 		this._colorMap = /* @__PURE__ */ new Map();
@@ -1371,7 +1435,7 @@ var LogixiaLogger = class LogixiaLogger {
 		if (this.config.silent) return;
 		if (!this.shouldLog(level)) return;
 		if (this._sampler) {
-			const traceId$1 = this.config.traceId ? getCurrentTraceId() ?? this.fallbackTraceId : void 0;
+			const traceId$1 = this.config.traceId ? TraceContext.instance.getCurrentTraceId() ?? this.fallbackTraceId : void 0;
 			if (!this._sampler.shouldEmit(level, traceId$1)) return;
 		}
 		const alsContext = LogixiaContext.get();
@@ -1394,7 +1458,7 @@ var LogixiaLogger = class LogixiaLogger {
 		} : mergedData;
 		let payload;
 		if (rawPayload !== void 0 && rawPayload !== null) payload = this._hasRedact ? applyRedaction(rawPayload, this.config.redact) ?? rawPayload : rawPayload;
-		const traceId = this.config.traceId ? getCurrentTraceId() ?? this.fallbackTraceId : void 0;
+		const traceId = this.config.traceId ? TraceContext.instance.getCurrentTraceId() ?? this.fallbackTraceId : void 0;
 		const entry = {
 			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
 			level,
@@ -1645,11 +1709,11 @@ let LogixiaLoggerService = _LogixiaLoggerService = class LogixiaLoggerService$1
 		return childService;
 	}
 	getCurrentTraceId() {
-		return getCurrentTraceId();
+		return TraceContext.instance.getCurrentTraceId();
 	}
-	/** The AsyncLocalStorage key under which the trace ID is stored ('traceId'). */
+	/** Returns the AsyncLocalStorage key currently used to store the trace ID. */
 	get traceContextKey() {
-		return TRACE_CONTEXT_KEY;
+		return getTraceContextKey();
 	}
 	async close() {
 		return this.logger.close();
@@ -10533,6 +10597,7 @@ var import_cjs$1 = /* @__PURE__ */ require_chunk.__toESM(require_cjs());
 let KafkaTraceInterceptor = class KafkaTraceInterceptor$1 {
 	constructor(config) {
 		this.config = config;
+		this.ctx = TraceContext.instance;
 		this.config = {
 			enabled: true,
 			contextKey: "traceId",
@@ -10560,7 +10625,7 @@ let KafkaTraceInterceptor = class KafkaTraceInterceptor$1 {
 			query: {},
 			params: {}
 		}, this.config.extractor);
-		if (!traceId) traceId = getCurrentTraceId();
+		if (!traceId) traceId = this.ctx.getCurrentTraceId();
 		if (!traceId) return next.handle();
 		const kafkaContext = {
 			messageType: "kafka",
@@ -10571,7 +10636,7 @@ let KafkaTraceInterceptor = class KafkaTraceInterceptor$1 {
 			timestamp: rpcData === null || rpcData === void 0 ? void 0 : rpcData.timestamp
 		};
 		return new import_cjs$1.Observable((subscriber) => {
-			runWithTraceId(traceId, () => {
+			this.ctx.run(traceId, () => {
 				next.handle().subscribe({
 					next: (value) => subscriber.next(value),
 					error: (err) => subscriber.error(err),
@@ -10593,36 +10658,17 @@ function __decorateParam(paramIndex, decorator) {
 
 //#endregion
 //#region src/core/trace.middleware.ts
-/**
-* Default headers checked when extracting an incoming trace ID, in priority order:
-*   1. traceparent  — W3C Trace Context (OpenTelemetry standard)
-*   2. x-trace-id   — common custom header
-*   3. x-request-id — used by AWS ALB, NGINX, etc.
-*   4. x-correlation-id — used by Azure / enterprise ESBs
-*   5. trace-id     — legacy shorthand
-*
-* NOTE: for `traceparent` the format is `00-<traceId>-<spanId>-<flags>`.
-* We store the full header value as-is so downstream systems can forward it
-* unmodified. If you need only the 32-char traceId segment, configure a
-* custom extractor via TraceIdConfig.extractor.
-*/
-const DEFAULT_TRACE_HEADERS = [
-	"traceparent",
-	"x-trace-id",
-	"x-request-id",
-	"x-correlation-id",
-	"trace-id"
-];
 let TraceMiddleware = class TraceMiddleware$1 {
 	constructor(config) {
 		this.config = config;
+		this.ctx = TraceContext.instance;
 		const defaultExtractor = {
 			header: DEFAULT_TRACE_HEADERS,
 			query: ["traceId", "trace_id"]
 		};
 		this.config = {
 			enabled: true,
-			generator: generateTraceId,
+			generator: () => this.ctx.generate(),
 			contextKey: "traceId",
 			...config,
 			extractor: (config === null || config === void 0 ? void 0 : config.extractor) ? {
@@ -10630,20 +10676,19 @@ let TraceMiddleware = class TraceMiddleware$1 {
 				...config.extractor
 			} : defaultExtractor
 		};
+		this.ctx.setContextKey(this.config.contextKey ?? "traceId");
 	}
 	use(req, res, next) {
 		var _this$config;
 		if (!((_this$config = this.config) === null || _this$config === void 0 ? void 0 : _this$config.enabled)) return next();
 		let traceId;
 		if (this.config.extractor) traceId = extractTraceId(req, this.config.extractor);
-		if (!traceId) traceId = this.config.generator ? this.config.generator() : generateTraceId();
+		if (!traceId) traceId = this.config.generator ? this.config.generator() : this.ctx.generate();
 		req.traceId = traceId;
-		req.requestId = req.requestId || generateTraceId();
+		req.requestId = req.requestId || this.ctx.generate();
 		res.setHeader("X-Trace-Id", traceId);
 		res.setHeader("X-Request-Id", req.requestId);
-		runWithTraceId(traceId, () => {
-			next();
-		}, {
+		this.ctx.run(traceId, () => next(), {
 			requestId: req.requestId,
 			method: req.method,
 			url: req.url,
@@ -10664,6 +10709,7 @@ var import_cjs = /* @__PURE__ */ require_chunk.__toESM(require_cjs());
 let WebSocketTraceInterceptor = class WebSocketTraceInterceptor$1 {
 	constructor(config) {
 		this.config = config;
+		this.ctx = TraceContext.instance;
 		this.config = {
 			enabled: true,
 			contextKey: "traceId",
@@ -10695,7 +10741,7 @@ let WebSocketTraceInterceptor = class WebSocketTraceInterceptor$1 {
 				params: {}
 			}, this.config.extractor);
 		}
-		if (!traceId) traceId = getCurrentTraceId();
+		if (!traceId) traceId = this.ctx.getCurrentTraceId();
 		if (!traceId) return next.handle();
 		const wsContextData = {
 			messageType: "websocket",
@@ -10705,7 +10751,7 @@ let WebSocketTraceInterceptor = class WebSocketTraceInterceptor$1 {
 			clientAddress: client === null || client === void 0 || (_client$handshake3 = client.handshake) === null || _client$handshake3 === void 0 ? void 0 : _client$handshake3.address
 		};
 		return new import_cjs.Observable((observer) => {
-			runWithTraceId(traceId, () => {
+			this.ctx.run(traceId, () => {
 				next.handle().subscribe({
 					next: (value) => observer.next(value),
 					error: (err) => observer.error(err),
@@ -10742,7 +10788,7 @@ let LogixiaLoggerModule = class LogixiaLoggerModule$1 {
 			else if (_LogixiaLoggerModule.loggerConfig.traceId === true) traceConfig = {
 				enabled: true,
 				contextKey: "traceId",
-				generator: () => generateTraceId()
+				generator: () => TraceContext.instance.generate()
 			};
 			else traceConfig = void 0;
 			return new TraceMiddleware(traceConfig).use(req, res, next);
@@ -10944,7 +10990,7 @@ Object.defineProperty(exports, 'DEFAULT_LOG_LEVELS', {
 Object.defineProperty(exports, 'DEFAULT_TRACE_HEADERS', {
   enumerable: true,
   get: function () {
-    return DEFAULT_TRACE_HEADERS$1;
+    return DEFAULT_TRACE_HEADERS;
   }
 });
 Object.defineProperty(exports, 'KafkaTraceInterceptor', {
@@ -11007,6 +11053,12 @@ Object.defineProperty(exports, 'TRACE_CONTEXT_KEY', {
     return TRACE_CONTEXT_KEY;
   }
 });
+Object.defineProperty(exports, 'TraceContext', {
+  enumerable: true,
+  get: function () {
+    return TraceContext;
+  }
+});
 Object.defineProperty(exports, 'TraceMiddleware', {
   enumerable: true,
   get: function () {
@@ -11037,6 +11089,12 @@ Object.defineProperty(exports, '__decorateParam', {
     return __decorateParam;
   }
 });
+Object.defineProperty(exports, '_setActiveContextKey', {
+  enumerable: true,
+  get: function () {
+    return _setActiveContextKey;
+  }
+});
 Object.defineProperty(exports, 'applyRedaction', {
   enumerable: true,
   get: function () {
@@ -11115,6 +11173,12 @@ Object.defineProperty(exports, 'getOtelMetaFields', {
     return getOtelMetaFields;
   }
 });
+Object.defineProperty(exports, 'getTraceContextKey', {
+  enumerable: true,
+  get: function () {
+    return getTraceContextKey;
+  }
+});
 Object.defineProperty(exports, 'globalPluginRegistry', {
   enumerable: true,
   get: function () {
@@ -11187,4 +11251,4 @@ Object.defineProperty(exports, 'usePlugin', {
     return usePlugin;
   }
 });
-//# sourceMappingURL=logitron-logger.module-BcCtbMEe.js.map
+//# sourceMappingURL=logitron-logger.module-BI5eI4X9.js.map