logixia 1.3.1 → 1.5.0

package/dist/{logitron-logger.module-BqNKp0Fs.js → logitron-logger.module-B7CsnCYA.js}

@@ -1,5 +1,5 @@
 const require_chunk = require('./chunk-BTgCAUrQ.js');
-const require_transport_manager = require('./transport.manager-DCOm4uIQ.js');
+const require_transport_manager = require('./transport.manager-DVTM978M.js');
 let fast_json_stringify = require("fast-json-stringify");
 fast_json_stringify = require_chunk.__toESM(fast_json_stringify);
 let node_async_hooks = require("node:async_hooks");
@@ -77,6 +77,103 @@ function createFastifyContextHook(options = {}) {
 	};
 }
 
+//#endregion
+//#region 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
+* singleton is also exported for process-wide registration.
+*/
+var PluginRegistry = class {
+	constructor() {
+		this._plugins = [];
+	}
+	/**
+	* Register a plugin. Silently skips if a plugin with the same `name` is
+	* already registered on this registry.
+	*/
+	register(plugin) {
+		if (this._plugins.some((p) => p.name === plugin.name)) return;
+		this._plugins.push(plugin);
+		if (plugin.onInit) {
+			const result = plugin.onInit();
+			if (result instanceof Promise) result.catch(() => {});
+		}
+	}
+	/** Remove a previously registered plugin by name. No-op if not found. */
+	unregister(name) {
+		const idx = this._plugins.findIndex((p) => p.name === name);
+		if (idx !== -1) this._plugins.splice(idx, 1);
+	}
+	/** Returns `true` if a plugin with the given name is registered. */
+	has(name) {
+		return this._plugins.some((p) => p.name === name);
+	}
+	/** Number of currently registered plugins. */
+	get size() {
+		return this._plugins.length;
+	}
+	/**
+	* Run all `onLog` hooks in order.
+	* Returns `null` if any plugin cancels the entry; otherwise returns the
+	* (possibly transformed) entry.
+	*/
+	async runOnLog(entry) {
+		let current = entry;
+		for (const plugin of this._plugins) {
+			if (!plugin.onLog) continue;
+			current = await plugin.onLog(current);
+			if (current === null) return null;
+		}
+		return current;
+	}
+	/**
+	* Notify all `onError` hooks.
+	* Errors thrown inside hooks are swallowed to prevent error cascades.
+	*/
+	async runOnError(error, entry) {
+		for (const plugin of this._plugins) if (plugin.onError) {
+			const r = plugin.onError(error, entry);
+			if (r instanceof Promise) await r.catch(() => {});
+		}
+	}
+	/** Run all `onShutdown` hooks concurrently. Hook errors are swallowed. */
+	async runOnShutdown() {
+		await Promise.all(this._plugins.filter((p) => Boolean(p.onShutdown)).map((p) => {
+			const r = p.onShutdown();
+			return r instanceof Promise ? r.catch(() => {}) : Promise.resolve();
+		}));
+	}
+};
+/**
+* Module-level singleton registry.
+*
+* Plugins registered here are automatically copied into every **new** logger
+* instance created after the registration. Already-created loggers are not
+* retroactively affected — use `logger.use(plugin)` for per-instance control.
+*/
+const globalPluginRegistry = new PluginRegistry();
+/**
+* Register a plugin in the global registry so it applies to every future
+* logger instance.
+*
+* @example
+* ```ts
+* import { usePlugin } from 'logixia';
+*
+* usePlugin({
+*   name: 'audit-sink',
+*   onLog(entry) {
+*     if (entry.level === 'error') auditQueue.push(entry);
+*     return entry;
+*   },
+* });
+* ```
+*/
+function usePlugin(plugin) {
+	globalPluginRegistry.register(plugin);
+}
+
 //#endregion
 //#region src/types/index.ts
 const LogLevel = {
@@ -214,10 +311,187 @@ 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;
+	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
+	};
+}
+/**
+* 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
+* 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
 const DEFAULT_CENSOR = "[REDACTED]";
 /**
+* Conservative patterns: tokens and secrets that should NEVER appear in logs.
+* Applied when `autoDetect: true` or `autoDetect: 'conservative'`.
+*/
+const PII_CONSERVATIVE_PATTERNS = [
+	/eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]*/g,
+	/Bearer\s+[A-Za-z0-9._~+/-]+=*/gi,
+	/\b(?:sk|pk|api|key|secret|token)-[A-Za-z0-9_-]{16,}/gi,
+	/\bAKIA[0-9A-Z]{16}\b/g,
+	/\b[A-Za-z0-9/+]{40}\b(?=.*aws)/gi
+];
+/**
+* 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"
+];
+/**
+* Aggressive patterns: also catch personal data that could identify a person.
+* Applied when `autoDetect: 'aggressive'`.
+*/
+const PII_AGGRESSIVE_PATTERNS = [
+	/\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,
+	/\b\d{3}-?\d{2}-?\d{4}\b/g,
+	/\b(?:\d[ -]?){13,19}\b/g,
+	/\b(?:\+?1[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b/g,
+	/\b(?:\d{1,3}\.){3}\d{1,3}\b/g
+];
+const PII_AGGRESSIVE_PATHS = [
+	...PII_CONSERVATIVE_PATHS,
+	"**.email",
+	"**.emailAddress",
+	"**.email_address",
+	"**.phone",
+	"**.phoneNumber",
+	"**.phone_number",
+	"**.mobile",
+	"**.ssn",
+	"**.sin",
+	"**.dob",
+	"**.dateOfBirth",
+	"**.date_of_birth",
+	"**.creditCard",
+	"**.credit_card",
+	"**.cardNumber",
+	"**.card_number",
+	"**.cvv",
+	"**.cvc",
+	"**.ipAddress",
+	"**.ip_address"
+];
+/**
+* Build an effective config that merges `autoDetect` PII rules into the
+* explicit `paths` and `patterns` the caller provided.
+*/
+function resolveConfig(config) {
+	const { autoDetect } = config;
+	if (!autoDetect) return config;
+	const aggressive = autoDetect === "aggressive";
+	const extraPaths = aggressive ? PII_AGGRESSIVE_PATHS : PII_CONSERVATIVE_PATHS;
+	const extraPatterns = aggressive ? [...PII_CONSERVATIVE_PATTERNS, ...PII_AGGRESSIVE_PATTERNS] : PII_CONSERVATIVE_PATTERNS;
+	const { paths = [], patterns = [] } = config;
+	return {
+		...config,
+		paths: [...paths, ...extraPaths],
+		patterns: [...patterns, ...extraPatterns]
+	};
+}
+/**
 * Convert a dot-notation path pattern to a RegExp.
 * Supports `*` (one segment) and `**` (zero or more segments).
 *
@@ -289,8 +563,9 @@ function redactObject(obj, config, _currentPath = "") {
 */
 function applyRedaction(payload, config) {
 	if (!payload || !config) return payload;
-	if ((!config.paths || config.paths.length === 0) && (!config.patterns || config.patterns.length === 0)) return payload;
-	return redactObject(payload, config);
+	const resolved$1 = resolveConfig(config);
+	if ((!resolved$1.paths || resolved$1.paths.length === 0) && (!resolved$1.patterns || resolved$1.patterns.length === 0)) return payload;
+	return redactObject(payload, resolved$1);
 }
 function isPlainObject(value) {
 	return value !== null && typeof value === "object" && !Array.isArray(value) && !(value instanceof Date) && !(value instanceof Error) && !(value instanceof RegExp);
@@ -666,11 +941,17 @@ function namespacePatternToRegex(pattern) {
 	const escaped = pattern.split(".").map((s) => s === "*" ? "[^.]+" : s.replace(/[$()*+.?[\\\]^{|}]/g, "\\$&")).join("\\.");
 	return /* @__PURE__ */ new RegExp(`^${escaped}$`);
 }
+/** Max compiled patterns to keep in memory. Oldest entry is evicted when full. */
+const _NS_CACHE_MAX = 1e3;
 const _nsPatternCache = /* @__PURE__ */ new Map();
 function matchesNamespacePattern(ns, pattern) {
 	let re = _nsPatternCache.get(pattern);
 	if (!re) {
 		re = namespacePatternToRegex(pattern);
+		if (_nsPatternCache.size >= _NS_CACHE_MAX) {
+			const firstKey = _nsPatternCache.keys().next().value;
+			if (firstKey !== void 0) _nsPatternCache.delete(firstKey);
+		}
 		_nsPatternCache.set(pattern, re);
 	}
 	return re.test(ns);
@@ -701,6 +982,7 @@ var LogixiaLogger = class LogixiaLogger {
 		this._formattedLevels = /* @__PURE__ */ new Map();
 		this._formattedAppName = "";
 		this._hasRedact = false;
+		this._pluginRegistry = new PluginRegistry();
 		this.config = {
 			appName: "App",
 			environment: "development",
@@ -757,6 +1039,7 @@ var LogixiaLogger = class LogixiaLogger {
 		});
 		this.setupGracefulShutdown();
 		this.createCustomLevelMethods();
+		for (const p of globalPluginRegistry._plugins) this._pluginRegistry.register(p);
 		this._buildPerfCaches();
 	}
 	setupGracefulShutdown() {
@@ -983,6 +1266,29 @@ var LogixiaLogger = class LogixiaLogger {
 		};
 		return childLogger;
 	}
+	/**
+	* Register a plugin on this logger instance.
+	*
+	* @example
+	* ```ts
+	* logger.use({
+	*   name: 'audit',
+	*   onLog(entry) { auditQueue.push(entry); return entry; },
+	* });
+	* ```
+	*/
+	use(plugin) {
+		this._pluginRegistry.register(plugin);
+		return this;
+	}
+	/**
+	* Remove a previously registered plugin by name.
+	* No-op if the plugin is not registered on this instance.
+	*/
+	unuse(pluginName) {
+		this._pluginRegistry.unregister(pluginName);
+		return this;
+	}
 	async flush() {
 		if (this.transportManager) await this.transportManager.flush();
 	}
@@ -1005,6 +1311,7 @@ var LogixiaLogger = class LogixiaLogger {
 			await this.transportManager.close();
 		}
 		(_this$_sampler = this._sampler) === null || _this$_sampler === void 0 || _this$_sampler.destroy();
+		await this._pluginRegistry.runOnShutdown();
 		deregisterFromShutdown(this);
 	}
 	async log(level, message, data) {
@@ -1015,10 +1322,19 @@ var LogixiaLogger = class LogixiaLogger {
 			if (!this._sampler.shouldEmit(level, traceId$1)) return;
 		}
 		const alsContext = LogixiaContext.get();
-		const mergedData = alsContext && Object.keys(alsContext).length > 0 ? {
+		const otelFields = _getOtelPayloadIfEnabled();
+		const hasOtel = Object.keys(otelFields).length > 0;
+		let mergedData;
+		if (alsContext && Object.keys(alsContext).length > 0) mergedData = {
 			...alsContext,
+			...hasOtel ? otelFields : {},
+			...data
+		};
+		else if (hasOtel) mergedData = {
+			...otelFields,
 			...data
-		} : data;
+		};
+		else mergedData = data;
 		const rawPayload = this._hasContextData ? {
 			...this.contextData,
 			...mergedData
@@ -1036,8 +1352,13 @@ var LogixiaLogger = class LogixiaLogger {
 		if (this.context) entry.context = this.context;
 		if (payload !== void 0) entry.payload = payload;
 		if (traceId !== void 0) entry.traceId = traceId;
-		const formattedLog = this.formatLog(entry);
-		await this.output(formattedLog, level, entry);
+		let finalEntry = entry;
+		if (this._pluginRegistry.size > 0) {
+			finalEntry = await this._pluginRegistry.runOnLog(entry);
+			if (finalEntry === null) return;
+		}
+		const formattedLog = this.formatLog(finalEntry);
+		await this.output(formattedLog, level, finalEntry);
 	}
 	/**
 	* Hot-path level check: a single Map lookup + integer compare.
@@ -1172,45 +1493,57 @@ let LogixiaLoggerService = _LogixiaLoggerService = class LogixiaLoggerService$1
 		});
 	}
 	/**
-	* NestJS LoggerService interface implementation
+	* NestJS `LoggerService.log` — void, string context.
+	* Maps internally to `info`.
+	*
+	* @example `logger.log('User signed up', 'AuthService')`
 	*/
 	log(message, context$1) {
 		this.setContextIfProvided(context$1);
 		this.logger.info(this.formatMessage(message)).catch((err) => require_transport_manager.internalError("LogixiaLoggerService.log failed", err));
 	}
-	error(message, trace, context$1) {
+	/**
+	* Native async `info` — structured data, returns `Promise<void>`.
+	*
+	* @example `await logger.info('User signed up', { userId: 'u_abc' })`
+	*/
+	async info(message, data) {
+		return this.logger.info(message, data);
+	}
+	error(message, dataOrTrace, context$1) {
+		if (typeof dataOrTrace === "object" && dataOrTrace !== null) return message instanceof Error ? this.logger.error(message, dataOrTrace) : this.logger.error(this.formatMessage(message), dataOrTrace);
 		this.setContextIfProvided(context$1);
 		const errorData = {};
-		if (trace) errorData.stack = trace;
-		(typeof message === "object" && message instanceof Error ? this.logger.error(message, errorData) : this.logger.error(this.formatMessage(message), errorData)).catch((err) => require_transport_manager.internalError("LogixiaLoggerService.error failed", err));
+		if (typeof dataOrTrace === "string" && dataOrTrace) errorData.stack = dataOrTrace;
+		(message instanceof Error ? this.logger.error(message, errorData) : this.logger.error(this.formatMessage(message), errorData)).catch((err) => require_transport_manager.internalError("LogixiaLoggerService.error failed", err));
 	}
-	warn(message, context$1) {
-		this.setContextIfProvided(context$1);
+	warn(message, dataOrContext) {
+		if (typeof dataOrContext === "object" && dataOrContext !== null) return this.logger.warn(this.formatMessage(message), dataOrContext);
+		this.setContextIfProvided(typeof dataOrContext === "string" ? dataOrContext : void 0);
 		this.logger.warn(this.formatMessage(message)).catch((err) => require_transport_manager.internalError("LogixiaLoggerService.warn failed", err));
 	}
-	debug(message, context$1) {
-		this.setContextIfProvided(context$1);
+	debug(message, dataOrContext) {
+		if (typeof dataOrContext === "object" && dataOrContext !== null) return this.logger.debug(this.formatMessage(message), dataOrContext);
+		this.setContextIfProvided(typeof dataOrContext === "string" ? dataOrContext : void 0);
 		this.logger.debug(this.formatMessage(message)).catch((err) => require_transport_manager.internalError("LogixiaLoggerService.debug failed", err));
 	}
-	verbose(message, context$1) {
-		this.setContextIfProvided(context$1);
+	verbose(message, dataOrContext) {
+		if (typeof dataOrContext === "object" && dataOrContext !== null) return this.logger.trace(this.formatMessage(message), dataOrContext);
+		this.setContextIfProvided(typeof dataOrContext === "string" ? dataOrContext : void 0);
 		this.logger.trace(this.formatMessage(message)).catch((err) => require_transport_manager.internalError("LogixiaLoggerService.verbose failed", err));
 	}
 	/**
-	* Extended Logitron methods
+	* Native async `trace` — lowest verbosity level, structured data.
 	*/
-	async info(message, data) {
-		return this.logger.info(message, data);
-	}
 	async trace(message, data) {
 		return this.logger.trace(message, data);
 	}
+	/**
+	* Log at any named level with structured data.
+	*/
 	logLevel(level, message, data) {
 		return this.logger.logLevel(level, message, data);
 	}
-	/**
-	* Timing methods
-	*/
 	time(label) {
 		this.logger.time(label);
 	}
@@ -1220,9 +1553,6 @@ let LogixiaLoggerService = _LogixiaLoggerService = class LogixiaLoggerService$1
 	async timeAsync(label, fn) {
 		return this.logger.timeAsync(label, fn);
 	}
-	/**
-	* Context and level management
-	*/
 	setContext(context$1) {
 		this.context = context$1;
 		this.logger.setContext(context$1);
@@ -1236,30 +1566,24 @@ let LogixiaLoggerService = _LogixiaLoggerService = class LogixiaLoggerService$1
 	getLevel() {
 		return this.logger.getLevel();
 	}
-	/**
-	* Create child logger
-	*/
 	child(context$1, data) {
 		const childService = new _LogixiaLoggerService();
 		childService.logger = this.logger.child(context$1, data);
 		childService.context = context$1;
 		return childService;
 	}
-	/**
-	* Get current trace ID
-	*/
 	getCurrentTraceId() {
 		return getCurrentTraceId();
 	}
-	/**
-	* Close logger
-	*/
 	async close() {
 		return this.logger.close();
 	}
-	/**
-	* Private helper methods
-	*/
+	static create(config) {
+		return new _LogixiaLoggerService(config);
+	}
+	getLogger() {
+		return this.logger;
+	}
 	setContextIfProvided(context$1) {
 		if (context$1 && context$1 !== this.context) this.setContext(context$1);
 	}
@@ -1268,18 +1592,6 @@ let LogixiaLoggerService = _LogixiaLoggerService = class LogixiaLoggerService$1
 		if (typeof message === "object") return JSON.stringify(message);
 		return String(message);
 	}
-	/**
-	* Static factory method for easy instantiation
-	*/
-	static create(config) {
-		return new _LogixiaLoggerService(config);
-	}
-	/**
-	* Get the underlying Logitron logger instance
-	*/
-	getLogger() {
-		return this.logger;
-	}
 };
 LogixiaLoggerService = _LogixiaLoggerService = __decorate([(0, __nestjs_common.Injectable)({ scope: __nestjs_common.Scope.TRANSIENT }), __decorateMetadata("design:paramtypes", [Object])], LogixiaLoggerService);
 
@@ -10591,6 +10903,12 @@ Object.defineProperty(exports, 'LogixiaLoggerService', {
     return LogixiaLoggerService;
   }
 });
+Object.defineProperty(exports, 'PluginRegistry', {
+  enumerable: true,
+  get: function () {
+    return PluginRegistry;
+  }
+});
 Object.defineProperty(exports, 'TraceMiddleware', {
   enumerable: true,
   get: function () {
@@ -10603,6 +10921,18 @@ Object.defineProperty(exports, 'WebSocketTraceInterceptor', {
     return WebSocketTraceInterceptor;
   }
 });
+Object.defineProperty(exports, '__decorate', {
+  enumerable: true,
+  get: function () {
+    return __decorate;
+  }
+});
+Object.defineProperty(exports, '__decorateMetadata', {
+  enumerable: true,
+  get: function () {
+    return __decorateMetadata;
+  }
+});
 Object.defineProperty(exports, 'applyRedaction', {
   enumerable: true,
   get: function () {
@@ -10639,6 +10969,12 @@ Object.defineProperty(exports, 'deregisterFromShutdown', {
     return deregisterFromShutdown;
   }
 });
+Object.defineProperty(exports, 'disableOtelBridge', {
+  enumerable: true,
+  get: function () {
+    return disableOtelBridge;
+  }
+});
 Object.defineProperty(exports, 'extractTraceId', {
   enumerable: true,
   get: function () {
@@ -10657,12 +10993,36 @@ Object.defineProperty(exports, 'generateTraceId', {
     return generateTraceId;
   }
 });
+Object.defineProperty(exports, 'getActiveOtelContext', {
+  enumerable: true,
+  get: function () {
+    return getActiveOtelContext;
+  }
+});
 Object.defineProperty(exports, 'getCurrentTraceId', {
   enumerable: true,
   get: function () {
     return getCurrentTraceId;
   }
 });
+Object.defineProperty(exports, 'getOtelMetaFields', {
+  enumerable: true,
+  get: function () {
+    return getOtelMetaFields;
+  }
+});
+Object.defineProperty(exports, 'globalPluginRegistry', {
+  enumerable: true,
+  get: function () {
+    return globalPluginRegistry;
+  }
+});
+Object.defineProperty(exports, 'initOtelBridge', {
+  enumerable: true,
+  get: function () {
+    return initOtelBridge;
+  }
+});
 Object.defineProperty(exports, 'isError', {
   enumerable: true,
   get: function () {
@@ -10717,4 +11077,10 @@ Object.defineProperty(exports, 'traceStorage', {
     return traceStorage;
   }
 });
-//# sourceMappingURL=logitron-logger.module-BqNKp0Fs.js.map
+Object.defineProperty(exports, 'usePlugin', {
+  enumerable: true,
+  get: function () {
+    return usePlugin;
+  }
+});
+//# sourceMappingURL=logitron-logger.module-B7CsnCYA.js.map