@techstream/quark-core 1.1.0

package/src/logger.js

@@ -0,0 +1,182 @@
+/**
+ * @techstream/quark-core - Logger Module
+ * Lightweight structured logger with zero external dependencies
+ */
+
+/** @enum {number} */
+const LOG_LEVELS = {
+	debug: 10,
+	info: 20,
+	warn: 30,
+	error: 40,
+	fatal: 50,
+};
+
+const LEVEL_NAMES = /** @type {const} */ ({
+	10: "debug",
+	20: "info",
+	30: "warn",
+	40: "error",
+	50: "fatal",
+});
+
+/** @type {Record<string, string>} */
+const LEVEL_COLORS = {
+	debug: "\x1b[36m", // cyan
+	info: "\x1b[32m", // green
+	warn: "\x1b[33m", // yellow
+	error: "\x1b[31m", // red
+	fatal: "\x1b[35m", // magenta
+};
+
+const RESET = "\x1b[0m";
+const DIM = "\x1b[2m";
+
+const isProduction = () => process.env.NODE_ENV === "production";
+
+/**
+ * Resolves the minimum log level from options and environment
+ * @param {string} [optionLevel] - Level from options
+ * @returns {number}
+ */
+const resolveLevel = (optionLevel) => {
+	const level =
+		optionLevel || process.env.LOG_LEVEL || (isProduction() ? "info" : "debug");
+	return LOG_LEVELS[level] ?? LOG_LEVELS.info;
+};
+
+/**
+ * Formats a log entry for dev (colorized, human-readable)
+ * @param {object} entry - The log entry
+ * @returns {string}
+ */
+const formatDev = (entry) => {
+	const { timestamp, level, name, msg, ...rest } = entry;
+	const color = LEVEL_COLORS[level] || "";
+	const time = timestamp.slice(11, 23); // HH:mm:ss.SSS
+	const contextStr =
+		Object.keys(rest).length > 0
+			? ` ${DIM}${JSON.stringify(rest)}${RESET}`
+			: "";
+	return `${DIM}${time}${RESET} ${color}${level.toUpperCase().padEnd(5)}${RESET} ${DIM}[${name}]${RESET} ${msg}${contextStr}`;
+};
+
+/**
+ * Formats a log entry for production (single-line JSON)
+ * @param {object} entry - The log entry
+ * @returns {string}
+ */
+const formatProd = (entry) => {
+	return JSON.stringify(entry);
+};
+
+/**
+ * Returns the console method for a given level
+ * @param {string} level - The log level name
+ * @returns {Function}
+ */
+const getTransport = (level) => {
+	if (level === "error" || level === "fatal") return console.error;
+	if (level === "warn") return console.warn;
+	return console.log;
+};
+
+/**
+ * @typedef {Object} LoggerOptions
+ * @property {string} [name] - Logger name (e.g. "web", "worker", "db")
+ * @property {string} [level] - Minimum log level (default: "info" in production, "debug" in dev)
+ * @property {Object} [context] - Default context merged into every log entry
+ */
+
+/**
+ * @typedef {Object} Logger
+ * @property {(msg: string, data?: Object) => void} debug - Log at debug level
+ * @property {(msg: string, data?: Object) => void} info - Log at info level
+ * @property {(msg: string, data?: Object) => void} warn - Log at warn level
+ * @property {(msg: string, data?: Object) => void} error - Log at error level
+ * @property {(msg: string, data?: Object) => void} fatal - Log at fatal level
+ * @property {(context: Object) => Logger} child - Create a child logger with merged context
+ */
+
+/**
+ * Creates a structured logger instance
+ * @param {LoggerOptions} [options] - Logger configuration
+ * @returns {Logger}
+ */
+export const createLogger = (options = {}) => {
+	const {
+		name = "app",
+		level: optionLevel,
+		context: defaultContext = {},
+	} = options;
+	const minLevel = resolveLevel(optionLevel);
+	const format = isProduction() ? formatProd : formatDev;
+
+	/**
+	 * Writes a log entry if the level is at or above the minimum
+	 * @param {string} levelName - The level name
+	 * @param {string} msg - The log message
+	 * @param {Object} [data] - Additional data
+	 */
+	const write = (levelName, msg, data = {}) => {
+		const numeric = LOG_LEVELS[levelName];
+		if (numeric < minLevel) return;
+
+		const entry = {
+			timestamp: new Date().toISOString(),
+			level: levelName,
+			name,
+			msg,
+			...defaultContext,
+			...data,
+		};
+
+		const transport = getTransport(levelName);
+		transport(format(entry));
+	};
+
+	return {
+		debug: (msg, data) => write("debug", msg, data),
+		info: (msg, data) => write("info", msg, data),
+		warn: (msg, data) => write("warn", msg, data),
+		error: (msg, data) => write("error", msg, data),
+		fatal: (msg, data) => write("fatal", msg, data),
+
+		/**
+		 * Creates a child logger with merged context
+		 * @param {Object} childContext - Additional context for the child logger
+		 * @returns {Logger}
+		 */
+		child: (childContext = {}) => {
+			return createLogger({
+				name,
+				level: LEVEL_NAMES[minLevel],
+				context: { ...defaultContext, ...childContext },
+			});
+		},
+	};
+};
+
+/**
+ * Creates a request logger middleware helper.
+ * Returns a function that accepts a request object and produces
+ * a child logger enriched with request-specific fields.
+ * @param {Logger} parentLogger - The parent logger instance
+ * @returns {(request: { method?: string, url?: string, headers?: Object }) => Logger}
+ */
+export const requestLogger = (parentLogger) => {
+	return (request) => {
+		const requestId = request.headers?.["x-request-id"] || crypto.randomUUID();
+		const method = request.method || "UNKNOWN";
+		const path = request.url
+			? new URL(request.url, "http://localhost").pathname
+			: "/";
+
+		const child = parentLogger.child({ requestId, method, path });
+		child.info("request started");
+		return child;
+	};
+};
+
+/** Default logger instance */
+export const logger = createLogger({ name: "quark" });

package/src/logger.test.js

@@ -0,0 +1,287 @@
+import assert from "node:assert/strict";
+import { afterEach, beforeEach, describe, test } from "node:test";
+import { createLogger, requestLogger } from "../src/logger.js";
+
+/** Helper: captures console output during a callback */
+const captureConsole = async (fn) => {
+	const output = { log: [], warn: [], error: [] };
+	const orig = {
+		log: console.log,
+		warn: console.warn,
+		error: console.error,
+	};
+
+	console.log = (...args) => output.log.push(args.join(" "));
+	console.warn = (...args) => output.warn.push(args.join(" "));
+	console.error = (...args) => output.error.push(args.join(" "));
+
+	try {
+		await fn();
+	} finally {
+		console.log = orig.log;
+		console.warn = orig.warn;
+		console.error = orig.error;
+	}
+	return output;
+};
+
+describe("Logger", () => {
+	let originalNodeEnv;
+	let originalLogLevel;
+
+	beforeEach(() => {
+		originalNodeEnv = process.env.NODE_ENV;
+		originalLogLevel = process.env.LOG_LEVEL;
+	});
+
+	afterEach(() => {
+		if (originalNodeEnv === undefined) {
+			delete process.env.NODE_ENV;
+		} else {
+			process.env.NODE_ENV = originalNodeEnv;
+		}
+		if (originalLogLevel === undefined) {
+			delete process.env.LOG_LEVEL;
+		} else {
+			process.env.LOG_LEVEL = originalLogLevel;
+		}
+	});
+
+	test("creates logger with default options", () => {
+		const log = createLogger();
+		assert.ok(log.debug);
+		assert.ok(log.info);
+		assert.ok(log.warn);
+		assert.ok(log.error);
+		assert.ok(log.fatal);
+		assert.ok(log.child);
+	});
+
+	test("default logger instance exists with name 'quark'", async () => {
+		process.env.NODE_ENV = "production";
+		const log = createLogger({ name: "quark" });
+		const output = await captureConsole(() => {
+			log.info("hello");
+		});
+		const entry = JSON.parse(output.log[0]);
+		assert.equal(entry.name, "quark");
+	});
+
+	test("log level filtering: debug hidden at info level", async () => {
+		process.env.NODE_ENV = "production";
+		const log = createLogger({ name: "test", level: "info" });
+
+		const output = await captureConsole(() => {
+			log.debug("should be hidden");
+			log.info("should be visible");
+		});
+
+		assert.equal(output.log.length, 1);
+		const entry = JSON.parse(output.log[0]);
+		assert.equal(entry.msg, "should be visible");
+	});
+
+	test("log level filtering: debug visible at debug level", async () => {
+		process.env.NODE_ENV = "production";
+		const log = createLogger({ name: "test", level: "debug" });
+
+		const output = await captureConsole(() => {
+			log.debug("visible");
+		});
+
+		assert.equal(output.log.length, 1);
+		const entry = JSON.parse(output.log[0]);
+		assert.equal(entry.msg, "visible");
+		assert.equal(entry.level, "debug");
+	});
+
+	test("respects LOG_LEVEL env var", async () => {
+		process.env.NODE_ENV = "production";
+		process.env.LOG_LEVEL = "warn";
+		const log = createLogger({ name: "test" });
+
+		const output = await captureConsole(() => {
+			log.info("hidden");
+			log.warn("visible");
+		});
+
+		assert.equal(output.log.length, 0);
+		assert.equal(output.warn.length, 1);
+		const entry = JSON.parse(output.warn[0]);
+		assert.equal(entry.msg, "visible");
+	});
+
+	test("child logger inherits parent context", async () => {
+		process.env.NODE_ENV = "production";
+		const parent = createLogger({
+			name: "parent",
+			level: "info",
+			context: { service: "web" },
+		});
+
+		const child = parent.child({ requestId: "abc-123" });
+
+		const output = await captureConsole(() => {
+			child.info("child message");
+		});
+
+		const entry = JSON.parse(output.log[0]);
+		assert.equal(entry.name, "parent");
+		assert.equal(entry.service, "web");
+		assert.equal(entry.requestId, "abc-123");
+		assert.equal(entry.msg, "child message");
+	});
+
+	test("child logger merges context without mutating parent", async () => {
+		process.env.NODE_ENV = "production";
+		const parent = createLogger({
+			name: "parent",
+			level: "info",
+			context: { a: 1 },
+		});
+
+		parent.child({ b: 2 });
+
+		const output = await captureConsole(() => {
+			parent.info("parent only");
+		});
+
+		const entry = JSON.parse(output.log[0]);
+		assert.equal(entry.a, 1);
+		assert.equal(entry.b, undefined);
+	});
+
+	test("structured output contains required fields", async () => {
+		process.env.NODE_ENV = "production";
+		const log = createLogger({ name: "fields-test", level: "debug" });
+
+		const output = await captureConsole(() => {
+			log.info("test message", { extra: "data" });
+		});
+
+		const entry = JSON.parse(output.log[0]);
+		assert.ok(entry.timestamp);
+		assert.equal(entry.level, "info");
+		assert.equal(entry.name, "fields-test");
+		assert.equal(entry.msg, "test message");
+		assert.equal(entry.extra, "data");
+		// timestamp should be ISO 8601
+		assert.ok(!Number.isNaN(Date.parse(entry.timestamp)));
+	});
+
+	test("error and fatal use console.error", async () => {
+		process.env.NODE_ENV = "production";
+		const log = createLogger({ name: "test", level: "debug" });
+
+		const output = await captureConsole(() => {
+			log.error("err msg");
+			log.fatal("fatal msg");
+		});
+
+		assert.equal(output.error.length, 2);
+		const errEntry = JSON.parse(output.error[0]);
+		assert.equal(errEntry.level, "error");
+		const fatalEntry = JSON.parse(output.error[1]);
+		assert.equal(fatalEntry.level, "fatal");
+	});
+
+	test("warn uses console.warn", async () => {
+		process.env.NODE_ENV = "production";
+		const log = createLogger({ name: "test", level: "debug" });
+
+		const output = await captureConsole(() => {
+			log.warn("warn msg");
+		});
+
+		assert.equal(output.warn.length, 1);
+		const entry = JSON.parse(output.warn[0]);
+		assert.equal(entry.level, "warn");
+	});
+
+	test("dev mode outputs colorized non-JSON string", async () => {
+		delete process.env.NODE_ENV;
+		const log = createLogger({ name: "dev-test", level: "debug" });
+
+		const output = await captureConsole(() => {
+			log.info("hello dev");
+		});
+
+		assert.equal(output.log.length, 1);
+		const line = output.log[0];
+		// Should NOT be valid JSON in dev mode
+		assert.throws(() => JSON.parse(line));
+		// Should contain the message and logger name
+		assert.ok(line.includes("hello dev"));
+		assert.ok(line.includes("dev-test"));
+		assert.ok(line.includes("INFO"));
+	});
+
+	test("call-site data overrides default context", async () => {
+		process.env.NODE_ENV = "production";
+		const log = createLogger({
+			name: "test",
+			level: "info",
+			context: { region: "us-east" },
+		});
+
+		const output = await captureConsole(() => {
+			log.info("override", { region: "eu-west" });
+		});
+
+		const entry = JSON.parse(output.log[0]);
+		assert.equal(entry.region, "eu-west");
+	});
+});
+
+describe("requestLogger", () => {
+	test("creates child logger with request fields", async () => {
+		process.env.NODE_ENV = "production";
+		const parent = createLogger({ name: "web", level: "info" });
+		const getReqLogger = requestLogger(parent);
+
+		const request = {
+			method: "GET",
+			url: "/api/users?page=1",
+			headers: { "x-request-id": "req-456" },
+		};
+
+		const output = await captureConsole(() => {
+			const reqLog = getReqLogger(request);
+			reqLog.info("handling request");
+		});
+
+		// First log is "request started", second is "handling request"
+		assert.equal(output.log.length, 2);
+
+		const startEntry = JSON.parse(output.log[0]);
+		assert.equal(startEntry.msg, "request started");
+		assert.equal(startEntry.requestId, "req-456");
+		assert.equal(startEntry.method, "GET");
+		assert.equal(startEntry.path, "/api/users");
+
+		const handleEntry = JSON.parse(output.log[1]);
+		assert.equal(handleEntry.msg, "handling request");
+		assert.equal(handleEntry.requestId, "req-456");
+	});
+
+	test("generates requestId when header is missing", async () => {
+		process.env.NODE_ENV = "production";
+		const parent = createLogger({ name: "web", level: "info" });
+		const getReqLogger = requestLogger(parent);
+
+		const request = {
+			method: "POST",
+			url: "/api/data",
+			headers: {},
+		};
+
+		const output = await captureConsole(() => {
+			getReqLogger(request);
+		});
+
+		const entry = JSON.parse(output.log[0]);
+		assert.ok(entry.requestId);
+		assert.equal(entry.method, "POST");
+		assert.equal(entry.path, "/api/data");
+	});
+});

package/src/mailhog.js

@@ -0,0 +1,43 @@
+/**
+ * Builds MAILHOG_SMTP_URL from individual environment variables if not explicitly provided.
+ * Allows configuration via individual MAILHOG_* vars instead of a single MAILHOG_SMTP_URL.
+ */
+function getMailhogSmtpUrl() {
+	if (process.env.MAILHOG_SMTP_URL) {
+		return process.env.MAILHOG_SMTP_URL;
+	}
+
+	const host = process.env.MAILHOG_HOST || "localhost";
+	const port = process.env.MAILHOG_SMTP_PORT || "1025";
+
+	return `smtp://${host}:${port}`;
+}
+
+/**
+ * Builds Mailhog Web UI URL from individual environment variables.
+ * Useful for displaying the URL in logs or configuration.
+ */
+function getMailhogUiUrl() {
+	const host = process.env.MAILHOG_HOST || "localhost";
+	const port = process.env.MAILHOG_UI_PORT || "8025";
+
+	return `http://${host}:${port}`;
+}
+
+/**
+ * Gets Mailhog SMTP configuration for email clients.
+ */
+export const getMailhogSmtpConfig = () => {
+	const url = getMailhogSmtpUrl();
+	const match = url.match(/smtp:\/\/([^:]+):(\d+)/);
+	const host = match ? match[1] : (process.env.MAILHOG_HOST || "localhost");
+	const port = match ? match[2] : (process.env.MAILHOG_SMTP_PORT || "1025");
+
+	return {
+		host,
+		port: parseInt(port, 10),
+		url,
+	};
+};
+
+export { getMailhogSmtpUrl, getMailhogUiUrl };