logixia 1.12.5 → 1.13.0

package/dist/browser.js

@@ -0,0 +1,590 @@
+
+//#region src/utils/safe-stringify.ts
+/** Build a JSONPath like `$["a"][0]["b"]` for a decycle pointer. */
+function jsonPath(parts) {
+	let path = "$";
+	for (const p of parts) path += typeof p === "number" ? `[${p}]` : `[${JSON.stringify(p)}]`;
+	return path;
+}
+/**
+* Serialize any value to JSON without throwing on circular references or BigInt.
+* Circular refs become `"[Circular]"` (or `{ $ref }` pointers when `decycle`).
+*/
+function safeStringify(value, options = {}) {
+	const { indent, deterministic = false, decycle = false, bigint = "string" } = options;
+	if (decycle) return JSON.stringify(decycleValue(value, bigint), void 0, indent);
+	const seen = /* @__PURE__ */ new WeakSet();
+	const transform = (val) => {
+		if (typeof val === "bigint") return bigint === "number" ? Number(val) : val.toString();
+		if (typeof val === "function") return `[Function: ${val.name || "anonymous"}]`;
+		if (typeof val === "symbol") return val.toString();
+		if (val === null || typeof val !== "object") return val;
+		if (seen.has(val)) return "[Circular]";
+		seen.add(val);
+		let out;
+		const toJSON = val.toJSON;
+		if (Array.isArray(val)) out = val.map((item) => transform(item));
+		else if (typeof toJSON === "function") out = transform(toJSON.call(val));
+		else {
+			const rec = val;
+			const keys = deterministic ? Object.keys(rec).sort() : Object.keys(rec);
+			const obj = {};
+			for (const k of keys) {
+				if (k === "__proto__" || k === "constructor" || k === "prototype") continue;
+				obj[k] = transform(rec[k]);
+			}
+			out = obj;
+		}
+		seen.delete(val);
+		return out;
+	};
+	return JSON.stringify(transform(value), void 0, indent);
+}
+/**
+* Replace repeated object references with round-trippable `{ "$ref": "$..." }`
+* JSONPath pointers (the classic Crockford decycle). Pair with {@link retrocycle}
+* to reconstruct the original shared/circular graph.
+*/
+function decycleValue(value, bigint = "string") {
+	const paths = /* @__PURE__ */ new WeakMap();
+	const walk = (val, path) => {
+		if (typeof val === "bigint") return bigint === "number" ? Number(val) : val.toString();
+		if (val === null || typeof val !== "object") return val;
+		if (val instanceof Date) return val.toISOString();
+		const existing = paths.get(val);
+		if (existing !== void 0) return { $ref: existing };
+		paths.set(val, jsonPath(path));
+		if (Array.isArray(val)) return val.map((item, i) => walk(item, [...path, i]));
+		const rec = val;
+		const obj = {};
+		for (const k of Object.keys(rec)) {
+			if (k === "__proto__" || k === "constructor" || k === "prototype") continue;
+			obj[k] = walk(rec[k], [...path, k]);
+		}
+		return obj;
+	};
+	return walk(value, []);
+}
+/**
+* `JSON.stringify` for log output. Takes the plain fast path first and only
+* falls back to {@link safeStringify} when that throws (a cycle, a BigInt, a
+* throwing `toJSON`), so a bad payload costs nothing until it shows up.
+* Never throws: if even the safe walk fails, the value is replaced by a marker.
+*/
+function stringifyForLog(value) {
+	try {
+		return JSON.stringify(value);
+	} catch {
+		try {
+			return safeStringify(value);
+		} catch (error) {
+			const reason = error instanceof Error ? error.message : String(error);
+			return JSON.stringify(`[Unserializable: ${reason}]`);
+		}
+	}
+}
+
+//#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;
+}
+/**
+* Disable the OTel bridge (useful for tests).
+*/
+function disableOtelBridge() {
+	_bridgeOptions = null;
+}
+
+//#endregion
+//#region src/utils/internal-log.ts
+/**
+* Internal logging helpers for use within the logixia library itself.
+*
+* These functions write directly to stderr/stdout without going through
+* LogixiaLogger — this avoids circular dependencies and ensures internal
+* diagnostics still surface even when the logger is misconfigured.
+*
+* Library code must NEVER call console.log/warn/error directly. Use these
+* helpers instead so that internal output can be silenced in tests by setting
+* the LOGIXIA_SILENT_INTERNAL=1 environment variable.
+*/
+/**
+* Read the silence flag on each call rather than caching it at import time, so
+* setting LOGIXIA_SILENT_INTERNAL=1 AFTER the module is first imported (e.g. in
+* a test setup file) still takes effect — the documented test-silencing
+* behavior was previously unreliable because the value was frozen at load.
+*/
+function isSilent() {
+	return process.env.LOGIXIA_SILENT_INTERNAL === "1";
+}
+/**
+* Emit an internal warning to stderr.
+* Use when something is misconfigured but logixia can continue operating.
+*/
+function internalWarn(message) {
+	if (!isSilent()) process.stderr.write(`[logixia:warn] ${message}\n`);
+}
+
+//#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, schema) {
+	function withValidation(level, fn, message, data) {
+		if (schema && data) {
+			const warnings = schema.validate(data);
+			for (const w of warnings) internalWarn(`[logixia/schema] ${w} — level=${level} message="${message}"`);
+		}
+		return fn(message, data);
+	}
+	return {
+		raw: logger,
+		error(messageOrError, data) {
+			if (schema && data) {
+				const warnings = schema.validate(data);
+				const display = messageOrError instanceof Error ? messageOrError.message : messageOrError;
+				for (const w of warnings) internalWarn(`[logixia/schema] ${w} — level=error message="${display}"`);
+			}
+			return logger.error(messageOrError, data);
+		},
+		warn: (m, d) => withValidation("warn", logger.warn.bind(logger), m, d),
+		info: (m, d) => withValidation("info", logger.info.bind(logger), m, d),
+		debug: (m, d) => withValidation("debug", logger.debug.bind(logger), m, d),
+		verbose: (m, d) => withValidation("verbose", (logger.verbose ?? logger.debug).bind(logger), m, d),
+		trace: (m, d) => withValidation("trace", (logger.trace ?? logger.debug).bind(logger), m, d)
+	};
+}
+
+//#endregion
+//#region src/browser.ts
+const LEVEL_ORDER = {
+	verbose: 0,
+	debug: 1,
+	info: 2,
+	warn: 3,
+	error: 4,
+	critical: 5
+};
+function shouldLog(entryLevel, minLevel) {
+	return LEVEL_ORDER[entryLevel] >= LEVEL_ORDER[minLevel];
+}
+/**
+* Default browser transport — writes to the browser console using native
+* level methods so devtools can filter by severity.
+*
+* In pretty mode (default):
+*   - Groups each entry under a collapsible header with timestamp + app name
+*   - Payload displayed as an expandable object via `console.table` / `console.dir`
+*
+* In JSON mode:
+*   - Emits compact JSON strings via `console.log` / `console.error`
+*/
+var BrowserConsoleTransport = class {
+	constructor(options = {}) {
+		this.name = "browser-console";
+		this.json = options.json ?? false;
+		if (options.level !== void 0) this.level = options.level;
+	}
+	write(entry) {
+		if (this.json) this.writeJson(entry);
+		else this.writePretty(entry);
+	}
+	writeJson(entry) {
+		const line = stringifyForLog(entry);
+		switch (entry.level) {
+			case "verbose":
+			case "debug":
+				console.debug(line);
+				break;
+			case "warn":
+				console.warn(line);
+				break;
+			case "error":
+			case "critical":
+				console.error(line);
+				break;
+			default: console.log(line);
+		}
+	}
+	writePretty(entry) {
+		const { timestamp, level, appName, message, payload, context } = entry;
+		const ts = timestamp.slice(11, 23);
+		const prefix = `[${appName}]${context ? ` [${context}]` : ""}`;
+		const header = `%c${ts} %c${level.toUpperCase().padEnd(8)} %c${prefix} ${message}`;
+		const tsStyle = "color: #888; font-size: 11px;";
+		const levelStyle = this.levelStyle(level);
+		const msgStyle = "color: inherit; font-weight: normal;";
+		if (payload && Object.keys(payload).length > 0) {
+			console.groupCollapsed(header, tsStyle, levelStyle, msgStyle);
+			console.dir(payload);
+			console.groupEnd();
+		} else switch (level) {
+			case "verbose":
+			case "debug":
+				console.debug(header, tsStyle, levelStyle, msgStyle);
+				break;
+			case "warn":
+				console.warn(header, tsStyle, levelStyle, msgStyle);
+				break;
+			case "error":
+			case "critical":
+				console.error(header, tsStyle, levelStyle, msgStyle);
+				break;
+			default: console.log(header, tsStyle, levelStyle, msgStyle);
+		}
+	}
+	levelStyle(level) {
+		return {
+			verbose: "color: #aaa; font-weight: bold;",
+			debug: "color: #7ec8e3; font-weight: bold;",
+			info: "color: #4caf50; font-weight: bold;",
+			warn: "color: #ff9800; font-weight: bold;",
+			error: "color: #f44336; font-weight: bold;",
+			critical: "color: #fff; background: #f44336; font-weight: bold; padding: 1px 4px;"
+		}[level] ?? "color: inherit; font-weight: bold;";
+	}
+};
+function validateRemoteUrl(raw) {
+	if (typeof raw !== "string" || raw.length === 0) throw new TypeError("BrowserRemoteTransport: `url` must be a non-empty string");
+	if (raw.startsWith("/") && !raw.startsWith("//")) return raw;
+	let parsed;
+	try {
+		parsed = new URL(raw);
+	} catch {
+		throw new TypeError(`BrowserRemoteTransport: invalid url "${raw}"`);
+	}
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") throw new TypeError(`BrowserRemoteTransport: url scheme "${parsed.protocol}" is not allowed; use http: or https:`);
+	return raw;
+}
+/**
+* UTF-8 byte length of `s` — the measure browsers use for the keepalive
+* body-size limit. `TextEncoder` is a standard Web API (browsers, workers,
+* Node >= 11); it needs no Node import.
+*/
+function byteLength(s) {
+	return new TextEncoder().encode(s).length;
+}
+/**
+* Browser transport that batches log entries and sends them to a remote
+* HTTP endpoint via `fetch` (available in all modern browsers and Edge runtimes).
+*
+* @example
+* ```ts
+* const logger = createBrowserLogger({
+*   transports: [
+*     new BrowserRemoteTransport({
+*       url: '/api/logs',
+*       batchSize: 50,
+*       flushIntervalMs: 10_000,
+*     }),
+*   ],
+* });
+* ```
+*/
+var BrowserRemoteTransport = class {
+	constructor(options) {
+		this.name = "browser-remote";
+		this.batch = [];
+		this.timer = null;
+		this.droppedEntries = 0;
+		this.url = validateRemoteUrl(options.url);
+		this.headers = options.headers ?? {};
+		this.batchSize = options.batchSize ?? 100;
+		this.flushIntervalMs = options.flushIntervalMs ?? 5e3;
+		this.maxBufferSize = options.maxBufferSize ?? 1e3;
+		if (options.level !== void 0) this.level = options.level;
+		this.scheduleFlush();
+	}
+	/**
+	* Number of entries dropped without delivery — either because the buffer
+	* exceeded `maxBufferSize` (oldest first) or because a POST failed with a
+	* non-retryable HTTP status (a 4xx other than 429).
+	*/
+	get dropped() {
+		return this.droppedEntries;
+	}
+	write(entry) {
+		this.batch.push(entry);
+		while (this.batch.length > this.maxBufferSize) {
+			this.batch.shift();
+			this.droppedEntries += 1;
+		}
+		if (this.batch.length >= this.batchSize) this.flush();
+	}
+	async flush() {
+		while (this.batch.length > 0) {
+			const entries = this.batch.splice(0, this.batchSize);
+			const body = stringifyForLog(entries);
+			const keepalive = byteLength(body) < 6e4;
+			let res;
+			try {
+				res = await fetch(this.url, {
+					method: "POST",
+					headers: {
+						"Content-Type": "application/json",
+						...this.headers
+					},
+					body,
+					keepalive
+				});
+			} catch {
+				this.batch.unshift(...entries);
+				return;
+			}
+			if (!res.ok) {
+				if (res.status >= 500 || res.status === 429) this.batch.unshift(...entries);
+				else this.droppedEntries += entries.length;
+				return;
+			}
+		}
+	}
+	scheduleFlush() {
+		if (this.flushIntervalMs <= 0) return;
+		if (typeof globalThis !== "undefined" && typeof globalThis["setInterval"] === "function") this.timer = setInterval(() => {
+			this.flush().catch(() => {});
+		}, this.flushIntervalMs);
+	}
+	/**
+	* Stop the flush timer and flush remaining entries. Without the final flush,
+	* any buffered logs were lost on page unload / teardown — the browser
+	* equivalent of the "last N seconds of logs lost on deploy" problem.
+	*/
+	destroy() {
+		if (this.timer !== null) {
+			clearInterval(this.timer);
+			this.timer = null;
+		}
+		this.flush().catch(() => {});
+	}
+};
+/**
+* Lightweight browser-safe logger.
+*
+* Unlike the Node.js `LogixiaLogger`, this implementation has **zero**
+* Node.js dependencies. It can be bundled for any runtime.
+*/
+var BrowserLogger = class BrowserLogger {
+	constructor(config = {}) {
+		this.config = {
+			appName: config.appName ?? "App",
+			level: config.level ?? "info",
+			silent: config.silent ?? false,
+			json: config.json ?? false,
+			context: config.context
+		};
+		if (config.silent) this.transports = [];
+		else this.transports = [new BrowserConsoleTransport({ json: this.config.json }), ...config.transports ?? []];
+	}
+	verbose(message, payload) {
+		this.emit("verbose", message, payload);
+	}
+	debug(message, payload) {
+		this.emit("debug", message, payload);
+	}
+	info(message, payload) {
+		this.emit("info", message, payload);
+	}
+	log(message, payload) {
+		this.emit("info", message, payload);
+	}
+	warn(message, payload) {
+		this.emit("warn", message, payload);
+	}
+	error(message, payload) {
+		this.emit("error", message, payload);
+	}
+	critical(message, payload) {
+		this.emit("critical", message, payload);
+	}
+	/**
+	* Create a child logger that inherits config and merges extra context fields
+	* into every emitted entry.
+	*
+	* @example
+	* ```ts
+	* const childLogger = logger.child({ context: 'AuthService', userId: '42' });
+	* childLogger.info('Login succeeded'); // → { context: 'AuthService', userId: '42', ... }
+	* ```
+	*/
+	child(extraContext) {
+		return new BrowserLogger({
+			appName: this.config.appName,
+			level: this.config.level,
+			silent: this.config.silent,
+			json: this.config.json,
+			context: {
+				...this.config.context,
+				...extraContext
+			},
+			transports: this.transports.filter((t) => t.name !== "browser-console")
+		});
+	}
+	emit(level, message, payload) {
+		if (!shouldLog(level, this.config.level)) return;
+		const entry = {
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			level,
+			appName: this.config.appName,
+			message,
+			...payload || this.config.context ? { payload: {
+				...this.config.context,
+				...payload
+			} } : {}
+		};
+		for (const transport of this.transports) {
+			if (transport.level && !shouldLog(level, transport.level)) continue;
+			transport.write(entry);
+		}
+	}
+};
+/**
+* Create a browser-safe logixia logger instance.
+*
+* @example
+* ```ts
+* import { createBrowserLogger } from 'logixia/browser';
+*
+* const logger = createBrowserLogger({ appName: 'checkout', level: 'debug' });
+* logger.info('Cart updated', { itemCount: 3, total: 49.99 });
+* ```
+*/
+function createBrowserLogger(config) {
+	return new BrowserLogger(config);
+}
+/**
+* Default browser logger instance (singleton, console transport, info level).
+*
+* @example
+* ```ts
+* import { browserLogger } from 'logixia/browser';
+* browserLogger.info('Hello from browser');
+* ```
+*/
+const browserLogger = new BrowserLogger({ appName: "App" });
+
+//#endregion
+exports.BrowserConsoleTransport = BrowserConsoleTransport;
+exports.BrowserLogger = BrowserLogger;
+exports.BrowserRemoteTransport = BrowserRemoteTransport;
+exports.browserLogger = browserLogger;
+exports.createBrowserLogger = createBrowserLogger;
+exports.createTypedLogger = createTypedLogger;
+exports.defineLogSchema = defineLogSchema;
+exports.disableOtelBridge = disableOtelBridge;
+exports.getActiveOtelContext = getActiveOtelContext;
+exports.getOtelMetaFields = getOtelMetaFields;
+exports.initOtelBridge = initOtelBridge;
+//# sourceMappingURL=browser.js.map