logixia 1.7.0 → 1.7.2

package/dist/{logitron-logger.module-DnRTDcoz.mjs → logitron-logger.module-BvWgddzf.mjs}

@@ -807,51 +807,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 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 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) {
@@ -891,7 +956,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",
@@ -903,7 +968,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 = {
@@ -913,15 +978,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() });
 	};
 }
 
@@ -980,7 +1044,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();
@@ -1366,7 +1430,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();
@@ -1389,7 +1453,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,
@@ -1640,11 +1704,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();
@@ -10528,6 +10592,7 @@ var import_cjs$1 = /* @__PURE__ */ __toESM(require_cjs());
 let KafkaTraceInterceptor = class KafkaTraceInterceptor$1 {
 	constructor(config) {
 		this.config = config;
+		this.ctx = TraceContext.instance;
 		this.config = {
 			enabled: true,
 			contextKey: "traceId",
@@ -10555,7 +10620,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",
@@ -10566,7 +10631,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),
@@ -10588,36 +10653,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) ? {
@@ -10625,20 +10671,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,
@@ -10659,6 +10704,7 @@ var import_cjs = /* @__PURE__ */ __toESM(require_cjs());
 let WebSocketTraceInterceptor = class WebSocketTraceInterceptor$1 {
 	constructor(config) {
 		this.config = config;
+		this.ctx = TraceContext.instance;
 		this.config = {
 			enabled: true,
 			contextKey: "traceId",
@@ -10690,7 +10736,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",
@@ -10700,7 +10746,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),
@@ -10737,7 +10783,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);
@@ -10924,5 +10970,5 @@ let LogixiaLoggerModule = class LogixiaLoggerModule$1 {
 LogixiaLoggerModule = _LogixiaLoggerModule = __decorate([Module({})], LogixiaLoggerModule);
 
 //#endregion
-export { getOtelMetaFields as A, usePlugin as B, flushOnExit as C, redactObject as D, applyRedaction as E, DEFAULT_LOG_COLORS as F, createExpressContextMiddleware as H, DEFAULT_LOG_LEVELS as I, LogLevel as L, isError as M, normalizeError as N, disableOtelBridge as O, serializeError as P, PluginRegistry as R, deregisterFromShutdown as S, resetShutdownHandlers as T, createFastifyContextHook as U, LogixiaContext as V, generateTraceId as _, TraceMiddleware as a, setTraceId as b, LogixiaLoggerService as c, LogixiaLogger as d, createLogger as f, extractTraceId as g, createTraceMiddleware as h, WebSocketTraceInterceptor as i, initOtelBridge as j, getActiveOtelContext as k, __decorate as l, TRACE_CONTEXT_KEY as m, LOGIXIA_LOGGER_PREFIX as n, __decorateParam as o, DEFAULT_TRACE_HEADERS$1 as p, LogixiaLoggerModule as r, KafkaTraceInterceptor as s, LOGIXIA_LOGGER_CONFIG as t, __decorateMetadata as u, getCurrentTraceId as v, registerForShutdown as w, traceStorage as x, runWithTraceId as y, globalPluginRegistry as z };
-//# sourceMappingURL=logitron-logger.module-DnRTDcoz.mjs.map
+export { redactObject as A, LogLevel as B, setTraceId as C, registerForShutdown as D, flushOnExit as E, isError as F, createExpressContextMiddleware as G, globalPluginRegistry as H, normalizeError as I, createFastifyContextHook as K, serializeError as L, getActiveOtelContext as M, getOtelMetaFields as N, resetShutdownHandlers as O, initOtelBridge as P, DEFAULT_LOG_COLORS as R, runWithTraceId as S, deregisterFromShutdown as T, usePlugin as U, PluginRegistry as V, LogixiaContext as W, createTraceMiddleware as _, TraceMiddleware as a, getCurrentTraceId as b, LogixiaLoggerService as c, LogixiaLogger as d, createLogger as f, _setActiveContextKey as g, TraceContext as h, WebSocketTraceInterceptor as i, disableOtelBridge as j, applyRedaction as k, __decorate as l, TRACE_CONTEXT_KEY as m, LOGIXIA_LOGGER_PREFIX as n, __decorateParam as o, DEFAULT_TRACE_HEADERS as p, LogixiaLoggerModule as r, KafkaTraceInterceptor as s, LOGIXIA_LOGGER_CONFIG as t, __decorateMetadata as u, extractTraceId as v, traceStorage as w, getTraceContextKey as x, generateTraceId as y, DEFAULT_LOG_LEVELS as z };
+//# sourceMappingURL=logitron-logger.module-BvWgddzf.mjs.map