@prosopo/logger 2.0.3 → 2.0.5

package/dist/tests/loggerLevels.unit.test.js

@@ -0,0 +1,132 @@
+import { afterEach, beforeEach, describe, expect, it, vi, } from "vitest";
+import { NativeLogger, getLogger, setGlobalDirectives } from "../logger.js";
+const parseLast = (spy) => {
+    const calls = spy.mock.calls;
+    const last = calls[calls.length - 1];
+    return JSON.parse(String(last?.[0]));
+};
+let info;
+let debug;
+let trace;
+let warn;
+let error;
+beforeEach(() => {
+    setGlobalDirectives("");
+    info = vi.fn();
+    debug = vi.fn();
+    trace = vi.fn();
+    warn = vi.fn();
+    error = vi.fn();
+    vi.spyOn(console, "info").mockImplementation(info);
+    vi.spyOn(console, "debug").mockImplementation(debug);
+    vi.spyOn(console, "trace").mockImplementation(trace);
+    vi.spyOn(console, "warn").mockImplementation(warn);
+    vi.spyOn(console, "error").mockImplementation(error);
+});
+afterEach(() => {
+    vi.restoreAllMocks();
+});
+describe("NativeLogger format", () => {
+    it("accepts the json format and reports it back", () => {
+        const logger = new NativeLogger("scope");
+        logger.setFormat("json");
+        expect(logger.getFormat()).toBe("json");
+    });
+    it("rejects the plain format, which is not implemented", () => {
+        const logger = new NativeLogger("scope");
+        expect(() => logger.setFormat("plain")).toThrow("Only JSON format implemented for now");
+    });
+});
+describe("NativeLogger.log level dispatch", () => {
+    const cases = [
+        { level: "trace", dest: () => trace },
+        { level: "debug", dest: () => debug },
+        { level: "info", dest: () => info },
+        { level: "warn", dest: () => warn },
+        { level: "error", dest: () => error },
+        { level: "fatal", dest: () => error },
+    ];
+    for (const { level, dest } of cases) {
+        it(`routes ${level} to its own console method`, () => {
+            const logger = getLogger("trace", "scope");
+            logger.log(level, () => ({ msg: `${level} message` }));
+            expect(parseLast(dest()).msg).toBe(`${level} message`);
+        });
+    }
+    it("throws on an unknown log level", () => {
+        const logger = getLogger("trace", "scope");
+        expect(() => logger.log("verbose", () => ({ msg: "x" }))).toThrow("Unknown log level: verbose");
+    });
+});
+describe("NativeLogger direct level methods", () => {
+    it("emits trace records at the trace threshold", () => {
+        const logger = getLogger("trace", "scope");
+        logger.trace(() => ({ msg: "traced" }));
+        expect(parseLast(trace)).toMatchObject({ msg: "traced", level: "trace" });
+    });
+    it("emits warn records", () => {
+        const logger = getLogger("info", "scope");
+        logger.warn(() => ({ msg: "warned" }));
+        expect(parseLast(warn)).toMatchObject({ msg: "warned", level: "warn" });
+    });
+    it("emits fatal records via console.error", () => {
+        const logger = getLogger("info", "scope");
+        logger.fatal(() => ({ msg: "fatal" }));
+        expect(parseLast(error)).toMatchObject({ msg: "fatal", level: "fatal" });
+    });
+    it("suppresses a record below the threshold", () => {
+        const logger = getLogger("warn", "scope");
+        logger.debug(() => ({ msg: "hidden" }));
+        expect(debug).not.toHaveBeenCalled();
+    });
+});
+describe("error unpacking edge cases", () => {
+    it("passes a primitive cause through unchanged", () => {
+        const logger = getLogger("info", "scope");
+        const err = new Error("boom");
+        err.cause = "a string cause";
+        logger.error(() => ({ err }));
+        expect(parseLast(error).errData).toMatchObject({ cause: "a string cause" });
+    });
+    it("keeps a null cause out of the unpacked object", () => {
+        const logger = getLogger("info", "scope");
+        const err = new Error("boom");
+        err.cause = null;
+        logger.error(() => ({ err }));
+        expect(parseLast(error).errData).toBeDefined();
+    });
+    it("stringifies a primitive err field", () => {
+        const logger = getLogger("info", "scope");
+        logger.error(() => ({ err: 42 }));
+        expect(parseLast(error).err).toBe("42");
+    });
+    it("stringifies a string err field", () => {
+        const logger = getLogger("info", "scope");
+        logger.error(() => ({ err: "plain failure" }));
+        expect(parseLast(error).err).toBe("plain failure");
+    });
+});
+describe("Logger.with default data reuse", () => {
+    it("reuses the parent default data when the child adds none", () => {
+        const parent = getLogger("info", "scope").with({ requestId: "r1" });
+        const child = parent.with({}, "sub");
+        child.info(() => ({ msg: "hello" }));
+        expect(parseLast(info)).toMatchObject({
+            msg: "hello",
+            req_id: "r1",
+            data: { requestId: "r1" },
+            scope: "scope:sub",
+        });
+    });
+    it("omits default data entirely when neither side supplies any", () => {
+        const child = getLogger("info", "scope").with({}, "sub");
+        child.info(() => ({ msg: "hello" }));
+        expect(parseLast(info)).toMatchObject({ msg: "hello", scope: "scope:sub" });
+    });
+    it("merges the child data over the parent data", () => {
+        const parent = getLogger("info", "scope").with({ a: 1, b: 2 });
+        parent.with({ b: 3 }).info(() => ({ msg: "hello" }));
+        expect(parseLast(info)).toMatchObject({ data: { a: 1, b: 3 } });
+    });
+});
+//# sourceMappingURL=loggerLevels.unit.test.js.map

package/dist/tests/loggerLevels.unit.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loggerLevels.unit.test.js","sourceRoot":"","sources":["../../src/tests/loggerLevels.unit.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@prosopo/logger",
-	"version": "2.0.3",
+	"version": "2.0.5",
 	"description": "Prosopo logger library",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
@@ -28,22 +28,23 @@
 	"author": "Prosopo Limited",
 	"license": "Apache-2.0",
 	"dependencies": {
-		"@prosopo/util": "3.3.4",
+		"@prosopo/util": "3.3.5",
 		"zod": "3.23.8"
 	},
 	"devDependencies": {
-		"@prosopo/config": "3.3.4",
+		"@prosopo/config": "3.3.7",
 		"@types/node": "22.10.2",
-		"@vitest/coverage-v8": "3.2.4",
+		"@vitest/coverage-v8": "4.1.10",
 		"concurrently": "9.0.1",
 		"del-cli": "6.0.0",
 		"dotenv": "16.4.5",
+		"jsdom": "25.0.0",
 		"npm-run-all": "4.1.5",
 		"tslib": "2.7.0",
 		"tsx": "4.20.3",
 		"typescript": "5.6.2",
-		"vite": "6.4.3",
-		"vitest": "3.2.4"
+		"vite": "8.1.5",
+		"vitest": "4.1.10"
 	},
 	"repository": {
 		"type": "git",

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

@@ -0,0 +1,85 @@
+// 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.
+
+// @vitest-environment jsdom
+
+import {
+	type Mock,
+	afterEach,
+	beforeEach,
+	describe,
+	expect,
+	it,
+	vi,
+} from "vitest";
+import type { LogRecord } from "../logger.js";
+import { getLogger, setGlobalDirectives } from "../logger.js";
+
+// `inBrowser` is resolved once at module load, so this whole file runs under
+// jsdom to exercise the dev-tools branch of print() (objects are passed to the
+// console verbatim rather than being serialised to JSON).
+
+type ConsoleMock = Mock<(...args: unknown[]) => void>;
+
+let info: ConsoleMock;
+let error: ConsoleMock;
+
+beforeEach(() => {
+	setGlobalDirectives("");
+	info = vi.fn<(...args: unknown[]) => void>();
+	error = vi.fn<(...args: unknown[]) => void>();
+	vi.spyOn(console, "info").mockImplementation(info);
+	vi.spyOn(console, "error").mockImplementation(error);
+});
+
+afterEach(() => {
+	vi.restoreAllMocks();
+});
+
+describe("NativeLogger in a browser", () => {
+	it("logs the message and the record separately so dev tools can expand it", () => {
+		getLogger("info", "scope").info((): LogRecord => ({ msg: "hello" }));
+
+		expect(info).toHaveBeenCalledWith(
+			"hello",
+			expect.objectContaining({ msg: "hello", scope: "scope", level: "info" }),
+		);
+	});
+
+	it("falls back to the error message when there is no msg", () => {
+		getLogger("info", "scope").error(
+			(): LogRecord => ({ err: new Error("boom") }),
+		);
+
+		expect(error).toHaveBeenCalledWith(
+			"boom",
+			expect.objectContaining({ err: "boom" }),
+		);
+	});
+
+	it("logs the bare record when there is neither a message nor an error", () => {
+		getLogger("info", "scope").info((): LogRecord => ({ data: { a: 1 } }));
+
+		expect(info).toHaveBeenCalledWith(
+			expect.objectContaining({ data: { a: 1 }, scope: "scope" }),
+		);
+		expect(info.mock.calls[0]).toHaveLength(1);
+	});
+
+	it("does not serialise the record to a string", () => {
+		getLogger("info", "scope").info((): LogRecord => ({ msg: "hello" }));
+
+		expect(typeof info.mock.calls[0]?.[1]).toBe("object");
+	});
+});

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

@@ -0,0 +1,215 @@
+// 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 {
+	type Mock,
+	afterEach,
+	beforeEach,
+	describe,
+	expect,
+	it,
+	vi,
+} from "vitest";
+import type { LogLevel, LogRecord } from "../logger.js";
+import { NativeLogger, getLogger, setGlobalDirectives } from "../logger.js";
+
+type Record_ = Record<string, unknown>;
+
+type ConsoleMock = Mock<(...args: unknown[]) => void>;
+
+const parseLast = (spy: ConsoleMock): Record_ => {
+	const calls = spy.mock.calls;
+	const last = calls[calls.length - 1];
+	return JSON.parse(String(last?.[0])) as Record_;
+};
+
+let info: ConsoleMock;
+let debug: ConsoleMock;
+let trace: ConsoleMock;
+let warn: ConsoleMock;
+let error: ConsoleMock;
+
+beforeEach(() => {
+	setGlobalDirectives("");
+	info = vi.fn<(...args: unknown[]) => void>();
+	debug = vi.fn<(...args: unknown[]) => void>();
+	trace = vi.fn<(...args: unknown[]) => void>();
+	warn = vi.fn<(...args: unknown[]) => void>();
+	error = vi.fn<(...args: unknown[]) => void>();
+	vi.spyOn(console, "info").mockImplementation(info);
+	vi.spyOn(console, "debug").mockImplementation(debug);
+	vi.spyOn(console, "trace").mockImplementation(trace);
+	vi.spyOn(console, "warn").mockImplementation(warn);
+	vi.spyOn(console, "error").mockImplementation(error);
+});
+
+afterEach(() => {
+	vi.restoreAllMocks();
+});
+
+describe("NativeLogger format", () => {
+	it("accepts the json format and reports it back", () => {
+		const logger = new NativeLogger("scope");
+
+		logger.setFormat("json");
+
+		expect(logger.getFormat()).toBe("json");
+	});
+
+	it("rejects the plain format, which is not implemented", () => {
+		const logger = new NativeLogger("scope");
+
+		expect(() => logger.setFormat("plain")).toThrow(
+			"Only JSON format implemented for now",
+		);
+	});
+});
+
+describe("NativeLogger.log level dispatch", () => {
+	const cases: Array<{
+		level: LogLevel;
+		dest: () => ConsoleMock;
+	}> = [
+		{ level: "trace", dest: (): ConsoleMock => trace },
+		{ level: "debug", dest: (): ConsoleMock => debug },
+		{ level: "info", dest: (): ConsoleMock => info },
+		{ level: "warn", dest: (): ConsoleMock => warn },
+		{ level: "error", dest: (): ConsoleMock => error },
+		{ level: "fatal", dest: (): ConsoleMock => error },
+	];
+
+	for (const { level, dest } of cases) {
+		it(`routes ${level} to its own console method`, () => {
+			const logger = getLogger("trace", "scope");
+
+			logger.log(level, (): LogRecord => ({ msg: `${level} message` }));
+
+			expect(parseLast(dest()).msg).toBe(`${level} message`);
+		});
+	}
+
+	it("throws on an unknown log level", () => {
+		const logger = getLogger("trace", "scope");
+
+		expect(() =>
+			// the switch guards against a level smuggled past the type system
+			logger.log("verbose" as LogLevel, (): LogRecord => ({ msg: "x" })),
+		).toThrow("Unknown log level: verbose");
+	});
+});
+
+describe("NativeLogger direct level methods", () => {
+	it("emits trace records at the trace threshold", () => {
+		const logger = getLogger("trace", "scope");
+
+		logger.trace((): LogRecord => ({ msg: "traced" }));
+
+		expect(parseLast(trace)).toMatchObject({ msg: "traced", level: "trace" });
+	});
+
+	it("emits warn records", () => {
+		const logger = getLogger("info", "scope");
+
+		logger.warn((): LogRecord => ({ msg: "warned" }));
+
+		expect(parseLast(warn)).toMatchObject({ msg: "warned", level: "warn" });
+	});
+
+	it("emits fatal records via console.error", () => {
+		const logger = getLogger("info", "scope");
+
+		logger.fatal((): LogRecord => ({ msg: "fatal" }));
+
+		expect(parseLast(error)).toMatchObject({ msg: "fatal", level: "fatal" });
+	});
+
+	it("suppresses a record below the threshold", () => {
+		const logger = getLogger("warn", "scope");
+
+		logger.debug((): LogRecord => ({ msg: "hidden" }));
+
+		expect(debug).not.toHaveBeenCalled();
+	});
+});
+
+describe("error unpacking edge cases", () => {
+	it("passes a primitive cause through unchanged", () => {
+		const logger = getLogger("info", "scope");
+		const err: Error & { cause?: unknown } = new Error("boom");
+		err.cause = "a string cause";
+
+		logger.error((): LogRecord => ({ err }));
+
+		expect(parseLast(error).errData).toMatchObject({ cause: "a string cause" });
+	});
+
+	it("keeps a null cause out of the unpacked object", () => {
+		const logger = getLogger("info", "scope");
+		const err: Error & { cause?: unknown } = new Error("boom");
+		err.cause = null;
+
+		logger.error((): LogRecord => ({ err }));
+
+		// null is an object, so it takes the object branch and unpacks to nothing
+		expect(parseLast(error).errData).toBeDefined();
+	});
+
+	it("stringifies a primitive err field", () => {
+		const logger = getLogger("info", "scope");
+
+		logger.error((): LogRecord => ({ err: 42 }));
+
+		expect(parseLast(error).err).toBe("42");
+	});
+
+	it("stringifies a string err field", () => {
+		const logger = getLogger("info", "scope");
+
+		logger.error((): LogRecord => ({ err: "plain failure" }));
+
+		expect(parseLast(error).err).toBe("plain failure");
+	});
+});
+
+describe("Logger.with default data reuse", () => {
+	it("reuses the parent default data when the child adds none", () => {
+		const parent = getLogger("info", "scope").with({ requestId: "r1" });
+
+		const child = parent.with({}, "sub");
+		child.info((): LogRecord => ({ msg: "hello" }));
+
+		expect(parseLast(info)).toMatchObject({
+			msg: "hello",
+			req_id: "r1",
+			data: { requestId: "r1" },
+			scope: "scope:sub",
+		});
+	});
+
+	it("omits default data entirely when neither side supplies any", () => {
+		const child = getLogger("info", "scope").with({}, "sub");
+
+		child.info((): LogRecord => ({ msg: "hello" }));
+
+		expect(parseLast(info)).toMatchObject({ msg: "hello", scope: "scope:sub" });
+	});
+
+	it("merges the child data over the parent data", () => {
+		const parent = getLogger("info", "scope").with({ a: 1, b: 2 });
+
+		parent.with({ b: 3 }).info((): LogRecord => ({ msg: "hello" }));
+
+		expect(parseLast(info)).toMatchObject({ data: { a: 1, b: 3 } });
+	});
+});