@prosopo/logger 2.1.1 → 2.1.3

package/src/logger.ts

@@ -1,471 +0,0 @@
-// Copyright 2021-2026 Prosopo (UK) Ltd.
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-import { stringifyBigInts } from "@prosopo/util";
-
-export type LogObject = object;
-export type LogRecord = {
-	err?: unknown;
-	data?: LogObject;
-	msg?: string;
-};
-export type LogRecordFn = () => LogRecord;
-
-export type Logger = {
-	setLogLevel(level: LogLevel): void;
-	getLogLevel(): LogLevel;
-	getScope(): string;
-	info(fn: LogRecordFn): void;
-	debug(fn: LogRecordFn): void;
-	trace(fn: LogRecordFn): void;
-	warn(fn: LogRecordFn): void;
-	error(fn: LogRecordFn): void;
-	fatal(fn: LogRecordFn): void;
-	log(level: LogLevel, fn: LogRecordFn): void;
-	/**
-	 * Creates a child logger with merged default data and an optional subscope appended to the
-	 * current scope (e.g. parent "database" + subscope "queries" → "database:queries").
-	 * The child's configured level is snapshotted at creation by resolving PROSOPO_LOG_LEVEL
-	 * directives for the new scope, falling back to the parent's level when no directive matches.
-	 * At emit time `print()` re-resolves directives for the scope, using the child's own configured
-	 * level (this snapshot) as the fallback — so later directive changes are honoured, but a direct
-	 * `setLogLevel()` on the child overrides the snapshot.
-	 */
-	with(obj: LogObject, subscope?: string): Logger;
-	getPretty(): boolean;
-	setPretty(pretty: boolean): void;
-	getPrintStack(): boolean;
-	setPrintStack(printStack: boolean): void;
-	getFormat(): Format;
-	setFormat(format: Format): void;
-};
-
-// Level string constants are internal to this module; consumers use the
-// `LogLevel` enum/type or the string literals it parses.
-const InfoLevel = "info";
-const DebugLevel = "debug";
-const TraceLevel = "trace";
-const WarnLevel = "warn";
-const ErrorLevel = "error";
-const FatalLevel = "fatal";
-
-const LogLevels = [
-	InfoLevel,
-	DebugLevel,
-	TraceLevel,
-	WarnLevel,
-	ErrorLevel,
-	FatalLevel,
-] as const;
-
-export type LogLevel = (typeof LogLevels)[number];
-
-/**
- * Shaped like the zod enum it replaced, because `LogLevel.enum.info` and
- * `LogLevel.options` are what callers across the repo already write. zod itself
- * is 14KB gzipped and this module is on the widget's critical path, which is a
- * poor trade for validating six strings.
- */
-export const LogLevel = {
-	enum: {
-		[InfoLevel]: InfoLevel,
-		[DebugLevel]: DebugLevel,
-		[TraceLevel]: TraceLevel,
-		[WarnLevel]: WarnLevel,
-		[ErrorLevel]: ErrorLevel,
-		[FatalLevel]: FatalLevel,
-	},
-	options: LogLevels,
-} as const;
-
-const isLogLevel = (value: string): value is LogLevel =>
-	(LogLevels as readonly string[]).includes(value);
-
-const logLevelMap: Record<LogLevel, number> = {
-	[TraceLevel]: 0,
-	[DebugLevel]: 1,
-	[InfoLevel]: 2,
-	[WarnLevel]: 3,
-	[ErrorLevel]: 4,
-	[FatalLevel]: 5,
-};
-
-export function parseLogLevel(
-	level: string | undefined,
-	or: LogLevel = InfoLevel,
-): LogLevel {
-	if (!level) return or;
-	// Handle directive strings like "warn,database=trace" — extract the bare global level.
-	for (const part of level.split(",")) {
-		const trimmed = part.trim();
-		if (trimmed && !trimmed.includes("=")) {
-			if (isLogLevel(trimmed)) return trimmed;
-		}
-	}
-	return or;
-}
-
-// ---------------------------------------------------------------------------
-// Directive-based filtering
-//
-// PROSOPO_LOG_LEVEL supports both a bare level and a comma-separated directive
-// string with optional per-scope overrides, e.g.:
-//   "warn"                         – global floor
-//   "warn,database=trace"          – global warn, database:* gets trace
-//   "database=trace,http=debug"    – per-scope only, no global default
-//
-// Scope segments are separated by ":" mirroring module paths, e.g.
-//   "provider:db=debug" matches any logger whose scope starts with "provider:db".
-// ---------------------------------------------------------------------------
-
-export type Directives = Map<string, LogLevel>;
-
-/**
- * Parse a PROSOPO_LOG_LEVEL directive string into a scope→level map.
- * An entry with an empty-string key represents the global default.
- */
-export function parseDirectives(raw: string): Directives {
-	const map: Directives = new Map();
-	for (const part of raw.split(",")) {
-		const trimmed = part.trim();
-		if (!trimmed) continue;
-		const eqIdx = trimmed.indexOf("=");
-		if (eqIdx === -1) {
-			if (isLogLevel(trimmed)) map.set("", trimmed);
-		} else {
-			const scope = trimmed.slice(0, eqIdx).trim();
-			// Ignore entries with an empty scope (e.g. "=debug") — only a bare
-			// level (no "=") may set the global default.
-			if (!scope) continue;
-			const level = trimmed.slice(eqIdx + 1).trim();
-			if (isLogLevel(level)) map.set(scope, level);
-		}
-	}
-	return map;
-}
-
-/**
- * Find the most specific directive that matches the given scope.
- * Walks from the full scope up to the empty-string global default.
- * Returns the fallback if nothing matches.
- */
-export function resolveLevel(
-	scope: string,
-	directives: Directives,
-	fallback: LogLevel,
-): LogLevel {
-	if (directives.has(scope)) return directives.get(scope) as LogLevel;
-	const parts = scope.split(":");
-	for (let i = parts.length - 1; i > 0; i--) {
-		const prefix = parts.slice(0, i).join(":");
-		if (directives.has(prefix)) return directives.get(prefix) as LogLevel;
-	}
-	if (directives.has("")) return directives.get("") as LogLevel;
-	return fallback;
-}
-
-let _globalDirectives: Directives | undefined;
-
-function getGlobalDirectives(): Directives {
-	if (!_globalDirectives) {
-		const raw =
-			typeof process !== "undefined"
-				? (process.env?.PROSOPO_LOG_LEVEL ?? "")
-				: "";
-		_globalDirectives = parseDirectives(raw);
-	}
-	return _globalDirectives;
-}
-
-/**
- * Override the global directives at runtime (useful in tests or at app startup).
- * Accepts the same directive string as PROSOPO_LOG_LEVEL.
- */
-export function setGlobalDirectives(raw: string): void {
-	_globalDirectives = parseDirectives(raw);
-}
-
-// Create a new logger with the given level and scope
-export function getLogger(logLevel: LogLevel, scope: string): Logger {
-	const logger = new NativeLogger(scope);
-	logger.setLogLevel(logLevel);
-	return logger;
-}
-
-const inBrowser =
-	typeof window !== "undefined" && typeof window.document !== "undefined";
-
-const FormatJson = "json";
-const FormatPlain = "plain";
-export type Format = typeof FormatJson | typeof FormatPlain;
-
-/**
- * Native logger which uses console.log, console.error, etc, without any libraries.
- */
-export class NativeLogger implements Logger {
-	// the default data to be logged
-	// this provides utility for adding properties to every log message
-	private defaultData: LogObject | undefined;
-	private level: LogLevel;
-	private pretty = 0; // pretty print indentation level - 0 = no pretty print, 2 = 2 spaces, etc
-	private printStack = false; // whether to print the stack trace in the log
-	private format: Format = FormatJson;
-
-	constructor(
-		private scope: string,
-		private levelMap: Record<LogLevel, number> = logLevelMap,
-	) {
-		this.level = InfoLevel; // default log level
-	}
-
-	setFormat(format: Format): void {
-		this.format = format;
-		if (this.format !== FormatJson) {
-			throw new Error("Only JSON format implemented for now"); // for performance reasons
-		}
-	}
-
-	getFormat(): Format {
-		return this.format;
-	}
-
-	with(obj: LogObject, subscope?: string): Logger {
-		// Trim so a whitespace-only subscope is treated as absent and the
-		// resulting scope matches the trimmed keys produced by parseDirectives().
-		const trimmedSubscope = subscope?.trim();
-		const newScope = trimmedSubscope
-			? this.scope
-				? `${this.scope}:${trimmedSubscope}`
-				: trimmedSubscope
-			: this.scope;
-		const newLogger = new NativeLogger(newScope, this.levelMap);
-		// Avoid allocating an empty defaultData object when scoping only
-		// (e.g. with({}, "subscope")). Reuse the parent reference when obj has no
-		// keys, and skip merging entirely when neither side has data.
-		const hasObjData = Object.keys(obj).length > 0;
-		if (hasObjData) {
-			newLogger.defaultData = { ...this.defaultData, ...obj };
-		} else if (this.defaultData) {
-			newLogger.defaultData = this.defaultData;
-		}
-		newLogger.setPretty(this.getPretty());
-		newLogger.setPrintStack(this.getPrintStack());
-		// Inherit the parent's configured level as the fallback only. Directives
-		// are applied dynamically at print time (see print()), so we must NOT bake
-		// the currently-resolved level in here — otherwise a directive active now
-		// would stick to this child even after setGlobalDirectives() clears it.
-		newLogger.setLogLevel(this.getLogLevel());
-		return newLogger;
-	}
-
-	getPrintStack(): boolean {
-		return this.printStack;
-	}
-
-	setPrintStack(printStack: boolean): void {
-		this.printStack = printStack;
-	}
-
-	getPretty(): boolean {
-		return this.pretty > 0;
-	}
-
-	setPretty(pretty: boolean): void {
-		this.pretty = pretty ? 2 : 0;
-	}
-
-	getScope(): string {
-		return this.scope;
-	}
-
-	setLogLevel(level: LogLevel): void {
-		this.level = level;
-	}
-
-	getLogLevel(): LogLevel {
-		return this.level;
-	}
-
-	private unpackError(err: Error | object): {
-		msg: string;
-		data: Record<string, unknown>;
-	} {
-		const e = err as Record<string, unknown>;
-		const data: Record<string, unknown> = {};
-
-		for (const key of Object.getOwnPropertyNames(err)) {
-			if (!this.printStack && (key === "stack" || key === "stacktrace"))
-				continue;
-			data[key] = e[key];
-		}
-
-		if (!data.name) {
-			data.name = (err as { name?: unknown }).name ?? "Error";
-		}
-
-		// Recursively unpack the cause chain
-		const cause = e.cause;
-		if (cause !== undefined) {
-			if (
-				cause instanceof Error ||
-				(typeof cause === "object" && cause !== null)
-			) {
-				data.cause = this.unpackError(cause as Error | object);
-			} else {
-				data.cause = cause;
-			}
-		}
-
-		// Prefer translationKey when present (e.g. ProsopoBaseError) so the
-		// top-level `err` field is locale-stable and queryable.
-		const msg = String(e.translationKey ?? e.message ?? e.msg ?? "");
-		return { msg, data };
-	}
-
-	private print(
-		dest: (...args: unknown[]) => void,
-		fn: LogRecordFn,
-		level: LogLevel,
-	): void {
-		// Re-resolve at print time so directives set after construction are respected.
-		const effectiveLevelNum =
-			this.levelMap[
-				resolveLevel(this.scope, getGlobalDirectives(), this.level)
-			];
-		if (this.levelMap[level] < effectiveLevelNum) {
-			return; // skip logging if the level is below the effective threshold
-		}
-		const ts = new Date().toISOString();
-		// populate the log fields using the fn
-		let { data, msg, err } = fn();
-		let errMsg: string | undefined;
-		let errData: Record<string, unknown> | undefined;
-		if (err) {
-			if (err instanceof Error || typeof err === "object") {
-				// if it's an instance of Error, unpack the standard fields (e.g. message, name, stack, etc)
-				const result = this.unpackError(err);
-				errMsg = result.msg;
-				errData = result.data;
-			} else {
-				// primitive
-				errMsg = String(err);
-			}
-		}
-		// add any default data to the data object
-		if (this.defaultData) {
-			data = { ...this.defaultData, ...data };
-		}
-		// Promote `requestId` (set via `.with({requestId})` in the request
-		// logger middleware) to a top-level `req_id` on the emitted record.
-		// OpenObserve indexes top-level fields as their own columns, so this
-		// makes `WHERE req_id = '…'` cheap and lets us correlate to Caddy's
-		// `X-Request-ID` without a schema alias per stream. Keep the copy in
-		// `data.requestId` for backwards compat with existing dashboards.
-		const dataMaybeRequestId = data as { requestId?: unknown } | undefined;
-		const reqId =
-			dataMaybeRequestId && typeof dataMaybeRequestId.requestId === "string"
-				? dataMaybeRequestId.requestId
-				: undefined;
-		const baseRecord: {
-			scope: string;
-			ts: string;
-			level: LogLevel;
-			req_id?: string;
-			data?: LogObject;
-			msg?: string;
-			err?: string;
-			errData?: Record<string, unknown>;
-		} = { scope: this.scope, ts, level };
-		if (reqId) {
-			baseRecord.req_id = reqId;
-		}
-		if (data) {
-			baseRecord.data = data;
-		}
-		if (msg) {
-			baseRecord.msg = msg;
-		}
-		if (errMsg) {
-			baseRecord.err = errMsg;
-		}
-		if (errData) {
-			baseRecord.errData = errData;
-		}
-
-		if (inBrowser) {
-			// no need to convert to json, dev tools will handle it
-			if (msg || errMsg) {
-				// log the log record object separately to the message to utilize browser dev tools
-				dest(msg || errMsg, baseRecord);
-			} else {
-				dest(baseRecord);
-			}
-		} else {
-			// conversion to avoid "TypeError: Do not know how to serialize a BigInt" in JSON.stringify
-			const logRecord = stringifyBigInts(baseRecord) as object;
-
-			const output = JSON.stringify(logRecord, null, this.pretty);
-			dest(output);
-		}
-	}
-
-	info(fn: LogRecordFn): void {
-		this.print(console.info.bind(console), fn, InfoLevel);
-	}
-
-	debug(fn: LogRecordFn): void {
-		this.print(console.debug.bind(console), fn, DebugLevel);
-	}
-
-	trace(fn: LogRecordFn): void {
-		this.print(console.trace.bind(console), fn, TraceLevel);
-	}
-
-	warn(fn: LogRecordFn): void {
-		this.print(console.warn.bind(console), fn, WarnLevel);
-	}
-
-	error(fn: LogRecordFn): void {
-		this.print(console.error.bind(console), fn, ErrorLevel);
-	}
-
-	fatal(fn: LogRecordFn): void {
-		this.print(console.error.bind(console), fn, FatalLevel);
-	}
-
-	log(level: LogLevel, fn: LogRecordFn): void {
-		switch (level) {
-			case "trace":
-				this.trace(fn);
-				break;
-			case "debug":
-				this.debug(fn);
-				break;
-			case "info":
-				this.info(fn);
-				break;
-			case "warn":
-				this.warn(fn);
-				break;
-			case "error":
-				this.error(fn);
-				break;
-			case "fatal":
-				this.fatal(fn);
-				break;
-			default:
-				throw new Error(`Unknown log level: ${level}`);
-		}
-	}
-}