@usequark/quark-core 2.5.4

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/mail.js

@@ -0,0 +1,50 @@
+/**
+ * Builds the dev mail SMTP URL from individual MAIL_* environment variables.
+ * Used only for local development (Mailpit). Production email uses SMTP_HOST/SMTP_PORT
+ * configured in email.js.
+ *
+ * @returns {string} SMTP URL (e.g. "smtp://localhost:1025")
+ */
+function getDevMailUrl() {
+	const host = process.env.MAIL_HOST || "localhost";
+	const port = process.env.MAIL_SMTP_PORT || "1025";
+
+	return `smtp://${host}:${port}`;
+}
+
+/**
+ * Builds mail Web UI URL from individual environment variables.
+ * Useful for displaying the Mailpit URL in logs or configuration.
+ *
+ * @returns {string} Mail UI URL (e.g. "http://localhost:8025")
+ */
+function getDevMailUiUrl() {
+	const host = process.env.MAIL_HOST || "localhost";
+	const port = process.env.MAIL_UI_PORT || "8025";
+
+	return `http://${host}:${port}`;
+}
+
+/**
+ * Gets dev mail SMTP configuration for the Nodemailer transport.
+ * Reads from MAIL_HOST and MAIL_SMTP_PORT environment variables.
+ *
+ * @returns {{ host: string, port: number, url: string }}
+ */
+export const getDevMailConfig = () => {
+	const host = process.env.MAIL_HOST || "localhost";
+	const port = process.env.MAIL_SMTP_PORT || "1025";
+
+	return {
+		host,
+		port: parseInt(port, 10),
+		url: getDevMailUrl(),
+	};
+};
+
+// Backwards-compatible aliases (deprecated - use getDevMailConfig, getDevMailUrl, getDevMailUiUrl)
+export const getMailSmtpConfig = getDevMailConfig;
+export const getMailSmtpUrl = getDevMailUrl;
+export const getMailUiUrl = getDevMailUiUrl;
+
+export { getDevMailUiUrl, getDevMailUrl };

package/src/metrics.js

@@ -0,0 +1,379 @@
+/**
+ * @techstream/quark-core - Metrics Module
+ * Lightweight application metrics with zero external dependencies.
+ * Supports counters, gauges, and histograms with optional labels.
+ * Exports Prometheus-compatible text format.
+ */
+
+/**
+ * @typedef {"counter" | "gauge" | "histogram"} MetricType
+ *
+ * @typedef {Object} MetricOptions
+ * @property {string} name - Metric name (e.g. "http_requests_total")
+ * @property {string} help - Human-readable description
+ * @property {string[]} [labelNames] - Allowed label keys
+ *
+ * @typedef {Object} HistogramOptions
+ * @property {string} name
+ * @property {string} help
+ * @property {string[]} [labelNames]
+ * @property {number[]} [buckets] - Histogram bucket boundaries in ascending order
+ */
+
+/** Default histogram buckets (in seconds) */
+const DEFAULT_BUCKETS = [
+	0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10,
+];
+
+/**
+ * Serialises a label object into a Prometheus label string.
+ * @param {Record<string, string>} labels
+ * @returns {string} e.g. `{method="GET",path="/api/health"}`
+ */
+const escapeLabel = (v) =>
+	String(v).replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
+
+const labelsToKey = (labels) => {
+	const keys = Object.keys(labels).sort();
+	if (keys.length === 0) return "";
+	return `{${keys.map((k) => `${k}="${escapeLabel(labels[k])}"`).join(",")}}`;
+};
+
+// ─── Counter ──────────────────────────────────────────────────
+
+class Counter {
+	/** @param {MetricOptions} opts */
+	constructor(opts) {
+		this.name = opts.name;
+		this.help = opts.help;
+		this.labelNames = opts.labelNames || [];
+		/** @type {Map<string, number>} */
+		this.values = new Map();
+	}
+
+	/**
+	 * Increment counter.
+	 * @param {Record<string, string>} [labels]
+	 * @param {number} [value=1]
+	 */
+	inc(labels = {}, value = 1) {
+		if (value < 0) throw new Error("Counter can only be incremented");
+		const key = labelsToKey(labels);
+		this.values.set(key, (this.values.get(key) || 0) + value);
+	}
+
+	/** Reset all values */
+	reset() {
+		this.values.clear();
+	}
+
+	/** @returns {string} Prometheus text */
+	serialize() {
+		const lines = [
+			`# HELP ${this.name} ${this.help}`,
+			`# TYPE ${this.name} counter`,
+		];
+		for (const [key, val] of this.values) {
+			lines.push(`${this.name}${key} ${val}`);
+		}
+		return lines.join("\n");
+	}
+}
+
+// ─── Gauge ────────────────────────────────────────────────────
+
+class Gauge {
+	/** @param {MetricOptions} opts */
+	constructor(opts) {
+		this.name = opts.name;
+		this.help = opts.help;
+		this.labelNames = opts.labelNames || [];
+		/** @type {Map<string, number>} */
+		this.values = new Map();
+	}
+
+	/** Set gauge to a specific value */
+	set(labels = {}, value = 0) {
+		this.values.set(labelsToKey(labels), value);
+	}
+
+	/** Increment gauge */
+	inc(labels = {}, value = 1) {
+		const key = labelsToKey(labels);
+		this.values.set(key, (this.values.get(key) || 0) + value);
+	}
+
+	/** Decrement gauge */
+	dec(labels = {}, value = 1) {
+		const key = labelsToKey(labels);
+		this.values.set(key, (this.values.get(key) || 0) - value);
+	}
+
+	/** Reset all values */
+	reset() {
+		this.values.clear();
+	}
+
+	/** @returns {string} Prometheus text */
+	serialize() {
+		const lines = [
+			`# HELP ${this.name} ${this.help}`,
+			`# TYPE ${this.name} gauge`,
+		];
+		for (const [key, val] of this.values) {
+			lines.push(`${this.name}${key} ${val}`);
+		}
+		return lines.join("\n");
+	}
+}
+
+// ─── Histogram ────────────────────────────────────────────────
+
+class Histogram {
+	/** @param {HistogramOptions} opts */
+	constructor(opts) {
+		this.name = opts.name;
+		this.help = opts.help;
+		this.labelNames = opts.labelNames || [];
+		this.buckets = opts.buckets || DEFAULT_BUCKETS;
+		/** @type {Map<string, { buckets: number[], sum: number, count: number }>} */
+		this.values = new Map();
+	}
+
+	/** @private */
+	_getOrCreate(key) {
+		if (!this.values.has(key)) {
+			this.values.set(key, {
+				buckets: new Array(this.buckets.length).fill(0),
+				sum: 0,
+				count: 0,
+			});
+		}
+		return this.values.get(key);
+	}
+
+	/**
+	 * Observe a value (e.g. request duration in seconds).
+	 * @param {Record<string, string>} [labels]
+	 * @param {number} value
+	 */
+	observe(labels = {}, value) {
+		const key = labelsToKey(labels);
+		const data = this._getOrCreate(key);
+		data.sum += value;
+		data.count += 1;
+		for (let i = 0; i < this.buckets.length; i++) {
+			if (value <= this.buckets[i]) {
+				data.buckets[i] += 1;
+			}
+		}
+	}
+
+	/**
+	 * Returns a timer function. Call the returned function to record
+	 * elapsed time in seconds.
+	 * @param {Record<string, string>} [labels]
+	 * @returns {() => number} stop function - returns elapsed seconds
+	 */
+	startTimer(labels = {}) {
+		const start = performance.now();
+		return () => {
+			const elapsed = (performance.now() - start) / 1000;
+			this.observe(labels, elapsed);
+			return elapsed;
+		};
+	}
+
+	/** Reset all values */
+	reset() {
+		this.values.clear();
+	}
+
+	/** @returns {string} Prometheus text */
+	serialize() {
+		const lines = [
+			`# HELP ${this.name} ${this.help}`,
+			`# TYPE ${this.name} histogram`,
+		];
+		for (const [key, data] of this.values) {
+			// Parse existing labels for bucket lines
+			const lblPrefix = key ? `${key.slice(0, -1)},` : "{";
+			const lblSuffix = key ? "}" : "}";
+
+			for (let i = 0; i < this.buckets.length; i++) {
+				const le = this.buckets[i];
+				lines.push(
+					`${this.name}_bucket${lblPrefix}le="${le}"${lblSuffix} ${data.buckets[i]}`,
+				);
+			}
+			lines.push(
+				`${this.name}_bucket${lblPrefix}le="+Inf"${lblSuffix} ${data.count}`,
+			);
+			lines.push(`${this.name}_sum${key} ${data.sum}`);
+			lines.push(`${this.name}_count${key} ${data.count}`);
+		}
+		return lines.join("\n");
+	}
+}
+
+// ─── Registry ─────────────────────────────────────────────────
+
+/**
+ * A metrics registry that holds all metric instances
+ * and can serialize them to Prometheus exposition format.
+ */
+class MetricsRegistry {
+	constructor() {
+		/** @type {Map<string, Counter | Gauge | Histogram>} */
+		this.metrics = new Map();
+	}
+
+	/**
+	 * Create and register a counter.
+	 * @param {MetricOptions} opts
+	 * @returns {Counter}
+	 */
+	counter(opts) {
+		if (this.metrics.has(opts.name)) {
+			return /** @type {Counter} */ (this.metrics.get(opts.name));
+		}
+		const c = new Counter(opts);
+		this.metrics.set(opts.name, c);
+		return c;
+	}
+
+	/**
+	 * Create and register a gauge.
+	 * @param {MetricOptions} opts
+	 * @returns {Gauge}
+	 */
+	gauge(opts) {
+		if (this.metrics.has(opts.name)) {
+			return /** @type {Gauge} */ (this.metrics.get(opts.name));
+		}
+		const g = new Gauge(opts);
+		this.metrics.set(opts.name, g);
+		return g;
+	}
+
+	/**
+	 * Create and register a histogram.
+	 * @param {HistogramOptions} opts
+	 * @returns {Histogram}
+	 */
+	histogram(opts) {
+		if (this.metrics.has(opts.name)) {
+			return /** @type {Histogram} */ (this.metrics.get(opts.name));
+		}
+		const h = new Histogram(opts);
+		this.metrics.set(opts.name, h);
+		return h;
+	}
+
+	/**
+	 * Get a registered metric by name.
+	 * @param {string} name
+	 * @returns {Counter | Gauge | Histogram | undefined}
+	 */
+	get(name) {
+		return this.metrics.get(name);
+	}
+
+	/** Reset all metrics */
+	resetAll() {
+		for (const m of this.metrics.values()) {
+			m.reset();
+		}
+	}
+
+	/**
+	 * Serialize all metrics to Prometheus exposition format.
+	 * @returns {string}
+	 */
+	serialize() {
+		const blocks = [];
+		for (const metric of this.metrics.values()) {
+			blocks.push(metric.serialize());
+		}
+		return `${blocks.join("\n\n")}\n`;
+	}
+
+	/** Number of registered metrics */
+	get size() {
+		return this.metrics.size;
+	}
+}
+
+// ─── Default Instance & Factory ───────────────────────────────
+
+/**
+ * Creates a new metrics registry.
+ * @returns {MetricsRegistry}
+ */
+export const createMetrics = () => new MetricsRegistry();
+
+/**
+ * Default application-wide metrics registry.
+ * Register HTTP metrics, business metrics, etc. on this instance.
+ */
+export const metrics = createMetrics();
+
+// ─── Pre-registered HTTP metrics ──────────────────────────────
+
+/** Total HTTP requests (labels: method, path, status) */
+export const httpRequestsTotal = metrics.counter({
+	name: "http_requests_total",
+	help: "Total number of HTTP requests",
+	labelNames: ["method", "path", "status"],
+});
+
+/** HTTP request duration in seconds (labels: method, path) */
+export const httpRequestDuration = metrics.histogram({
+	name: "http_request_duration_seconds",
+	help: "HTTP request duration in seconds",
+	labelNames: ["method", "path"],
+});
+
+/** Currently in-flight HTTP requests */
+export const httpRequestsInFlight = metrics.gauge({
+	name: "http_requests_in_flight",
+	help: "Number of HTTP requests currently being processed",
+	labelNames: ["method"],
+});
+
+/** Total application errors (labels: type) */
+export const appErrorsTotal = metrics.counter({
+	name: "app_errors_total",
+	help: "Total number of application errors",
+	labelNames: ["type"],
+});
+
+// ─── Pre-registered Queue metrics ─────────────────────────────
+
+/** Number of jobs currently waiting in each queue (label: queue) */
+export const jobQueueDepth = metrics.gauge({
+	name: "job_queue_depth",
+	help: "Number of jobs currently waiting in each queue",
+	labelNames: ["queue"],
+});
+
+/**
+ * Total job processing attempts (labels: queue, status - completed | failed).
+ * For jobs with retries > 1, each attempt increments this counter independently.
+ */
+export const jobsProcessedTotal = metrics.counter({
+	name: "jobs_processed_total",
+	help: "Total number of job processing attempts (each retry counts separately)",
+	labelNames: ["queue", "status"],
+});
+
+/** Job processing duration in seconds (labels: queue, name) */
+export const jobDuration = metrics.histogram({
+	name: "job_duration_seconds",
+	help: "Job processing duration in seconds",
+	labelNames: ["queue", "name"],
+	buckets: [0.1, 0.5, 1, 2, 5, 10, 30, 60, 120, 300],
+});
+
+// Re-export classes for advanced usage
+export { Counter, Gauge, Histogram, MetricsRegistry };