@usequark/quark-core 2.5.4

package/src/db-instrumentation.test.js

@@ -0,0 +1,284 @@
+import assert from "node:assert";
+import { mock, test } from "node:test";
+
+// Module-level env control: restore after each test.
+const ORIGINAL_ENV = { ...process.env };
+
+test("db-instrumentation", async (t) => {
+	t.afterEach(() => {
+		process.env.DB_INSTRUMENTATION = ORIGINAL_ENV.DB_INSTRUMENTATION;
+		process.env.DB_SLOW_QUERY_THRESHOLD = ORIGINAL_ENV.DB_SLOW_QUERY_THRESHOLD;
+	});
+
+	await t.test("exports createDbInstrumentation", async () => {
+		const mod = await import("./db-instrumentation.js");
+		assert.equal(typeof mod.createDbInstrumentation, "function");
+	});
+
+	await t.test("exports maskSensitiveValues", async () => {
+		const mod = await import("./db-instrumentation.js");
+		assert.equal(typeof mod.maskSensitiveValues, "function");
+	});
+
+	await t.test("exports isSensitiveKey", async () => {
+		const mod = await import("./db-instrumentation.js");
+		assert.equal(typeof mod.isSensitiveKey, "function");
+	});
+
+	await t.test("exports summarizeArgs", async () => {
+		const mod = await import("./db-instrumentation.js");
+		assert.equal(typeof mod.summarizeArgs, "function");
+	});
+
+	await t.test("exports getSlowThreshold", async () => {
+		const mod = await import("./db-instrumentation.js");
+		assert.equal(typeof mod.getSlowThreshold, "function");
+	});
+
+	await t.test("exports REDACTED_PLACEHOLDER", async () => {
+		const mod = await import("./db-instrumentation.js");
+		assert.equal(mod.REDACTED_PLACEHOLDER, "[REDACTED]");
+	});
+
+	await t.test(
+		"should return null when DB_INSTRUMENTATION is disabled",
+		async () => {
+			process.env.DB_INSTRUMENTATION = "false";
+			const { createDbInstrumentation } = await import(
+				"./db-instrumentation.js"
+			);
+			const result = createDbInstrumentation();
+			assert.strictEqual(result, null);
+		},
+	);
+
+	await t.test(
+		"should return an extension object when instrumentation is enabled",
+		async () => {
+			process.env.DB_INSTRUMENTATION = "true";
+			// Re-import to pick up updated env (module body is cached, but
+			// isInstrumentationEnabled reads process.env each call).
+			const { createDbInstrumentation } = await import(
+				"./db-instrumentation.js"
+			);
+			const ext = createDbInstrumentation();
+			assert.ok(ext, "expected non-null extension");
+			assert.equal(ext.name, "quark-db-instrumentation");
+			assert.equal(typeof ext.query.$allOperations, "function");
+		},
+	);
+
+	await t.test(
+		"maskSensitiveValues — redacts known sensitive keys",
+		async () => {
+			const { maskSensitiveValues, REDACTED_PLACEHOLDER } = await import(
+				"./db-instrumentation.js"
+			);
+
+			const input = {
+				email: "user@example.com",
+				password: "supersecret",
+				name: "Alice",
+				token: "abc123",
+				metadata: {
+					apiKey: "sk-xxx",
+					role: "admin",
+				},
+			};
+
+			const result = maskSensitiveValues(input);
+
+			assert.strictEqual(result.email, "user@example.com");
+			assert.strictEqual(result.password, REDACTED_PLACEHOLDER);
+			assert.strictEqual(result.name, "Alice");
+			assert.strictEqual(result.token, REDACTED_PLACEHOLDER);
+			assert.strictEqual(result.metadata.apiKey, REDACTED_PLACEHOLDER);
+			assert.strictEqual(result.metadata.role, "admin");
+		},
+	);
+
+	await t.test(
+		"maskSensitiveValues — handles null/undefined/primitives",
+		async () => {
+			const { maskSensitiveValues } = await import("./db-instrumentation.js");
+
+			assert.strictEqual(maskSensitiveValues(null), null);
+			assert.strictEqual(maskSensitiveValues(undefined), undefined);
+			assert.strictEqual(maskSensitiveValues(42), 42);
+			assert.strictEqual(maskSensitiveValues("hello"), "hello");
+		},
+	);
+
+	await t.test("maskSensitiveValues — handles arrays", async () => {
+		const { maskSensitiveValues, REDACTED_PLACEHOLDER } = await import(
+			"./db-instrumentation.js"
+		);
+
+		const input = [
+			{ password: "secret1", name: "A" },
+			{ password: "secret2", name: "B" },
+		];
+
+		const result = maskSensitiveValues(input);
+
+		assert.equal(result[0].password, REDACTED_PLACEHOLDER);
+		assert.equal(result[0].name, "A");
+		assert.equal(result[1].password, REDACTED_PLACEHOLDER);
+		assert.equal(result[1].name, "B");
+	});
+
+	await t.test("maskSensitiveValues — deeply nested objects", async () => {
+		const { maskSensitiveValues, REDACTED_PLACEHOLDER } = await import(
+			"./db-instrumentation.js"
+		);
+
+		const input = {
+			user: {
+				profile: {
+					hash: "abc",
+					displayName: "Bob",
+				},
+			},
+		};
+
+		const result = maskSensitiveValues(input);
+
+		assert.strictEqual(result.user.profile.hash, REDACTED_PLACEHOLDER);
+		assert.strictEqual(result.user.profile.displayName, "Bob");
+	});
+
+	await t.test("isSensitiveKey — matches known patterns", async () => {
+		const { isSensitiveKey } = await import("./db-instrumentation.js");
+
+		assert.strictEqual(isSensitiveKey("password"), true);
+		assert.strictEqual(isSensitiveKey("Password"), true);
+		assert.strictEqual(isSensitiveKey("PASSWORD"), true);
+		assert.strictEqual(isSensitiveKey("token"), true);
+		assert.strictEqual(isSensitiveKey("api_key"), true);
+		assert.strictEqual(isSensitiveKey("apiKey"), true);
+		assert.strictEqual(isSensitiveKey("secret"), true);
+		assert.strictEqual(isSensitiveKey("hash"), true);
+		assert.strictEqual(isSensitiveKey("pin"), true);
+		assert.strictEqual(isSensitiveKey("otp"), true);
+		assert.strictEqual(isSensitiveKey("nonce"), true);
+		assert.strictEqual(isSensitiveKey("signature"), true);
+		assert.strictEqual(isSensitiveKey("csrf_token"), true);
+		assert.strictEqual(isSensitiveKey("authorization"), true);
+	});
+
+	await t.test("isSensitiveKey — does not match safe keys", async () => {
+		const { isSensitiveKey } = await import("./db-instrumentation.js");
+
+		assert.strictEqual(isSensitiveKey("email"), false);
+		assert.strictEqual(isSensitiveKey("name"), false);
+		assert.strictEqual(isSensitiveKey("title"), false);
+		assert.strictEqual(isSensitiveKey("description"), false);
+		assert.strictEqual(isSensitiveKey("id"), false);
+		assert.strictEqual(isSensitiveKey("createdAt"), false);
+		assert.strictEqual(isSensitiveKey("updatedAt"), false);
+		assert.strictEqual(isSensitiveKey("role"), false);
+	});
+
+	await t.test("summarizeArgs — masks sensitive fields", async () => {
+		const { summarizeArgs, REDACTED_PLACEHOLDER } = await import(
+			"./db-instrumentation.js"
+		);
+
+		const args = {
+			where: { email: "test@test.com", password: "hunter2" },
+			data: { name: "Test", token: "xyz" },
+		};
+
+		const result = summarizeArgs(args);
+
+		assert.strictEqual(result.where.email, "test@test.com");
+		assert.strictEqual(result.where.password, REDACTED_PLACEHOLDER);
+		assert.strictEqual(result.data.name, "Test");
+		assert.strictEqual(result.data.token, REDACTED_PLACEHOLDER);
+	});
+
+	await t.test("summarizeArgs — truncates large objects", async () => {
+		const { summarizeArgs } = await import("./db-instrumentation.js");
+
+		const largeWhere = {};
+		for (let i = 0; i < 20; i++) {
+			largeWhere[`field_${i}`] = `value_${i}`;
+		}
+
+		const args = { where: largeWhere };
+		const result = summarizeArgs(args);
+
+		// Should have at most 5 keys (3 truncated + the "[+N more]" marker)
+		const keyCount = Object.keys(result.where).length;
+		assert.ok(keyCount <= 5, `Expected ≤5 keys, got ${keyCount}`);
+		assert.ok("[+17 more]" in result.where || "[+11 more]" in result.where);
+	});
+
+	await t.test(
+		"summarizeArgs — returns empty object for null/undefined",
+		async () => {
+			const { summarizeArgs } = await import("./db-instrumentation.js");
+
+			assert.deepStrictEqual(summarizeArgs(null), {});
+			assert.deepStrictEqual(summarizeArgs(undefined), {});
+		},
+	);
+
+	await t.test("getSlowThreshold — reads from env", async () => {
+		const { getSlowThreshold } = await import("./db-instrumentation.js");
+
+		process.env.DB_SLOW_QUERY_THRESHOLD = "2000";
+		assert.strictEqual(getSlowThreshold(), 2000);
+
+		process.env.DB_SLOW_QUERY_THRESHOLD = "-1";
+		assert.strictEqual(getSlowThreshold(), 500); // fallback to default
+
+		delete process.env.DB_SLOW_QUERY_THRESHOLD;
+		assert.strictEqual(getSlowThreshold(), 500); // fallback to default
+	});
+
+	await t.test("$allOperations — calls query and returns result", async () => {
+		process.env.DB_INSTRUMENTATION = "true";
+		const { createDbInstrumentation } = await import("./db-instrumentation.js");
+		const ext = createDbInstrumentation();
+
+		const expected = { id: 1, email: "test@test.com" };
+		const params = {
+			model: "User",
+			operation: "findUnique",
+			args: { where: { id: 1 } },
+			query: mock.fn(async () => expected),
+		};
+
+		const result = await ext.query.$allOperations(params);
+
+		assert.strictEqual(result, expected);
+		assert.equal(params.query.mock.callCount(), 1);
+	});
+
+	await t.test(
+		"$allOperations — still returns result on query error (finally block)",
+		async () => {
+			process.env.DB_INSTRUMENTATION = "true";
+			const { createDbInstrumentation } = await import(
+				"./db-instrumentation.js"
+			);
+			const ext = createDbInstrumentation();
+
+			const queryError = new Error("DB failure");
+			const params = {
+				model: "User",
+				operation: "create",
+				args: { data: { email: "test@test.com" } },
+				query: mock.fn(async () => {
+					throw queryError;
+				}),
+			};
+
+			await assert.rejects(
+				() => ext.query.$allOperations(params),
+				(error) => error === queryError,
+			);
+		},
+	);
+});

package/src/db-metrics.js

@@ -0,0 +1,26 @@
+/**
+ * @techstream/quark-core — Database Metrics Registry
+ *
+ * Pre-registered Prometheus metrics for database query instrumentation.
+ * Imported lazily by db-instrumentation.js to avoid circular dependencies.
+ *
+ * These metrics are registered on the global `metrics` singleton so they
+ * appear alongside HTTP and queue metrics at the /api/metrics endpoint.
+ */
+
+import { metrics } from "./metrics.js";
+
+/** Total database queries (labels: model, operation) */
+export const dbQueriesTotal = metrics.counter({
+	name: "db_queries_total",
+	help: "Total number of database queries executed",
+	labelNames: ["model", "operation"],
+});
+
+/** Database query duration in seconds (labels: model, operation) */
+export const dbQueryDuration = metrics.histogram({
+	name: "db_query_duration_seconds",
+	help: "Database query duration in seconds",
+	labelNames: ["model", "operation"],
+	buckets: [0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5],
+});

package/src/db.js

@@ -0,0 +1,218 @@
+/**
+ * @techstream/quark-core - Database Utilities
+ *
+ * Shared Prisma client singleton, connection-string builder, pool config,
+ * and a lightweight health-check ping.  These replace the per-project
+ * re-implementations in Regina / Pawdora / Trenchmate.
+ *
+ * Usage:
+ *   import { createPrismaClient, getConnectionString, pingDatabase } from "@techstream/quark-core/db";
+ */
+
+// ---------------------------------------------------------------------------
+// Connection String
+// ---------------------------------------------------------------------------
+
+/**
+ * Builds a PostgreSQL connection string from environment variables.
+ *
+ * Priority: DATABASE_URL → assembled from POSTGRES_* vars.
+ *
+ * @param {{ throwOnMissing?: boolean }} [options]
+ * @returns {string} PostgreSQL connection string
+ */
+export function getConnectionString({ throwOnMissing = true } = {}) {
+	// 1. Prefer an explicit DATABASE_URL if set
+	if (process.env.DATABASE_URL) {
+		return process.env.DATABASE_URL;
+	}
+
+	// 2. Assemble from individual POSTGRES_* vars
+	const user = process.env.POSTGRES_USER;
+	const password = process.env.POSTGRES_PASSWORD;
+	const host = process.env.POSTGRES_HOST || "localhost";
+	const port = process.env.POSTGRES_PORT || "5432";
+	const db = process.env.POSTGRES_DB;
+
+	const hasCredentials = user && password && db;
+
+	if (!hasCredentials) {
+		if (throwOnMissing) {
+			const missing = [];
+			if (!user) missing.push("POSTGRES_USER");
+			if (!password) missing.push("POSTGRES_PASSWORD");
+			if (!db) missing.push("POSTGRES_DB");
+			throw new Error(
+				`Missing required database environment variables: ${missing.join(", ")}. ` +
+					"Set DATABASE_URL or the individual POSTGRES_* variables.",
+			);
+		}
+
+		// Placeholder for prisma generate / CI
+		return "postgresql://placeholder:placeholder@localhost:5432/placeholder?schema=public";
+	}
+
+	return `postgresql://${user}:${password}@${host}:${port}/${db}?schema=public`;
+}
+
+// ---------------------------------------------------------------------------
+// Pool Config
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns the connection pool configuration for the `pg` driver.
+ *
+ * Reads from environment variables with sensible defaults:
+ *   DB_POOL_MAX               – max connections (default: 10 prod / 5 dev)
+ *   DB_POOL_IDLE_TIMEOUT      – idle timeout ms  (default: 30 000)
+ *   DB_POOL_CONNECTION_TIMEOUT – connect timeout ms (default: 5 000)
+ *
+ * @returns {{ max: number, idleTimeoutMillis: number, connectionTimeoutMillis: number }}
+ */
+export function getPoolConfig() {
+	const isProduction = process.env.NODE_ENV === "production";
+	return {
+		max: Number(process.env.DB_POOL_MAX) || (isProduction ? 10 : 5),
+		idleTimeoutMillis: Number(process.env.DB_POOL_IDLE_TIMEOUT) || 30_000,
+		connectionTimeoutMillis:
+			Number(process.env.DB_POOL_CONNECTION_TIMEOUT) || 5_000,
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Prisma Client Singleton
+// ---------------------------------------------------------------------------
+
+/**
+ * Creates a lazy Prisma client singleton that is safe to import at build
+ * time (no DB connection is made until the first property access).
+ *
+ * The singleton is stored on `globalThis` so it survives hot-reloads in
+ * development and is shared across lazy imports in a monorepo. The slot is
+ * namespaced per client (`__quark_prisma_<name>`) so two different Prisma
+ * clients in the same process do not silently share one instance.
+ *
+ * @template T - PrismaClient subclass
+ * @param {new (...args: any[]) => T} ClientClass - The PrismaClient constructor
+ * @param {Object} [options]
+ * @param {Array<(client: T) => T>} [options.$extends] - Extension functions applied to the client
+ * @param {Record<string, any>} [options.adapterOptions] - Extra options passed to the ClientClass constructor
+ * @param {string} [options.name] - Singleton namespace; defaults to the ClientClass name
+ * @param {string} [options.globalKey] - Full override for the `globalThis` key
+ * @returns {T} Proxy that defers initialization until first use
+ */
+export function createPrismaClient(ClientClass, options = {}) {
+	const globalKey =
+		options.globalKey ||
+		`__quark_prisma_${options.name || ClientClass?.name || "default"}`;
+
+	/**
+	 * Returns the real client, creating it on first access.
+	 * @returns {T}
+	 */
+	function getClient() {
+		if (globalThis[globalKey]) return globalThis[globalKey];
+
+		let client = new ClientClass(options.adapterOptions ?? {});
+
+		// Apply $extends chain if provided
+		if (options.$extends?.length) {
+			for (const ext of options.$extends) {
+				client = ext(client);
+			}
+		}
+
+		globalThis[globalKey] = client;
+		return client;
+	}
+
+	// Proxy-based deferred init — methods are bound on first access so the
+	// caller never notices the lazy instantiation.
+	return new Proxy(/** @type {T} */ ({}), {
+		get(_target, prop, receiver) {
+			const client = getClient();
+			const value = Reflect.get(client, prop, receiver);
+			return typeof value === "function" ? value.bind(client) : value;
+		},
+		has(_target, prop) {
+			return prop in getClient();
+		},
+		ownKeys() {
+			return Reflect.ownKeys(getClient());
+		},
+		getOwnPropertyDescriptor(_target, prop) {
+			return Reflect.getOwnPropertyDescriptor(getClient(), prop);
+		},
+	});
+}
+
+// ---------------------------------------------------------------------------
+// Health Check
+// ---------------------------------------------------------------------------
+
+/**
+ * Pings PostgreSQL to verify connectivity.
+ * Uses a raw `pg.Client` directly so the check is immune to Prisma adapter
+ * quirks.  `pg` is an optional peer dependency that is dynamically imported
+ * so importing this module (which the `.` and `./core` barrels re-export)
+ * does not require it to be installed. The import is marked `webpackIgnore`
+ * so bundlers keep it as a runtime import instead of failing the build when
+ * `pg` is absent.
+ *
+ * @param {object} [options]
+ * @param {number} [options.timeout=3000] - Connection/query timeout in ms.
+ * @returns {Promise<{ status: "ok", latencyMs: number } | { status: "error", message: string }>}
+ */
+export async function pingDatabase({ timeout = 3000 } = {}) {
+	/** @type {import("pg").Client | null} */
+	let client = null;
+	let connectionString;
+
+	try {
+		const { default: pg } = await import(/* webpackIgnore: true */ "pg");
+		connectionString = getConnectionString();
+
+		client = new pg.Client({
+			connectionString,
+			connectionTimeoutMillis: timeout,
+			query_timeout: timeout,
+		});
+
+		await client.connect();
+
+		const start = performance.now();
+		await client.query("SELECT 1");
+		const latencyMs = Math.round(performance.now() - start);
+
+		return { status: "ok", latencyMs };
+	} catch (error) {
+		let message;
+		if (
+			error?.code === "MODULE_NOT_FOUND" ||
+			error?.code === "ERR_MODULE_NOT_FOUND"
+		) {
+			message = "pg is not installed";
+		} else if (
+			error?.code === "ECONNREFUSED" ||
+			/ECONNREFUSED/i.test(error?.message ?? "")
+		) {
+			try {
+				const { hostname, port } = new URL(connectionString);
+				message = `PostgreSQL unreachable at ${hostname}:${port || "5432"}`;
+			} catch {
+				message = "PostgreSQL unreachable";
+			}
+		} else if (error?.code === "ENOTFOUND") {
+			message = `PostgreSQL host not found: ${error.hostname ?? "unknown"}`;
+		} else {
+			message = error?.message ?? String(error);
+		}
+		return { status: "error", message };
+	} finally {
+		try {
+			await client?.end();
+		} catch {
+			// ignore disconnect errors
+		}
+	}
+}