@prosopo/logger 1.0.2 → 1.0.4

package/src/logger.ts

@@ -0,0 +1,325 @@
+// 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";
+import { z } from "zod";
+
+export { stringifyBigInts };
+
+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 new logger instance which includes the given object in every log message. Akin to a child logger.
+	 * This is useful for adding context to log messages, such as user IDs, request IDs, etc.
+	 * @param obj An object to log, which will be added to every log message.
+	 */
+	with(obj: LogObject): Logger;
+	getPretty(): boolean;
+	setPretty(pretty: boolean): void;
+	getPrintStack(): boolean;
+	setPrintStack(printStack: boolean): void;
+	getFormat(): Format;
+	setFormat(format: Format): void;
+};
+
+export const InfoLevel = "info";
+export const DebugLevel = "debug";
+export const TraceLevel = "trace";
+export const WarnLevel = "warn";
+export const ErrorLevel = "error";
+export const FatalLevel = "fatal";
+
+export const LogLevel = z.enum([
+	InfoLevel,
+	DebugLevel,
+	TraceLevel,
+	WarnLevel,
+	ErrorLevel,
+	FatalLevel,
+]);
+export type LogLevel = z.infer<typeof LogLevel>;
+
+export type LevelMap = {
+	[K in LogLevel]: number;
+};
+
+const logLevelMap: LevelMap = {
+	[TraceLevel]: 0,
+	[DebugLevel]: 1,
+	[InfoLevel]: 2,
+	[WarnLevel]: 3,
+	[ErrorLevel]: 4,
+	[FatalLevel]: 5,
+};
+
+export function parseLogLevel(
+	level: string | undefined,
+	or: LogLevel = InfoLevel,
+): LogLevel {
+	const result = LogLevel.safeParse(level);
+	return result.success ? result.data : or;
+}
+
+// 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";
+
+export const FormatJson = "json";
+export const FormatPlain = "plain";
+export const Format = z.enum([FormatJson, FormatPlain]);
+export type Format = z.infer<typeof Format>;
+
+/**
+ * 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 levelNum: number;
+	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: LevelMap = logLevelMap,
+	) {
+		this.level = InfoLevel; // default log level
+		this.levelNum = this.levelMap[this.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): Logger {
+		const newLogger = new NativeLogger(this.scope);
+		newLogger.defaultData = { ...this.defaultData, ...obj };
+		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;
+		this.levelNum = this.levelMap[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 {
+		if (this.levelMap[level] < this.levelNum) {
+			return; // skip logging if the level is below the current log level 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 };
+		}
+		const baseRecord: {
+			scope: string;
+			ts: string;
+			level: LogLevel;
+			data?: LogObject;
+			msg?: string;
+			err?: string;
+			errData?: Record<string, unknown>;
+		} = { scope: this.scope, ts, level };
+		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}`);
+		}
+	}
+}

package/src/tests/logger.unit.test.ts

@@ -0,0 +1,134 @@
+// 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 { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { getLogger, stringifyBigInts } from "../logger.js";
+describe("unpackError", () => {
+	let captured: string[] = [];
+
+	beforeEach(() => {
+		captured = [];
+		vi.spyOn(console, "error").mockImplementation((...args: unknown[]) => {
+			captured.push(String(args[0]));
+		});
+	});
+
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	function lastRecord(): Record<string, unknown> {
+		const raw = captured[captured.length - 1] ?? "";
+		return JSON.parse(raw) as Record<string, unknown>;
+	}
+
+	it("captures name from Error prototype chain", () => {
+		const logger = getLogger("error", "test");
+		const err = new TypeError("bad input");
+		logger.error(() => ({ err }));
+		const record = lastRecord();
+		const errData = record.errData as Record<string, unknown>;
+		expect(errData.name).toBe("TypeError");
+	});
+
+	it("captures message field", () => {
+		const logger = getLogger("error", "test");
+		const err = new Error("something went wrong");
+		logger.error(() => ({ err }));
+		const errData = lastRecord().errData as Record<string, unknown>;
+		expect(errData.message).toBe("something went wrong");
+	});
+
+	it("captures custom own properties from subclass errors", () => {
+		const logger = getLogger("error", "test");
+		const err = Object.assign(new Error("custom"), { statusCode: 404 });
+		logger.error(() => ({ err }));
+		const errData = lastRecord().errData as Record<string, unknown>;
+		expect(errData.statusCode).toBe(404);
+	});
+
+	it("recursively unpacks cause", () => {
+		const logger = getLogger("error", "test");
+		const cause = new Error("root cause");
+		const err = new Error("outer");
+		(err as unknown as Record<string, unknown>).cause = cause;
+		logger.error(() => ({ err }));
+		const errData = lastRecord().errData as Record<string, unknown>;
+		const causeData = errData.cause as Record<string, unknown>;
+		expect(causeData).toBeDefined();
+	});
+
+	it("suppresses stack when printStack is false (default)", () => {
+		const logger = getLogger("error", "test");
+		const err = new Error("test");
+		logger.error(() => ({ err }));
+		const errData = lastRecord().errData as Record<string, unknown>;
+		expect(errData.stack).toBeUndefined();
+	});
+});
+
+describe("stringifyBigInts", () => {
+	it("should strigify big int", () => {
+		const bigInt = BigInt(12345678901234567890n);
+
+		const stringified = stringifyBigInts(bigInt);
+
+		expect(stringified).toEqual(bigInt.toString());
+	});
+
+	it("should strinfigy big int in object properties", () => {
+		const bigInt1 = BigInt(12345678901234567890n);
+		const bigInt2 = BigInt(23456789012345678901n);
+
+		const stringified = stringifyBigInts({
+			first: bigInt1,
+			second: {
+				inner: {
+					field: bigInt2,
+				},
+			},
+			third: "third",
+		});
+
+		expect(stringified).toEqual({
+			first: bigInt1.toString(),
+			second: {
+				inner: {
+					field: bigInt2.toString(),
+				},
+			},
+			third: "third",
+		});
+	});
+
+	it("should stringify big int inside array", () => {
+		const bigInt1 = BigInt(12345678901234567890n);
+		const bigInt2 = BigInt(23456789012345678901n);
+		const bigInt3 = BigInt(34567890123456789012n);
+
+		const stringified = stringifyBigInts([
+			bigInt1,
+			["inner", bigInt2],
+			{ name: "object", value: bigInt3 },
+			"third",
+		]);
+
+		expect(stringified).toEqual([
+			bigInt1.toString(),
+			["inner", bigInt2.toString()],
+			{ name: "object", value: bigInt3.toString() },
+			"third",
+		]);
+	});
+});

package/tsconfig.cjs.json

@@ -0,0 +1,21 @@
+{
+	"extends": "../../tsconfig.cjs.json",
+	"compilerOptions": {
+		"rootDir": "./src",
+		"outDir": "./dist/cjs"
+	},
+	"include": [
+		"./src/**/*.ts",
+		"./src/**/*.json",
+		"./src/**/*.d.ts",
+		"./src/**/*.tsx"
+	],
+	"references": [
+		{
+			"path": "../../dev/config/tsconfig.cjs.json"
+		},
+		{
+			"path": "../util/tsconfig.cjs.json"
+		}
+	]
+}

package/tsconfig.json

@@ -0,0 +1,23 @@
+{
+	"extends": "../../tsconfig.esm.json",
+	"compilerOptions": {
+		"rootDir": "./src",
+		"outDir": "./dist"
+	},
+	"include": [
+		"src",
+		"src/**/*.json",
+		"src/**/*.ts",
+		"src/**/*.tsx",
+		"src/**/*.d.ts",
+		"src/**/.*.ts"
+	],
+	"references": [
+		{
+			"path": "../../dev/config/tsconfig.json"
+		},
+		{
+			"path": "../util"
+		}
+	]
+}