logixia 2.0.0 → 2.0.6

package/dist/{builder-0gEzRopq.mjs → builder-DhNhvOkt.mjs}

@@ -1,14 +1,14 @@
-import { t as __require } from "./chunk-DLSkYcPk.mjs";
-import { n as internalLog, r as internalWarn, t as internalError } from "./internal-log-Cm8SOWSV.mjs";
-import { i as stringifyForLog } from "./safe-stringify-DJ66tW5I.mjs";
-import { i as TraceContext } from "./trace.utils-CvXgaiQT.mjs";
-import { t as LogixiaContext } from "./async-context-BzJrbfQs.mjs";
-import { t as safeToString } from "./coerce.utils-Cu6IUTgX.mjs";
-import { d as stripControlChars, t as TransportManager } from "./transport.manager-BiuCAJd2.mjs";
-import { constants } from "node:os";
+import { t as assignOwn } from "./own-property-CjFw9qwZ.mjs";
+import { o as TraceContext } from "./request-trace-BgNykH9M.mjs";
+import { t as LogixiaContext } from "./async-context-2mbUKhcl.mjs";
+import { n as internalLog, o as SENSITIVE_KEY_NAMES, r as internalWarn, t as internalError } from "./internal-log-Bg4V1cPg.mjs";
+import { n as protectSecrets } from "./secret-config-Dhb6pqTU.mjs";
+import { t as safeToString } from "./coerce.utils-B_rEudCn.mjs";
+import { i as stringifyForLog } from "./safe-stringify-B5p5ktFe.mjs";
+import { c as TransportManager, n as _getOtelPayloadIfEnabled, r as _isOtelBridgeEnabled, v as stripControlChars } from "./otel-Dt5riXuE.mjs";
 import buildFastStringify from "fast-json-stringify";
-
-//#region src/types/index.ts
+import { constants } from "node:os";
+// src/types/index.ts
 const LogLevel = {
 	ERROR: "error",
 	WARN: "warn",
@@ -33,9 +33,7 @@ const DEFAULT_LOG_COLORS = {
 	trace: "magenta",
 	verbose: "cyan"
 };
-
-//#endregion
-//#region src/core/default-config.ts
+// src/core/default-config.ts
 /**
 * Default configuration for Logixia logger
 */
@@ -79,9 +77,7 @@ const DEFAULT_CONFIG = {
 	},
 	outputs: ["console"]
 };
-
-//#endregion
-//#region src/plugin.ts
+// src/plugin.ts
 /**
 * Holds an ordered list of `LogixiaPlugin` instances and dispatches lifecycle
 * events to them. One registry is created per logger instance; a global
@@ -186,9 +182,7 @@ const globalPluginRegistry = new PluginRegistry();
 function usePlugin(plugin) {
 	globalPluginRegistry.register(plugin);
 }
-
-//#endregion
-//#region src/utils/error.utils.ts
+// src/utils/error.utils.ts
 const EXTRA_FIELDS = [
 	"code",
 	"statusCode",
@@ -230,13 +224,15 @@ function _serializeError(error, includeStack, maxDepth, excludeFields, depth, se
 	};
 	if (includeStack && error.stack) serialized.stack = error.stack;
 	const errorWithCause = error;
-	if (errorWithCause.cause !== void 0) if (errorWithCause.cause instanceof Error) serialized.cause = _serializeError(errorWithCause.cause, includeStack, maxDepth, excludeFields, depth + 1, seen);
-	else serialized.cause = serializeValue(errorWithCause.cause, maxDepth - depth - 1, seen);
+	if (errorWithCause.cause !== void 0) {
+		if (errorWithCause.cause instanceof Error) serialized.cause = _serializeError(errorWithCause.cause, includeStack, maxDepth, excludeFields, depth + 1, seen);
+		else serialized.cause = serializeValue(errorWithCause.cause, maxDepth - depth - 1, seen);
+	}
 	const aggregateError = error;
 	if (Array.isArray(aggregateError.errors)) serialized.errors = aggregateError.errors.map((e) => e instanceof Error ? _serializeError(e, includeStack, maxDepth, excludeFields, depth + 1, seen) : serializeValue(e, maxDepth - depth - 1, seen));
 	const errorRecord = error;
 	for (const field of EXTRA_FIELDS) if (!excludeFields.includes(field) && field in error && errorRecord[field] !== void 0) serialized[field] = errorRecord[field];
-	const skip = new Set([
+	const skip = /* @__PURE__ */ new Set([
 		"name",
 		"message",
 		"stack",
@@ -247,11 +243,10 @@ function _serializeError(error, includeStack, maxDepth, excludeFields, depth, se
 	]);
 	for (const key of Object.getOwnPropertyNames(error)) {
 		if (skip.has(key)) continue;
-		if (key === "__proto__" || key === "constructor" || key === "prototype") continue;
 		try {
-			serialized[key] = serializeValue(errorRecord[key], maxDepth - depth - 1, seen);
+			assignOwn(serialized, key, serializeValue(errorRecord[key], maxDepth - depth - 1, seen));
 		} catch {
-			serialized[key] = "[Unserializable]";
+			assignOwn(serialized, key, "[Unserializable]");
 		}
 	}
 	return serialized;
@@ -286,13 +281,10 @@ function serializeValue(value, remainingDepth, seen) {
 		if (seen.has(value)) return "[Circular]";
 		seen.add(value);
 		const out = {};
-		for (const [k, v] of Object.entries(value)) {
-			if (k === "__proto__" || k === "constructor" || k === "prototype") continue;
-			try {
-				out[k] = serializeValue(v, remainingDepth - 1, seen);
-			} catch {
-				out[k] = "[Unserializable]";
-			}
+		for (const [k, v] of Object.entries(value)) try {
+			assignOwn(out, k, serializeValue(v, remainingDepth - 1, seen));
+		} catch {
+			assignOwn(out, k, "[Unserializable]");
 		}
 		return out;
 	}
@@ -318,116 +310,7 @@ function normalizeError(error) {
 	}
 	return new Error(String(error));
 }
-
-//#endregion
-//#region src/utils/otel.ts
-let _otelApi;
-function tryLoadOtelApi() {
-	if (_otelApi !== void 0) return _otelApi;
-	try {
-		_otelApi = __require("@opentelemetry/api");
-		return _otelApi;
-	} catch {
-		_otelApi = null;
-		return null;
-	}
-}
-/**
-* Read the currently active OTel span context (if any) and return its fields
-* in a plain object suitable for spreading into a log entry.
-*
-* Returns `undefined` when:
-* - `@opentelemetry/api` is not installed
-* - No active span exists (root context)
-* - The span context is invalid (all-zeros)
-*/
-function getActiveOtelContext(opts = {}) {
-	const api = tryLoadOtelApi();
-	if (!api) return void 0;
-	try {
-		const ctx = api.context.active();
-		const sc = api.trace.getSpanContext(ctx);
-		if (!sc || !api.trace.isSpanContextValid(sc)) return void 0;
-		const isSampled = (sc.traceFlags & api.trace.TraceFlags.SAMPLED) === api.trace.TraceFlags.SAMPLED;
-		if (opts.sampledOnly && !isSampled) return void 0;
-		return {
-			traceId: sc.traceId,
-			spanId: sc.spanId,
-			traceFlags: sc.traceFlags,
-			isSampled
-		};
-	} catch {
-		return;
-	}
-}
-/**
-* Returns a metadata object with OTel context fields ready to merge into a log call,
-* using the configured field names.
-*
-* Returns `{}` when no active span exists (safe to spread unconditionally).
-*
-* @example
-* ```ts
-* await logger.info('Payment processed', {
-*   ...getOtelMetaFields(),
-*   orderId: 'ord_123',
-* });
-* ```
-*/
-function getOtelMetaFields(opts = {}) {
-	const { traceIdField = "traceId", spanIdField = "spanId", traceFlagsField = "traceFlags" } = opts;
-	const ctx = getActiveOtelContext(opts);
-	if (!ctx) return {};
-	return {
-		[traceIdField]: ctx.traceId,
-		[spanIdField]: ctx.spanId,
-		[traceFlagsField]: ctx.traceFlags
-	};
-}
-let _bridgeOptions = null;
-/**
-* Initialise the global OTel bridge.
-*
-* Once called, logixia's internal log pipeline checks for an active OTel span
-* on **every** log call and automatically merges the span context into the
-* entry's metadata — no per-call wiring needed.
-*
-* Call once at app startup, **after** the OTel SDK has been initialised:
-* ```ts
-* import { initOtelBridge } from 'logixia';
-* initOtelBridge();
-* ```
-*/
-function initOtelBridge(opts = {}) {
-	_bridgeOptions = opts;
-}
-/**
-* @internal
-* True when initOtelBridge() has been called. Lets the logger hot path skip the
-* `_getOtelPayloadIfEnabled()` call (and its `{}` allocation + Object.keys) on
-* every log when the bridge is off — the overwhelmingly common case.
-*/
-function _isOtelBridgeEnabled() {
-	return _bridgeOptions !== null;
-}
-/**
-* @internal
-* Used by the core logger to inject OTel context when the bridge is active.
-* Returns `{}` when the bridge is not initialised or no active span exists.
-*/
-function _getOtelPayloadIfEnabled() {
-	if (!_bridgeOptions) return {};
-	return getOtelMetaFields(_bridgeOptions);
-}
-/**
-* Disable the OTel bridge (useful for tests).
-*/
-function disableOtelBridge() {
-	_bridgeOptions = null;
-}
-
-//#endregion
-//#region src/utils/redact.utils.ts
+// src/utils/redact.utils.ts
 const DEFAULT_CENSOR = "[REDACTED]";
 /** Maximum nesting depth walked; deeper values are replaced with a marker. */
 const MAX_DEPTH = 32;
@@ -456,34 +339,7 @@ const PII_CONSERVATIVE_PATTERNS = [
 /**
 * Conservative field-name paths auto-redacted by name regardless of value.
 */
-const PII_CONSERVATIVE_PATHS = [
-	"**.password",
-	"**.passwd",
-	"**.secret",
-	"**.token",
-	"**.apiKey",
-	"**.api_key",
-	"**.accessToken",
-	"**.access_token",
-	"**.refreshToken",
-	"**.refresh_token",
-	"**.authorization",
-	"**.credentials",
-	"**.privateKey",
-	"**.private_key",
-	"**.clientSecret",
-	"**.client_secret",
-	"**.cookie",
-	"**.set-cookie",
-	"**.x-api-key",
-	"**.session",
-	"**.proxy-authorization",
-	"**.x-auth-token",
-	"**.x-access-token",
-	"**.aws_secret_access_key",
-	"**.awsSecretAccessKey",
-	"**.secretAccessKey"
-];
+const PII_CONSERVATIVE_PATHS = SENSITIVE_KEY_NAMES.map((name) => `**.${name}`);
 /**
 * Aggressive patterns: also catch personal data that could identify a person.
 * Applied when `autoDetect: 'aggressive'`.
@@ -655,10 +511,9 @@ function walkRecord(obj, state, fullPath, bare, depth) {
 	let result;
 	const entries = Object.entries(obj);
 	for (const [index, [key, value]] of entries.entries()) {
-		const forbidden = key === "__proto__" || key === "constructor" || key === "prototype";
-		const next = forbidden ? void 0 : walkValue(value, state, joinPath(fullPath, key), joinPath(bare, key), depth);
-		if ((forbidden || next !== value) && !result) result = Object.fromEntries(entries.slice(0, index));
-		if (result && !forbidden) result[key] = next;
+		const next = walkValue(value, state, joinPath(fullPath, key), joinPath(bare, key), depth);
+		if (next !== value && !result) result = Object.fromEntries(entries.slice(0, index));
+		if (result) assignOwn(result, key, next);
 	}
 	return result ?? obj;
 }
@@ -695,7 +550,7 @@ function walkToJSON(obj, state, fullPath, bare, depth) {
 function redactObject(obj, config, _currentPath = "") {
 	const result = walkRecord(obj, {
 		config,
-		ancestors: new Set([obj]),
+		ancestors: /* @__PURE__ */ new Set([obj]),
 		nodes: 0
 	}, _currentPath, _currentPath, 0);
 	return result === obj ? { ...obj } : result;
@@ -744,10 +599,8 @@ function isPlainObject(value) {
 	if (ArrayBuffer.isView(value)) return false;
 	return !OPAQUE_BUILTINS.some((ctor) => value instanceof ctor);
 }
-
-//#endregion
-//#region src/utils/sampling.utils.ts
-const ALWAYS_EMIT_LEVELS = new Set([
+// src/utils/sampling.utils.ts
+const ALWAYS_EMIT_LEVELS = /* @__PURE__ */ new Set([
 	"error",
 	"warn",
 	"fatal"
@@ -765,8 +618,8 @@ var Sampler = class {
 	constructor(config, onStats) {
 		this.traceDecisions = /* @__PURE__ */ new Map();
 		this.maxTrackedTraces = 1e5;
-		this.traceTtlMs = 5 * 6e4;
-		this.traceMaxLifetimeMs = 60 * 6e4;
+		this.traceTtlMs = 3e5;
+		this.traceMaxLifetimeMs = 36e5;
 		this._tokenBucket = 0;
 		this._lastRefillMs = Date.now();
 		this._adaptiveWindow = [];
@@ -945,9 +798,14 @@ var Sampler = class {
 		this._stats.dropped++;
 	}
 };
-
-//#endregion
-//#region src/utils/shutdown.utils.ts
+// src/utils/shutdown.utils.ts
+/**
+* Graceful shutdown utilities for Logixia
+*
+* Ensures all in-flight logs are flushed to every transport before the process
+* exits on SIGTERM / SIGINT — solving the "last N seconds of logs are lost on
+* deployment" problem reported in Pino issue #2002 and LogDNA issue #15.
+*/
 const MAX_BEFORE_EXIT_FLUSHES = 5;
 /** Module-level registry of all logger instances that have opted into graceful shutdown */
 const registry = /* @__PURE__ */ new Set();
@@ -1067,9 +925,59 @@ function resetShutdownHandlers() {
 	shutdownHandlerRegistered = false;
 	shutdownInProgress = false;
 }
-
-//#endregion
-//#region src/core/logitron-logger.ts
+const RESERVED = /* @__PURE__ */ new Set([
+	"logLevel",
+	"time",
+	"timeEnd",
+	"timeAsync",
+	"setLevel",
+	"getLevel",
+	"setNamespaceLevels",
+	"patchNamespaceLevels",
+	"getNamespaceLevels",
+	"setContext",
+	"getContext",
+	"enableField",
+	"disableField",
+	"isFieldEnabled",
+	"getFieldState",
+	"resetFieldState",
+	"enableTransportLevelPrompting",
+	"disableTransportLevelPrompting",
+	"setTransportLevels",
+	"getTransportLevels",
+	"clearTransportLevelPreferences",
+	"getAvailableTransports",
+	"child",
+	"flush",
+	"healthCheck",
+	"close",
+	"use",
+	"unuse"
+]);
+/**
+* Warn when `levels` defines a level named like a logger method (e.g. `flush`, `child`).
+* The method keeps its normal behaviour and no level shortcut is installed for that
+* name; log at it with `logger.logLevel(name, ...)` or pick a different level name.
+* Returns the clashing names.
+*/
+function warnOnReservedLevelNames(levels) {
+	if (!levels) return [];
+	const clashes = Object.keys(levels).filter((name) => RESERVED.has(name));
+	if (clashes.length > 0) internalWarn(`levelOptions.levels uses reserved logger method name(s): ${clashes.join(", ")}. No level shortcut is created for them; use logger.logLevel(name, ...) or rename the level.`);
+	return clashes;
+}
+// src/core/logitron-logger.ts
+/**
+* Core Logixia Logger implementation
+*
+* v1.1 additions:
+*  - Feature 1: Graceful shutdown / flushOnExit (auto-registered via config)
+*  - Feature 2: Built-in log redaction (path-based + regex)
+*  - Feature 3: Per-namespace log levels + LOGIXIA_LEVEL* ENV overrides
+*  - Feature 4: Cause-chain error serialization (handled in error.utils)
+*  - Feature 5: Adaptive log level based on NODE_ENV / CI detection
+*/
 const _fastStringifyEntry = buildFastStringify({
 	type: "object",
 	properties: {
@@ -1099,7 +1007,7 @@ function nowIso() {
 }
 function namespacePatternToRegex(pattern) {
 	const escaped = pattern.split(".").map((s) => s === "*" ? "[^.]+" : s.replace(/[$()*+.?[\\\]^{|}]/g, "\\$&")).join("\\.");
-	return /* @__PURE__ */ new RegExp(`^${escaped}$`);
+	return new RegExp(`^${escaped}$`);
 }
 /** Max compiled patterns to keep in memory. Oldest entry is evicted when full. */
 const _NS_CACHE_MAX = 1e3;
@@ -1141,7 +1049,7 @@ function canonicalLevel(level, known) {
 function resolveInitialLevel(config) {
 	var _config$levelOptions, _config$levelOptions2;
 	const envLevel = process.env["LOGIXIA_LEVEL"];
-	const knownLevels = new Set([...Object.values(LogLevel), ...Object.keys(((_config$levelOptions = config.levelOptions) === null || _config$levelOptions === void 0 ? void 0 : _config$levelOptions.levels) ?? {})]);
+	const knownLevels = /* @__PURE__ */ new Set([...Object.values(LogLevel), ...Object.keys(((_config$levelOptions = config.levelOptions) === null || _config$levelOptions === void 0 ? void 0 : _config$levelOptions.levels) ?? {})]);
 	if (envLevel && canonicalLevel(envLevel, knownLevels)) return envLevel;
 	if ((_config$levelOptions2 = config.levelOptions) === null || _config$levelOptions2 === void 0 ? void 0 : _config$levelOptions2.level) return config.levelOptions.level;
 	const nodeEnv = process.env["NODE_ENV"];
@@ -1151,6 +1059,19 @@ function resolveInitialLevel(config) {
 	if (process.env["CI"]) return LogLevel.INFO;
 	return LogLevel.INFO;
 }
+/**
+* The logixia logger. Create instances with {@link createLogger} so that custom
+* levels from `levelOptions.levels` also become methods.
+*
+* @example
+* ```ts
+* const logger = createLogger({ appName: 'api', environment: 'production' });
+* await logger.info('Server started', { port: 3000 });
+* const req = logger.child('RequestHandler', { requestId: 'r-1' });
+* await req.error(new Error('boom'));
+* await logger.close(); // flush buffered transports before exit
+* ```
+*/
 var LogixiaLogger = class LogixiaLogger {
 	constructor(config, context, parent) {
 		this.timers = /* @__PURE__ */ new Map();
@@ -1166,9 +1087,15 @@ var LogixiaLogger = class LogixiaLogger {
 		this._formattedLevels = /* @__PURE__ */ new Map();
 		this._formattedAppName = "";
 		this._hasRedact = false;
+		this._nsSeenVersion = 0;
 		this._parent = parent;
+		this._nsStore = parent ? parent._nsStore : {
+			levels: { ...config.namespaceLevels },
+			version: 0
+		};
+		this._nsSeenVersion = this._nsStore.version;
 		this._pluginRegistry = parent ? parent._pluginRegistry : new PluginRegistry();
-		this.config = {
+		const defaultConfig = {
 			appName: "App",
 			environment: "development",
 			traceId: true,
@@ -1196,7 +1123,10 @@ var LogixiaLogger = class LogixiaLogger {
 					[LogLevel.TRACE]: "gray",
 					[LogLevel.VERBOSE]: "cyan"
 				}
-			},
+			}
+		};
+		this.config = {
+			...defaultConfig,
 			...config
 		};
 		const resolvedLevel = resolveInitialLevel(this.config);
@@ -1214,18 +1144,19 @@ var LogixiaLogger = class LogixiaLogger {
 			timeTaken: "[time_taken_MS]"
 		};
 		this.context = context ?? "";
+		protectSecrets(this, ["config"]);
 		if (parent) {
 			this.transportManager = parent.transportManager;
 			this._sampler = parent._sampler;
 		} else if (this.config.transports) {
-			var _this$config$levelOpt;
+			var _this$config$levelOpt, _this$config$levelOpt2;
 			const transportsWithColors = { ...this.config.transports };
 			const userColors = (_this$config$levelOpt = this.config.levelOptions) === null || _this$config$levelOpt === void 0 ? void 0 : _this$config$levelOpt.colors;
 			if (userColors && transportsWithColors.console) transportsWithColors.console = {
 				...typeof transportsWithColors.console === "object" ? transportsWithColors.console : {},
 				levelColors: userColors
 			};
-			this.transportManager = new TransportManager(transportsWithColors);
+			this.transportManager = new TransportManager(transportsWithColors, (_this$config$levelOpt2 = this.config.levelOptions) === null || _this$config$levelOpt2 === void 0 ? void 0 : _this$config$levelOpt2.levels);
 		}
 		if (!parent && this.config.sampling) this._sampler = new Sampler(this.config.sampling, (stats) => {
 			process.stdout.write(JSON.stringify({
@@ -1252,8 +1183,9 @@ var LogixiaLogger = class LogixiaLogger {
 		});
 	}
 	createCustomLevelMethods() {
-		var _this$config$levelOpt2;
-		if ((_this$config$levelOpt2 = this.config.levelOptions) === null || _this$config$levelOpt2 === void 0 ? void 0 : _this$config$levelOpt2.levels) {
+		var _this$config$levelOpt3, _this$config$levelOpt4;
+		warnOnReservedLevelNames((_this$config$levelOpt3 = this.config.levelOptions) === null || _this$config$levelOpt3 === void 0 ? void 0 : _this$config$levelOpt3.levels);
+		if ((_this$config$levelOpt4 = this.config.levelOptions) === null || _this$config$levelOpt4 === void 0 ? void 0 : _this$config$levelOpt4.levels) {
 			for (const levelName of Object.keys(this.config.levelOptions.levels)) if (!this[levelName.toLowerCase()]) this[levelName.toLowerCase()] = async (message, data) => {
 				await this.logLevel(levelName.toLowerCase(), message, data);
 			};
@@ -1264,8 +1196,8 @@ var LogixiaLogger = class LogixiaLogger {
 	* Keeps the actual log() call free of allocations in the common case.
 	*/
 	_buildPerfCaches() {
-		var _this$config$levelOpt3, _this$config$format, _this$config$redact$p, _this$config$redact$p2;
-		const customLevelEntries = Object.entries(((_this$config$levelOpt3 = this.config.levelOptions) === null || _this$config$levelOpt3 === void 0 ? void 0 : _this$config$levelOpt3.levels) ?? {});
+		var _this$config$levelOpt5, _this$config$format, _this$config$redact$p, _this$config$redact$p2;
+		const customLevelEntries = Object.entries(((_this$config$levelOpt5 = this.config.levelOptions) === null || _this$config$levelOpt5 === void 0 ? void 0 : _this$config$levelOpt5.levels) ?? {});
 		this._levelValues = new Map([
 			[LogLevel.ERROR, 0],
 			[LogLevel.WARN, 1],
@@ -1279,7 +1211,7 @@ var LogixiaLogger = class LogixiaLogger {
 		this.config.levelOptions.level = this._validLevel(this.config.levelOptions.level, "levelOptions.level") ?? LogLevel.INFO;
 		const effectiveLevel = this.resolveEffectiveLevel();
 		this._minLevelValue = this._levelValues.get(effectiveLevel) ?? 2;
-		this._colorMap = new Map([
+		this._colorMap = /* @__PURE__ */ new Map([
 			["black", "\x1B[30m"],
 			["red", "\x1B[31m"],
 			["green", "\x1B[32m"],
@@ -1322,7 +1254,7 @@ var LogixiaLogger = class LogixiaLogger {
 			"green",
 			"blue"
 		];
-		const _BUILTIN_LEVELS = new Set([
+		const _BUILTIN_LEVELS = /* @__PURE__ */ new Set([
 			"error",
 			"warn",
 			"info",
@@ -1334,12 +1266,14 @@ var LogixiaLogger = class LogixiaLogger {
 		for (const [lvl] of this._levelValues) {
 			const upper = lvl.toUpperCase();
 			if (colorize && this._fieldCache.get("level") !== false) {
-				var _this$config$levelOpt4;
-				let colorName = (_this$config$levelOpt4 = this.config.levelOptions) === null || _this$config$levelOpt4 === void 0 || (_this$config$levelOpt4 = _this$config$levelOpt4.colors) === null || _this$config$levelOpt4 === void 0 ? void 0 : _this$config$levelOpt4[lvl];
-				if (!colorName) if (_BUILTIN_LEVELS.has(lvl)) colorName = "white";
-				else {
-					colorName = _AUTO_PALETTE[_paletteIdx % _AUTO_PALETTE.length];
-					_paletteIdx++;
+				var _this$config$levelOpt6;
+				let colorName = (_this$config$levelOpt6 = this.config.levelOptions) === null || _this$config$levelOpt6 === void 0 || (_this$config$levelOpt6 = _this$config$levelOpt6.colors) === null || _this$config$levelOpt6 === void 0 ? void 0 : _this$config$levelOpt6[lvl];
+				if (!colorName) {
+					if (_BUILTIN_LEVELS.has(lvl)) colorName = "white";
+					else {
+						colorName = _AUTO_PALETTE[_paletteIdx % _AUTO_PALETTE.length];
+						_paletteIdx++;
+					}
 				}
 				const code = this._colorMap.get(colorName.toLowerCase()) ?? this._colorMap.get("white");
 				const reset = this._colorMap.get("reset");
@@ -1351,6 +1285,11 @@ var LogixiaLogger = class LogixiaLogger {
 		else this._formattedAppName = colorize ? `${this._colorMap.get("gray")}${appNameRaw}${this._colorMap.get("reset")} ` : `${appNameRaw} `;
 		this._hasRedact = !!(this.config.redact && ((((_this$config$redact$p = this.config.redact.paths) === null || _this$config$redact$p === void 0 ? void 0 : _this$config$redact$p.length) ?? 0) > 0 || (((_this$config$redact$p2 = this.config.redact.patterns) === null || _this$config$redact$p2 === void 0 ? void 0 : _this$config$redact$p2.length) ?? 0) > 0 || !!this.config.redact.autoDetect));
 	}
+	/**
+	* Log at `error` level. An `Error` is logged with its message and serialized
+	* (name, message, stack) under `data.error`; a string is logged as-is.
+	* `data` is merged into the entry payload.
+	*/
 	async error(messageOrError, data) {
 		if (isError(messageOrError)) await this.log("error", messageOrError.message, {
 			...data,
@@ -1358,30 +1297,53 @@ var LogixiaLogger = class LogixiaLogger {
 		});
 		else await this.log("error", messageOrError, data);
 	}
+	/** Log `message` at `warn` level; `data` is merged into the entry payload. */
 	async warn(message, data) {
 		await this.log("warn", message, data);
 	}
+	/** Log `message` at `info` level; `data` is merged into the entry payload. */
 	async info(message, data) {
 		await this.log("info", message, data);
 	}
+	/** Log `message` at `debug` level; `data` is merged into the entry payload. */
 	async debug(message, data) {
 		await this.log("debug", message, data);
 	}
+	/** Log `message` at `trace` level; `data` is merged into the entry payload. */
 	async trace(message, data) {
 		await this.log("trace", message, data);
 	}
+	/** Log `message` at `verbose` level; `data` is merged into the entry payload. */
 	async verbose(message, data) {
 		await this.log("verbose", message, data);
 	}
+	/**
+	* Log at an arbitrary level name, including custom levels. Levels below the
+	* active threshold are dropped, as are level names that are not registered
+	* in `levelOptions.levels` (and are not built-in).
+	*/
 	async logLevel(level, message, data) {
 		await this.log(level, message, data);
 	}
+	/** Start a named timer; finish it with {@link timeEnd}. Reusing a label restarts it. */
 	time(label) {
 		this.timers.set(label, {
 			label,
 			startTime: Date.now()
 		});
 	}
+	/**
+	* Stop the timer `label`, log its duration at `info` level, and return the
+	* elapsed milliseconds. Logs a `warn` and returns `undefined` if the timer
+	* does not exist.
+	*
+	* @example
+	* ```ts
+	* logger.time('db');
+	* await query();
+	* const ms = await logger.timeEnd('db');
+	* ```
+	*/
 	async timeEnd(label) {
 		const timer = this.timers.get(label);
 		if (!timer) {
@@ -1411,6 +1373,17 @@ var LogixiaLogger = class LogixiaLogger {
 			throw error;
 		}
 	}
+	/**
+	* Change the minimum log level at runtime. The override outranks
+	* `LOGIXIA_LEVEL`, `LOGIXIA_LEVEL_<NS>` and `namespaceLevels`, and survives
+	* later changes to fields or namespace levels. Unknown level names are
+	* ignored with a warning and the current level is kept.
+	*
+	* @example
+	* ```ts
+	* logger.setLevel('debug');
+	* ```
+	*/
 	setLevel(level) {
 		const canonical = canonicalLevel(level, this._levelValues);
 		if (canonical === void 0) {
@@ -1419,12 +1392,17 @@ var LogixiaLogger = class LogixiaLogger {
 		}
 		this.config.levelOptions = this.config.levelOptions ?? {};
 		this.config.levelOptions.level = canonical;
-		this._minLevelValue = this._levelValues.get(canonical) ?? this._minLevelValue;
+		this._runtimeLevel = canonical;
 		this._buildPerfCaches();
 	}
+	/**
+	* Return the configured minimum log level, not the per-namespace effective
+	* one. Without `setLevel()` it is `LOGIXIA_LEVEL`, else `levelOptions.level`,
+	* else a `NODE_ENV` default (`debug` in development, `warn` in test), else `info`.
+	*/
 	getLevel() {
-		var _this$config$levelOpt5;
-		return ((_this$config$levelOpt5 = this.config.levelOptions) === null || _this$config$levelOpt5 === void 0 ? void 0 : _this$config$levelOpt5.level) ?? LogLevel.INFO;
+		var _this$config$levelOpt7;
+		return ((_this$config$levelOpt7 = this.config.levelOptions) === null || _this$config$levelOpt7 === void 0 ? void 0 : _this$config$levelOpt7.level) ?? LogLevel.INFO;
 	}
 	_validLevelList() {
 		return [...this._levelValues.keys()].join(", ");
@@ -1453,6 +1431,10 @@ var LogixiaLogger = class LogixiaLogger {
 	* (flip a module's verbosity live to chase a bug without raising global
 	* volume). The new map fully replaces the previous one.
 	*
+	* The map is shared by a logger and all its `child()` loggers: calling this on
+	* a child changes the whole family, and existing children pick the change up on
+	* their next log call.
+	*
 	* @example
 	* ```ts
 	* // Turn on debug for the DB layer only, live:
@@ -1460,45 +1442,57 @@ var LogixiaLogger = class LogixiaLogger {
 	* ```
 	*/
 	setNamespaceLevels(levels) {
-		this.config.namespaceLevels = { ...levels };
-		this._buildPerfCaches();
+		this._nsStore.levels = { ...levels };
+		this._nsStore.version++;
+		this._syncNamespaceLevels();
 	}
 	/** Merge entries into the existing per-namespace level map at runtime. */
 	patchNamespaceLevels(levels) {
-		this.config.namespaceLevels = {
-			...this.config.namespaceLevels,
+		this._nsStore.levels = {
+			...this._nsStore.levels,
 			...levels
 		};
-		this._buildPerfCaches();
+		this._nsStore.version++;
+		this._syncNamespaceLevels();
 	}
 	/** Return a copy of the current per-namespace level map. */
 	getNamespaceLevels() {
-		return { ...this.config.namespaceLevels };
+		return { ...this._nsStore.levels };
 	}
+	_syncNamespaceLevels() {
+		this._nsSeenVersion = this._nsStore.version;
+		this._minLevelValue = this._levelValues.get(this.resolveEffectiveLevel()) ?? 2;
+	}
+	/** Set the context label (e.g. a class or module name) attached to every subsequent entry. */
 	setContext(context) {
 		this.context = typeof context === "string" ? context : safeToString(context);
 	}
+	/** Return the current context label, or `undefined` if none is set. */
 	getContext() {
 		return this.context;
 	}
+	/** Show `fieldName` in log output, overriding the config for this logger instance. */
 	enableField(fieldName) {
 		this.fieldState.set(fieldName, true);
 		this._fieldCache.set(fieldName, true);
 		if (fieldName === "level" || fieldName === "appName") this._buildPerfCaches();
 		internalLog(`Field '${fieldName}' enabled`);
 	}
+	/** Hide `fieldName` from log output, overriding the config for this logger instance. */
 	disableField(fieldName) {
 		this.fieldState.set(fieldName, false);
 		this._fieldCache.set(fieldName, false);
 		if (fieldName === "level" || fieldName === "appName") this._buildPerfCaches();
 		internalLog(`Field '${fieldName}' disabled`);
 	}
+	/** Whether `fieldName` is currently shown: runtime override first, then config, default `true`. */
 	isFieldEnabled(fieldName) {
 		var _this$config$fields2;
 		if (this.fieldState.has(fieldName)) return this.fieldState.get(fieldName);
 		if (((_this$config$fields2 = this.config.fields) === null || _this$config$fields2 === void 0 ? void 0 : _this$config$fields2[fieldName]) !== void 0) return this.config.fields[fieldName] !== false;
 		return true;
 	}
+	/** Return the visibility (`true` = shown) of every standard log field. */
 	getFieldState() {
 		return Object.fromEntries([
 			"timestamp",
@@ -1515,6 +1509,7 @@ var LogixiaLogger = class LogixiaLogger {
 			"environment"
 		].map((f) => [f, this.isFieldEnabled(f)]));
 	}
+	/** Drop all runtime enable/disable overrides so field visibility follows the config again. */
 	resetFieldState() {
 		this.fieldState.clear();
 		internalLog("Field state reset to configuration defaults");
@@ -1529,10 +1524,12 @@ var LogixiaLogger = class LogixiaLogger {
 		if (this.transportManager) this.transportManager.disableLevelPrompting();
 		else internalWarn("Transport manager not initialized");
 	}
+	/** Restrict `transportId` to only the given `levels`. Warns if no transports are configured. */
 	setTransportLevels(transportId, levels) {
 		if (this.transportManager) this.transportManager.setTransportLevels(transportId, levels);
 		else internalWarn("Transport manager not initialized");
 	}
+	/** Return the levels `transportId` is restricted to, or `undefined` if it has none. */
 	getTransportLevels(transportId) {
 		if (this.transportManager) return this.transportManager.getTransportLevels(transportId);
 		internalWarn("Transport manager not initialized");
@@ -1541,10 +1538,23 @@ var LogixiaLogger = class LogixiaLogger {
 		if (this.transportManager) this.transportManager.clearTransportLevelPreferences();
 		else internalWarn("Transport manager not initialized");
 	}
+	/** Return the identifiers of the configured transports (empty if none). */
 	getAvailableTransports() {
 		var _this$transportManage;
 		return ((_this$transportManage = this.transportManager) === null || _this$transportManage === void 0 ? void 0 : _this$transportManage.getTransports()) ?? [];
 	}
+	/**
+	* Create a child logger with its own `context` that shares this logger's
+	* configuration and transports. `data` is merged into the bound fields
+	* inherited from this logger and added to every entry the child writes.
+	* Closing a child does not close the shared transports.
+	*
+	* @example
+	* ```ts
+	* const req = logger.child('Checkout', { requestId: 'r-42' });
+	* await req.info('started'); // entry includes requestId
+	* ```
+	*/
 	child(context, data) {
 		const childLogger = new LogixiaLogger(this.config, context, this);
 		const mergedContextData = {
@@ -1580,9 +1590,11 @@ var LogixiaLogger = class LogixiaLogger {
 		this._pluginRegistry.unregister(pluginName);
 		return this;
 	}
+	/** Flush buffered entries in all transports without closing them. */
 	async flush() {
 		if (this.transportManager) await this.transportManager.flush();
 	}
+	/** Report whether the transports are healthy; `healthy: false` if no transport manager exists. */
 	async healthCheck() {
 		if (!this.transportManager) return {
 			healthy: false,
@@ -1590,6 +1602,20 @@ var LogixiaLogger = class LogixiaLogger {
 		};
 		return this.transportManager.healthCheck();
 	}
+	/**
+	* Warn about timers that were never ended, then flush and close all transports,
+	* stop the sampler and run plugin shutdown hooks. On a child logger only the
+	* timer warnings run; the shared transports stay open.
+	*
+	* To flush on SIGTERM/SIGINT, set the `gracefulShutdown` config option rather
+	* than writing your own signal handler; do not combine it with a manual
+	* handler that calls `process.exit`, which can cut the flush short.
+	*
+	* @example
+	* ```ts
+	* await logger.close(); // e.g. at the end of a script or a test
+	* ```
+	*/
 	async close() {
 		var _this$_sampler;
 		for (const [label, timer] of this.timers) await this.warn(`Timer '${label}' was not ended properly`, {
@@ -1606,21 +1632,27 @@ var LogixiaLogger = class LogixiaLogger {
 	async log(level, message, data) {
 		if (this.config.silent) return;
 		if (!this.shouldLog(level)) return;
-		if (this._sampler) {
-			const traceId$1 = this.config.traceId ? TraceContext.instance.getCurrentTraceId() : void 0;
-			if (!this._sampler.shouldEmit(level, traceId$1)) return;
-		}
 		const alsContext = LogixiaContext.get();
+		let activeTraceId;
+		if (this.config.traceId) {
+			const ctxTraceId = alsContext === null || alsContext === void 0 ? void 0 : alsContext.traceId;
+			activeTraceId = TraceContext.instance.getCurrentTraceId() ?? (typeof ctxTraceId === "string" ? ctxTraceId : void 0);
+		}
+		if (this._sampler && !this._sampler.shouldEmit(level, activeTraceId)) return;
 		const hasAls = alsContext !== void 0 && Object.keys(alsContext).length > 0;
 		const otelFields = _isOtelBridgeEnabled() ? _getOtelPayloadIfEnabled() : void 0;
 		const hasOtel = otelFields !== void 0 && Object.keys(otelFields).length > 0;
+		const traceId = this.config.traceId ? activeTraceId ?? this.fallbackTraceId : void 0;
 		let mergedData;
-		if (hasAls) mergedData = {
-			...alsContext,
-			...hasOtel ? otelFields : {},
-			...data
-		};
-		else if (hasOtel) mergedData = {
+		if (hasAls) {
+			const als = { ...alsContext };
+			if (traceId !== void 0 && als["traceId"] === traceId) delete als["traceId"];
+			mergedData = {
+				...als,
+				...hasOtel ? otelFields : {},
+				...data
+			};
+		} else if (hasOtel) mergedData = {
 			...otelFields,
 			...data
 		};
@@ -1630,14 +1662,15 @@ var LogixiaLogger = class LogixiaLogger {
 			...mergedData
 		} : mergedData;
 		let payload;
-		if (rawPayload !== void 0 && rawPayload !== null) if (this._hasRedact) try {
-			payload = applyRedaction(rawPayload, this.config.redact) ?? rawPayload;
-		} catch (error) {
-			internalError("Redaction failed", error);
-			payload = { redaction: REDACTION_FAILED };
+		if (rawPayload !== void 0 && rawPayload !== null) {
+			if (this._hasRedact) try {
+				payload = applyRedaction(rawPayload, this.config.redact) ?? rawPayload;
+			} catch (error) {
+				internalError("Redaction failed", error);
+				payload = { redaction: REDACTION_FAILED };
+			}
+			else payload = rawPayload;
 		}
-		else payload = rawPayload;
-		const traceId = this.config.traceId ? TraceContext.instance.getCurrentTraceId() ?? this.fallbackTraceId : void 0;
 		let safeMessage = message;
 		if (this._hasRedact) try {
 			safeMessage = applyRedactionToString(message, this.config.redact);
@@ -1668,6 +1701,7 @@ var LogixiaLogger = class LogixiaLogger {
 	* The level map and threshold are pre-built in _buildPerfCaches().
 	*/
 	shouldLog(level) {
+		if (this._nsSeenVersion !== this._nsStore.version) this._syncNamespaceLevels();
 		const v = this._levelValues.get(level);
 		return v !== void 0 && v <= this._minLevelValue;
 	}
@@ -1675,19 +1709,21 @@ var LogixiaLogger = class LogixiaLogger {
 	* Feature 3: Resolve the effective log level for this logger instance.
 	*
 	* Priority:
+	*  0. A level set at runtime with `setLevel()` (explicit programmatic call, wins over all below)
 	*  1. ENV `LOGIXIA_LEVEL_<NS_UPPER>` (e.g. LOGIXIA_LEVEL_DB for ns "db" or "db.queries")
 	*  2. Matching `namespaceLevels` config entry (longer pattern = more specific, wins)
 	*  3. Global `LOGIXIA_LEVEL` ENV override
 	*  4. `levelOptions.level` (resolved via Feature 5 in constructor)
 	*/
 	resolveEffectiveLevel() {
+		if (this._runtimeLevel) return this._runtimeLevel;
 		const ns = this.context;
 		if (ns) {
 			const nsKey = ns.split(".")[0].toUpperCase();
 			const envNsLevel = this._validLevel(process.env[`LOGIXIA_LEVEL_${nsKey}`], `LOGIXIA_LEVEL_${nsKey}`);
 			if (envNsLevel) return envNsLevel;
-			const namespaceLevels = this.config.namespaceLevels;
-			if (namespaceLevels) {
+			const namespaceLevels = this._nsStore.levels;
+			if (Object.keys(namespaceLevels).length > 0) {
 				const sortedPatterns = Object.keys(namespaceLevels).sort((a, b) => b.length - a.length);
 				for (const pattern of sortedPatterns) if (matchesNamespacePattern(ns, pattern)) {
 					const nsLevel = this._validLevel(namespaceLevels[pattern], `namespaceLevels['${pattern}']`);
@@ -1754,6 +1790,22 @@ var LogixiaLogger = class LogixiaLogger {
 		(level === LogLevel.ERROR ? process.stderr : process.stdout).write(this.formatLog(entry) + "\n");
 	}
 };
+/**
+* Create a logger from `config`, with an optional default `context` label.
+*
+* Every key of `levelOptions.levels` that is not already a method becomes an
+* async method on the returned logger, typed through the config, and routes to
+* {@link LogixiaLogger.logLevel}.
+*
+* @example
+* ```ts
+* const logger = createLogger({
+*   appName: 'api',
+*   levelOptions: { level: 'info', levels: { error: 0, warn: 1, info: 2, audit: 2 } },
+* });
+* await logger.audit('user exported data', { userId: 'u1' });
+* ```
+*/
 function createLogger(config, context) {
 	var _config$levelOptions3;
 	const logger = new LogixiaLogger(config, context);
@@ -1765,9 +1817,7 @@ function createLogger(config, context) {
 	}
 	return logger;
 }
-
-//#endregion
-//#region src/exceptions/exception.ts
+// src/exceptions/exception.ts
 var LogixiaException = class extends Error {
 	constructor(options) {
 		super(options.message, { cause: options.cause });
@@ -1798,9 +1848,21 @@ var LogixiaException = class extends Error {
 function isLogixiaException(value) {
 	return value instanceof LogixiaException;
 }
-
-//#endregion
-//#region src/exceptions/builder.ts
+// src/exceptions/builder.ts
+/**
+* ErrorResponseBuilder — turns any exception into a `LogixiaErrorResponse`.
+*
+* Priority order:
+*  1. `LogixiaException`      — typed fields used directly
+*  2. NestJS `HttpException`  — duck-typed; status + message extracted
+*  3. Plain `Error` / unknown — falls back to 500 `server_error`
+*
+* The builder **always** populates `debug` when possible.
+* Your exception filter is responsible for stripping it in production:
+* ```ts
+* if (process.env.NODE_ENV === 'production') delete response.debug;
+* ```
+*/
 /**
 * Generates a trace ID via the shared {@link TraceContext} generator.
 *
@@ -1902,7 +1964,7 @@ var ErrorResponseBuilder = class {
 		const timestamp = (/* @__PURE__ */ new Date()).toISOString();
 		const durationMs = startTime !== void 0 ? Date.now() - startTime : void 0;
 		if (isLogixiaException(exception)) {
-			const debug$1 = buildDebug(exception, service, durationMs, expose);
+			const debug = buildDebug(exception, service, durationMs, expose);
 			const errorBlock = {
 				type: exception.errorType,
 				code: exception.errorCode,
@@ -1921,7 +1983,7 @@ var ErrorResponseBuilder = class {
 						path,
 						status: exception.httpStatus
 					},
-					...debug$1 !== void 0 ? { debug: debug$1 } : {}
+					...debug !== void 0 ? { debug } : {}
 				},
 				httpStatus: exception.httpStatus
 			};
@@ -1937,7 +1999,7 @@ var ErrorResponseBuilder = class {
 			} else message = exception.message;
 			const type = httpStatusToType(status);
 			const code = `HTTP_${status}`;
-			const debug$1 = buildDebug(exception, service, durationMs, expose);
+			const debug = buildDebug(exception, service, durationMs, expose);
 			return {
 				response: {
 					success: false,
@@ -1952,7 +2014,7 @@ var ErrorResponseBuilder = class {
 						path,
 						status
 					},
-					...debug$1 !== void 0 ? { debug: debug$1 } : {}
+					...debug !== void 0 ? { debug } : {}
 				},
 				httpStatus: status
 			};
@@ -1978,7 +2040,6 @@ var ErrorResponseBuilder = class {
 		};
 	}
 };
+export { DEFAULT_LOG_LEVELS as C, DEFAULT_LOG_COLORS as S, serializeError as _, isLogixiaException as a, usePlugin as b, _shutdownRegistrySize as c, registerForShutdown as d, resetShutdownHandlers as f, normalizeError as g, isError as h, LogixiaException as i, deregisterFromShutdown as l, redactObject as m, generateRequestId as n, LogixiaLogger as o, applyRedaction as p, generateTraceId as r, createLogger as s, ErrorResponseBuilder as t, flushOnExit as u, PluginRegistry as v, LogLevel as w, DEFAULT_CONFIG as x, globalPluginRegistry as y };
 
-//#endregion
-export { globalPluginRegistry as C, DEFAULT_LOG_LEVELS as D, DEFAULT_LOG_COLORS as E, LogLevel as O, PluginRegistry as S, DEFAULT_CONFIG as T, getOtelMetaFields as _, isLogixiaException as a, normalizeError as b, _shutdownRegistrySize as c, registerForShutdown as d, resetShutdownHandlers as f, getActiveOtelContext as g, disableOtelBridge as h, LogixiaException as i, deregisterFromShutdown as l, redactObject as m, generateRequestId as n, LogixiaLogger as o, applyRedaction as p, generateTraceId as r, createLogger as s, ErrorResponseBuilder as t, flushOnExit as u, initOtelBridge as v, usePlugin as w, serializeError as x, isError as y };
-//# sourceMappingURL=builder-0gEzRopq.mjs.map
+//# sourceMappingURL=builder-DhNhvOkt.mjs.map