logixia 1.3.0 → 1.4.0

package/dist/index.js

@@ -1,7 +1,119 @@
-const require_logitron_logger_module = require('./logitron-logger.module-BqNKp0Fs.js');
-require('./transport.manager-DCOm4uIQ.js');
+const require_chunk = require('./chunk-BTgCAUrQ.js');
+const require_logitron_logger_module = require('./logitron-logger.module-CCnX7GwK.js');
+const require_transport_manager = require('./transport.manager-DVTM978M.js');
 require('./search-DeZHhWxB.js');
+let __nestjs_common = require("@nestjs/common");
+__nestjs_common = require_chunk.__toESM(__nestjs_common);
 
+//#region \0@oxc-project+runtime@0.95.0/helpers/decorateParam.js
+function __decorateParam(paramIndex, decorator) {
+	return function(target, key) {
+		decorator(target, key, paramIndex);
+	};
+}
+
+//#endregion
+//#region src/core/nestjs-extras.ts
+/**
+* Inject the Logixia logger registered in the current NestJS DI container.
+*
+* Equivalent to `@Inject(LOGIXIA_LOGGER_TOKEN)` but without needing to import
+* the internal token constant yourself.
+*
+* @example
+* ```ts
+* constructor(@InjectLogger() private readonly logger: LogixiaLoggerService) {}
+* ```
+*/
+const InjectLogger = () => (0, __nestjs_common.Inject)(`${require_logitron_logger_module.LOGIXIA_LOGGER_PREFIX}SERVICE`);
+/**
+* Method decorator that auto-logs entry, exit, duration, and errors.
+*
+* Works on both async and sync methods. Attaches to the logger found on the
+* class instance via a `logger` property (the conventional NestJS name).
+*
+* @example
+* ```ts
+* @LogMethod({ level: 'info', logArgs: true })
+* async processPayment(orderId: string): Promise<void> { … }
+* ```
+*/
+function LogMethod(options = {}) {
+	const { level = "debug", logArgs = true, logResult = false, logErrors = true } = options;
+	return function(target, propertyKey, descriptor) {
+		var _constructor;
+		const originalMethod = descriptor.value;
+		if (typeof originalMethod !== "function") return descriptor;
+		const methodName = String(propertyKey);
+		const className = ((_constructor = target.constructor) === null || _constructor === void 0 ? void 0 : _constructor.name) ?? "Unknown";
+		const label = options.label ?? `${className}.${methodName}`;
+		descriptor.value = async function(...args) {
+			const logger$1 = this.logger;
+			const start = Date.now();
+			const entry = { method: label };
+			if (logArgs && args.length > 0) entry["args"] = args;
+			if (logger$1) {
+				const logFn = logger$1[level] ?? logger$1.debug.bind(logger$1);
+				if (typeof logFn === "function") await logFn(`→ ${label}`, entry).catch(() => void 0);
+			}
+			try {
+				const result = await originalMethod.apply(this, args);
+				const exit = {
+					method: label,
+					durationMs: Date.now() - start
+				};
+				if (logResult) exit["result"] = result;
+				if (logger$1) {
+					const logFn = logger$1[level] ?? logger$1.debug.bind(logger$1);
+					if (typeof logFn === "function") await logFn(`← ${label}`, exit).catch(() => void 0);
+				}
+				return result;
+			} catch (error) {
+				if (logger$1 && logErrors) {
+					const err = error instanceof Error ? error : new Error(String(error));
+					logger$1.error(err, `${label} durationMs=${Date.now() - start}`);
+				}
+				throw error;
+			}
+		};
+		return descriptor;
+	};
+}
+let LogixiaExceptionFilter = class LogixiaExceptionFilter$1 {
+	constructor(logger$1) {
+		this.logger = logger$1;
+	}
+	catch(exception, host) {
+		const ctx = host.switchToHttp();
+		const response = ctx.getResponse();
+		const request = ctx.getRequest();
+		const isHttp = exception instanceof __nestjs_common.HttpException;
+		const status = isHttp ? exception.getStatus() : 500;
+		let message;
+		if (isHttp) message = exception.message;
+		else if (exception instanceof Error) message = exception.message;
+		else message = "Internal server error";
+		const contextStr = `method=${String(request.method ?? "")} url=${String(request.url ?? "")} status=${status}`;
+		if (this.logger) if (status >= 500) {
+			const err = exception instanceof Error ? exception : new Error(String(exception));
+			this.logger.error(err, void 0, contextStr);
+		} else this.logger.warn(`[${status}] ${message}`, contextStr);
+		response.status(status).json({
+			statusCode: status,
+			message,
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			path: request.url
+		});
+	}
+};
+LogixiaExceptionFilter = require_logitron_logger_module.__decorate([
+	(0, __nestjs_common.Catch)(),
+	__decorateParam(0, (0, __nestjs_common.Optional)()),
+	__decorateParam(0, (0, __nestjs_common.Inject)(`${require_logitron_logger_module.LOGIXIA_LOGGER_PREFIX}SERVICE`)),
+	require_logitron_logger_module.__decorateMetadata("design:paramtypes", [Object])
+], LogixiaExceptionFilter);
+
+//#endregion
 //#region src/formatters/json.formatter.ts
 var JsonFormatter = class {
 	constructor(options = {}) {
@@ -165,6 +277,309 @@ var TextFormatter = class TextFormatter {
 	}
 };
 
+//#endregion
+//#region src/utils/typed-logger.ts
+/**
+* Define a typed schema for a category of log entries.
+*
+* Call this once at module initialisation and pass it to `createTypedLogger`.
+* In development, every log call is validated against the schema.
+*/
+function defineLogSchema(fields) {
+	return {
+		fields,
+		validate(payload) {
+			if (process.env["NODE_ENV"] === "production") return [];
+			const warnings = [];
+			for (const [key, def] of Object.entries(fields)) {
+				const value = payload[key];
+				if (def.required && (value === void 0 || value === null)) {
+					warnings.push(`Required field "${key}" is missing`);
+					continue;
+				}
+				if (value !== void 0 && value !== null) {
+					const actualType = Array.isArray(value) ? "array" : typeof value;
+					if (actualType !== def.type) warnings.push(`Field "${key}" expected type "${def.type}" but got "${actualType}"`);
+					if (def.validate) {
+						const msg = def.validate(value);
+						if (msg) warnings.push(`Field "${key}": ${msg}`);
+					}
+				}
+			}
+			return warnings;
+		}
+	};
+}
+/**
+* Wrap any logixia logger with a type-safe field interface.
+*
+* @param logger  Any object that implements `IBaseLogger` (e.g. the result of `createLogger()`)
+* @param schema  Optional schema for dev-time validation. Created with `defineLogSchema()`.
+*/
+function createTypedLogger(logger$1, schema) {
+	function withValidation(level, fn, message, data) {
+		if (schema && data) {
+			const warnings = schema.validate(data);
+			for (const w of warnings) require_transport_manager.internalWarn(`[logixia/schema] ${w} — level=${level} message="${message}"`);
+		}
+		return fn(message, data);
+	}
+	return {
+		raw: logger$1,
+		error(messageOrError, data) {
+			return logger$1.error(messageOrError, data);
+		},
+		warn: (m, d) => withValidation("warn", logger$1.warn.bind(logger$1), m, d),
+		info: (m, d) => withValidation("info", logger$1.info.bind(logger$1), m, d),
+		debug: (m, d) => withValidation("debug", logger$1.debug.bind(logger$1), m, d),
+		verbose: (m, d) => withValidation("verbose", (logger$1.verbose ?? logger$1.debug).bind(logger$1), m, d),
+		trace: (m, d) => withValidation("trace", (logger$1.trace ?? logger$1.debug).bind(logger$1), m, d)
+	};
+}
+
+//#endregion
+//#region src/metrics.ts
+const DEFAULT_BUCKETS = [
+	1,
+	5,
+	10,
+	25,
+	50,
+	100,
+	250,
+	500,
+	1e3,
+	2500,
+	5e3,
+	1e4
+];
+function buildLabelKey(config, entry) {
+	const labelNames = config.labels ?? [];
+	if (labelNames.length === 0) return "{}";
+	const pairs = {};
+	const payload = entry.payload ?? {};
+	for (const name of labelNames) {
+		const raw = name === "level" ? entry.level : payload[name];
+		pairs[name] = raw !== void 0 && raw !== null ? String(raw) : "";
+	}
+	return JSON.stringify(pairs);
+}
+function renderLabels(labelKey) {
+	if (labelKey === "{}") return "";
+	const obj = JSON.parse(labelKey);
+	return `{${Object.entries(obj).map(([k, v]) => `${k}="${escapeLabel(v)}"`).join(",")}}`;
+}
+function escapeLabel(value) {
+	return value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\n/g, "\\n");
+}
+/**
+* A logixia plugin that extracts Prometheus-compatible metrics from log entries.
+*
+* Implements `LogixiaPlugin` — pass directly to `logger.use()`:
+* ```ts
+* const metrics = new MetricsPlugin({ ... });
+* logger.use(metrics);
+* ```
+*
+* Or use the `createMetricsPlugin()` factory (preferred):
+* ```ts
+* const metrics = createMetricsPlugin({ ... });
+* logger.use(metrics);
+* ```
+*/
+var MetricsPlugin = class {
+	constructor(map) {
+		this.name = "logixia-metrics";
+		this.metricState = /* @__PURE__ */ new Map();
+		this.map = map;
+		this.initAllState();
+	}
+	onInit() {}
+	onLog(entry) {
+		const payload = entry.payload ?? {};
+		for (const [rawName, config] of Object.entries(this.map)) {
+			const state = this.metricState.get(rawName);
+			if (!state) continue;
+			const labelKey = buildLabelKey(config, entry);
+			if (config.type === "counter" && state.type === "counter") {
+				if (config.levelFilter && entry.level !== config.levelFilter) continue;
+				if (config.field !== void 0 && payload[config.field] !== config.value) continue;
+				state.values.set(labelKey, (state.values.get(labelKey) ?? 0) + 1);
+			} else if (config.type === "histogram" && state.type === "histogram") {
+				const raw = payload[config.field];
+				if (raw === void 0 || raw === null) continue;
+				const val = Number(raw);
+				if (Number.isNaN(val)) continue;
+				if (!state.counts.has(labelKey)) {
+					state.counts.set(labelKey, Array.from({ length: state.buckets.length + 1 }).fill(0));
+					state.sums.set(labelKey, 0);
+					state.observations.set(labelKey, 0);
+				}
+				const bucketArr = state.counts.get(labelKey);
+				for (let i = 0; i < state.buckets.length; i++) if (val <= state.buckets[i]) bucketArr[i]++;
+				bucketArr[state.buckets.length]++;
+				state.sums.set(labelKey, (state.sums.get(labelKey) ?? 0) + val);
+				state.observations.set(labelKey, (state.observations.get(labelKey) ?? 0) + 1);
+			} else if (config.type === "gauge" && state.type === "gauge") {
+				const raw = payload[config.field];
+				if (raw === void 0 || raw === null) continue;
+				const val = Number(raw);
+				if (Number.isNaN(val)) continue;
+				state.values.set(labelKey, val);
+			}
+		}
+		return entry;
+	}
+	/**
+	* Render all registered metrics in the Prometheus text exposition format
+	* (version 0.0.4).
+	*
+	* All metric names are prefixed with `logixia_`.
+	*
+	* @example
+	* ```
+	* # HELP logixia_error_count Total error log entries
+	* # TYPE logixia_error_count counter
+	* logixia_error_count{context="OrderService"} 7
+	* ```
+	*/
+	render() {
+		const lines = [];
+		for (const [rawName, config] of Object.entries(this.map)) {
+			const metricName = `logixia_${rawName}`;
+			const state = this.metricState.get(rawName);
+			if (!state) continue;
+			const helpText = config.help ?? rawName.replace(/_/g, " ");
+			lines.push(`# HELP ${metricName} ${helpText}`);
+			lines.push(`# TYPE ${metricName} ${config.type}`);
+			if (state.type === "counter") if (state.values.size === 0) lines.push(`${metricName} 0`);
+			else for (const [labelKey, count] of state.values) lines.push(`${metricName}${renderLabels(labelKey)} ${count}`);
+			else if (state.type === "histogram") for (const [labelKey, bucketCounts] of state.counts) {
+				const labelSuffix = renderLabels(labelKey);
+				const baseObj = labelKey === "{}" ? {} : JSON.parse(labelKey);
+				for (let i = 0; i < state.buckets.length; i++) {
+					const leKey = JSON.stringify({
+						...baseObj,
+						le: String(state.buckets[i])
+					});
+					lines.push(`${metricName}_bucket${renderLabels(leKey)} ${bucketCounts[i] ?? 0}`);
+				}
+				const infKey = JSON.stringify({
+					...baseObj,
+					le: "+Inf"
+				});
+				lines.push(`${metricName}_bucket${renderLabels(infKey)} ${bucketCounts[state.buckets.length] ?? 0}`);
+				lines.push(`${metricName}_sum${labelSuffix} ${state.sums.get(labelKey) ?? 0}`);
+				lines.push(`${metricName}_count${labelSuffix} ${state.observations.get(labelKey) ?? 0}`);
+			}
+			else if (state.type === "gauge") if (state.values.size === 0) lines.push(`${metricName} 0`);
+			else for (const [labelKey, val] of state.values) lines.push(`${metricName}${renderLabels(labelKey)} ${val}`);
+		}
+		return `${lines.join("\n")}\n`;
+	}
+	/**
+	* Reset all metric counters and observations back to zero.
+	* Useful between test runs or on a scheduled reset interval.
+	*/
+	reset() {
+		this.metricState.clear();
+		this.initAllState();
+	}
+	/**
+	* Express route handler — call `app.get('/metrics', metrics.expressHandler())`.
+	*
+	* @example
+	* ```ts
+	* import express from 'express';
+	* const app = express();
+	* app.get('/metrics', metrics.expressHandler());
+	* ```
+	*/
+	expressHandler() {
+		return (_req, res) => {
+			res.set("Content-Type", "text/plain; version=0.0.4; charset=utf-8");
+			res.end(this.render());
+		};
+	}
+	/**
+	* Raw Node.js `http` server handler.
+	* Responds to `GET /metrics` with the Prometheus text payload.
+	*
+	* @example Start a dedicated metrics server on the standard port:
+	* ```ts
+	* import http from 'node:http';
+	* const server = http.createServer(metrics.httpHandler());
+	* server.listen(9464); // Prometheus default port for custom exporters
+	* ```
+	*/
+	httpHandler() {
+		return (req, res) => {
+			if (!(req.url === "/metrics" || req.url === "/metrics/")) {
+				res.writeHead(404).end("Not found");
+				return;
+			}
+			const body = this.render();
+			res.writeHead(200, {
+				"Content-Type": "text/plain; version=0.0.4; charset=utf-8",
+				"Content-Length": Buffer.byteLength(body)
+			});
+			res.end(body);
+		};
+	}
+	initAllState() {
+		for (const [rawName, config] of Object.entries(this.map)) this.initSingleState(rawName, config);
+	}
+	initSingleState(rawName, config) {
+		if (config.type === "counter") this.metricState.set(rawName, {
+			type: "counter",
+			values: /* @__PURE__ */ new Map()
+		});
+		else if (config.type === "histogram") {
+			const buckets = [...config.buckets ?? DEFAULT_BUCKETS].sort((a, b) => a - b);
+			this.metricState.set(rawName, {
+				type: "histogram",
+				buckets,
+				counts: /* @__PURE__ */ new Map(),
+				sums: /* @__PURE__ */ new Map(),
+				observations: /* @__PURE__ */ new Map()
+			});
+		} else this.metricState.set(rawName, {
+			type: "gauge",
+			values: /* @__PURE__ */ new Map()
+		});
+	}
+};
+/**
+* Create a `MetricsPlugin` from a metrics map and return it ready for
+* `logger.use()`.
+*
+* @example
+* ```ts
+* import { createMetricsPlugin } from 'logixia';
+*
+* const metrics = createMetricsPlugin({
+*   http_request_duration: {
+*     type: 'histogram',
+*     field: 'duration',
+*     labels: ['method', 'statusCode'],
+*     help: 'HTTP request duration in milliseconds',
+*   },
+*   error_count: {
+*     type: 'counter',
+*     levelFilter: 'error',
+*     labels: ['context'],
+*     help: 'Total error log entries',
+*   },
+* });
+*
+* logger.use(metrics);
+* app.get('/metrics', metrics.expressHandler());
+* ```
+*/
+function createMetricsPlugin(map) {
+	return new MetricsPlugin(map);
+}
+
 //#endregion
 //#region src/index.ts
 /**
@@ -240,6 +655,7 @@ exports.DEFAULT_CONFIG = DEFAULT_CONFIG;
 exports.DEFAULT_LOG_COLORS = require_logitron_logger_module.DEFAULT_LOG_COLORS;
 exports.DEFAULT_LOG_LEVELS = require_logitron_logger_module.DEFAULT_LOG_LEVELS;
 exports.DEFAULT_TRACE_HEADERS = require_logitron_logger_module.DEFAULT_TRACE_HEADERS;
+exports.InjectLogger = InjectLogger;
 exports.JsonFormatter = JsonFormatter;
 Object.defineProperty(exports, 'KafkaTraceInterceptor', {
   enumerable: true,
@@ -250,7 +666,14 @@ Object.defineProperty(exports, 'KafkaTraceInterceptor', {
 exports.LOGIXIA_LOGGER_CONFIG = require_logitron_logger_module.LOGIXIA_LOGGER_CONFIG;
 exports.LOGIXIA_LOGGER_PREFIX = require_logitron_logger_module.LOGIXIA_LOGGER_PREFIX;
 exports.LogLevel = require_logitron_logger_module.LogLevel;
+exports.LogMethod = LogMethod;
 exports.LogixiaContext = require_logitron_logger_module.LogixiaContext;
+Object.defineProperty(exports, 'LogixiaExceptionFilter', {
+  enumerable: true,
+  get: function () {
+    return LogixiaExceptionFilter;
+  }
+});
 exports.LogixiaLogger = require_logitron_logger_module.LogixiaLogger;
 Object.defineProperty(exports, 'LogixiaLoggerModule', {
   enumerable: true,
@@ -264,6 +687,8 @@ Object.defineProperty(exports, 'LogixiaLoggerService', {
     return require_logitron_logger_module.LogixiaLoggerService;
   }
 });
+exports.MetricsPlugin = MetricsPlugin;
+exports.PluginRegistry = require_logitron_logger_module.PluginRegistry;
 exports.TextFormatter = TextFormatter;
 Object.defineProperty(exports, 'WebSocketTraceInterceptor', {
   enumerable: true,
@@ -276,12 +701,20 @@ exports.createExpressContextMiddleware = require_logitron_logger_module.createEx
 exports.createFastifyContextHook = require_logitron_logger_module.createFastifyContextHook;
 exports.createLogger = createLogger;
 exports.createLoggerService = createLoggerService;
+exports.createMetricsPlugin = createMetricsPlugin;
 exports.createTraceMiddleware = require_logitron_logger_module.createTraceMiddleware;
+exports.createTypedLogger = createTypedLogger;
+exports.defineLogSchema = defineLogSchema;
 exports.deregisterFromShutdown = require_logitron_logger_module.deregisterFromShutdown;
+exports.disableOtelBridge = require_logitron_logger_module.disableOtelBridge;
 exports.extractTraceId = require_logitron_logger_module.extractTraceId;
 exports.flushOnExit = require_logitron_logger_module.flushOnExit;
 exports.generateTraceId = require_logitron_logger_module.generateTraceId;
+exports.getActiveOtelContext = require_logitron_logger_module.getActiveOtelContext;
 exports.getCurrentTraceId = require_logitron_logger_module.getCurrentTraceId;
+exports.getOtelMetaFields = require_logitron_logger_module.getOtelMetaFields;
+exports.globalPluginRegistry = require_logitron_logger_module.globalPluginRegistry;
+exports.initOtelBridge = require_logitron_logger_module.initOtelBridge;
 exports.isError = require_logitron_logger_module.isError;
 exports.logger = logger;
 exports.normalizeError = require_logitron_logger_module.normalizeError;
@@ -292,4 +725,5 @@ exports.runWithTraceId = require_logitron_logger_module.runWithTraceId;
 exports.serializeError = require_logitron_logger_module.serializeError;
 exports.setTraceId = require_logitron_logger_module.setTraceId;
 exports.traceStorage = require_logitron_logger_module.traceStorage;
+exports.usePlugin = require_logitron_logger_module.usePlugin;
 //# sourceMappingURL=index.js.map