@usequark/quark-core 2.5.4

package/src/db.test.js

@@ -0,0 +1,365 @@
+import assert from "node:assert/strict";
+import { copyFile, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { pathToFileURL } from "node:url";
+
+import {
+	createPrismaClient,
+	getConnectionString,
+	getPoolConfig,
+	pingDatabase,
+} from "./db.js";
+
+// ---------------------------------------------------------------------------
+// getConnectionString
+// ---------------------------------------------------------------------------
+
+test("db - getConnectionString returns DATABASE_URL when set", () => {
+	const orig = process.env.DATABASE_URL;
+	try {
+		process.env.DATABASE_URL = "postgresql://user:pass@host:5432/db";
+		const conn = getConnectionString();
+		assert.equal(conn, "postgresql://user:pass@host:5432/db");
+	} finally {
+		if (orig === undefined) delete process.env.DATABASE_URL;
+		else process.env.DATABASE_URL = orig;
+	}
+});
+
+test("db - getConnectionString assembles from POSTGRES_* vars", () => {
+	const backup = {};
+	const vars = [
+		"DATABASE_URL",
+		"POSTGRES_USER",
+		"POSTGRES_PASSWORD",
+		"POSTGRES_HOST",
+		"POSTGRES_PORT",
+		"POSTGRES_DB",
+	];
+	for (const v of vars) {
+		backup[v] = process.env[v];
+		delete process.env[v];
+	}
+	try {
+		process.env.POSTGRES_USER = "alice";
+		process.env.POSTGRES_PASSWORD = "secret";
+		process.env.POSTGRES_HOST = "db.example.com";
+		process.env.POSTGRES_PORT = "5433";
+		process.env.POSTGRES_DB = "mydb";
+		const conn = getConnectionString();
+		assert.equal(
+			conn,
+			"postgresql://alice:secret@db.example.com:5433/mydb?schema=public",
+		);
+	} finally {
+		for (const v of vars) {
+			if (backup[v] === undefined) delete process.env[v];
+			else process.env[v] = backup[v];
+		}
+	}
+});
+
+test("db - getConnectionString defaults host/port when POSTGRES_HOST/PORT not set", () => {
+	const backup = {};
+	const vars = [
+		"DATABASE_URL",
+		"POSTGRES_USER",
+		"POSTGRES_PASSWORD",
+		"POSTGRES_DB",
+		"POSTGRES_HOST",
+		"POSTGRES_PORT",
+	];
+	for (const v of vars) {
+		backup[v] = process.env[v];
+		delete process.env[v];
+	}
+	try {
+		process.env.POSTGRES_USER = "u";
+		process.env.POSTGRES_PASSWORD = "p";
+		process.env.POSTGRES_DB = "d";
+		const conn = getConnectionString();
+		assert.equal(conn, "postgresql://u:p@localhost:5432/d?schema=public");
+	} finally {
+		for (const v of vars) {
+			if (backup[v] === undefined) delete process.env[v];
+			else process.env[v] = backup[v];
+		}
+	}
+});
+
+test("db - getConnectionString throws when throwOnMissing=true and vars missing", () => {
+	const backup = {};
+	const vars = [
+		"DATABASE_URL",
+		"POSTGRES_USER",
+		"POSTGRES_PASSWORD",
+		"POSTGRES_DB",
+	];
+	for (const v of vars) {
+		backup[v] = process.env[v];
+		delete process.env[v];
+	}
+	try {
+		assert.throws(
+			() => getConnectionString({ throwOnMissing: true }),
+			/Missing required database environment variables/,
+		);
+	} finally {
+		for (const v of vars) {
+			if (backup[v] === undefined) delete process.env[v];
+			else process.env[v] = backup[v];
+		}
+	}
+});
+
+test("db - getConnectionString returns placeholder when throwOnMissing=false and vars missing", () => {
+	const backup = {};
+	const vars = [
+		"DATABASE_URL",
+		"POSTGRES_USER",
+		"POSTGRES_PASSWORD",
+		"POSTGRES_DB",
+	];
+	for (const v of vars) {
+		backup[v] = process.env[v];
+		delete process.env[v];
+	}
+	try {
+		const conn = getConnectionString({ throwOnMissing: false });
+		assert.ok(conn.includes("placeholder"));
+	} finally {
+		for (const v of vars) {
+			if (backup[v] === undefined) delete process.env[v];
+			else process.env[v] = backup[v];
+		}
+	}
+});
+
+// ---------------------------------------------------------------------------
+// getPoolConfig
+// ---------------------------------------------------------------------------
+
+test("db - getPoolConfig returns production defaults in production", () => {
+	const orig = process.env.NODE_ENV;
+	const origMax = process.env.DB_POOL_MAX;
+	const origIdle = process.env.DB_POOL_IDLE_TIMEOUT;
+	const origConn = process.env.DB_POOL_CONNECTION_TIMEOUT;
+	try {
+		process.env.NODE_ENV = "production";
+		delete process.env.DB_POOL_MAX;
+		delete process.env.DB_POOL_IDLE_TIMEOUT;
+		delete process.env.DB_POOL_CONNECTION_TIMEOUT;
+		const config = getPoolConfig();
+		assert.equal(config.max, 10);
+		assert.equal(config.idleTimeoutMillis, 30_000);
+		assert.equal(config.connectionTimeoutMillis, 5_000);
+	} finally {
+		if (orig === undefined) delete process.env.NODE_ENV;
+		else process.env.NODE_ENV = orig;
+		if (origMax === undefined) delete process.env.DB_POOL_MAX;
+		else process.env.DB_POOL_MAX = origMax;
+		if (origIdle === undefined) delete process.env.DB_POOL_IDLE_TIMEOUT;
+		else process.env.DB_POOL_IDLE_TIMEOUT = origIdle;
+		if (origConn === undefined) delete process.env.DB_POOL_CONNECTION_TIMEOUT;
+		else process.env.DB_POOL_CONNECTION_TIMEOUT = origConn;
+	}
+});
+
+test("db - getPoolConfig returns dev defaults in development", () => {
+	const orig = process.env.NODE_ENV;
+	const origMax = process.env.DB_POOL_MAX;
+	try {
+		process.env.NODE_ENV = "development";
+		delete process.env.DB_POOL_MAX;
+		const config = getPoolConfig();
+		assert.equal(config.max, 5);
+	} finally {
+		if (orig === undefined) delete process.env.NODE_ENV;
+		else process.env.NODE_ENV = orig;
+		if (origMax === undefined) delete process.env.DB_POOL_MAX;
+		else process.env.DB_POOL_MAX = origMax;
+	}
+});
+
+test("db - getPoolConfig respects DB_POOL_MAX override", () => {
+	const orig = process.env.DB_POOL_MAX;
+	try {
+		process.env.DB_POOL_MAX = "20";
+		const config = getPoolConfig();
+		assert.equal(config.max, 20);
+	} finally {
+		if (orig === undefined) delete process.env.DB_POOL_MAX;
+		else process.env.DB_POOL_MAX = orig;
+	}
+});
+
+// ---------------------------------------------------------------------------
+// createPrismaClient
+// ---------------------------------------------------------------------------
+
+test("db - createPrismaClient returns a proxy", () => {
+	class FakeClient {
+		constructor(opts) {
+			this.opts = opts;
+		}
+		get user() {
+			return { findMany: () => [] };
+		}
+	}
+
+	const client = createPrismaClient(FakeClient);
+	// Proxy should be an object
+	assert.equal(typeof client, "object");
+	delete globalThis.__quark_prisma_FakeClient;
+});
+
+test("db - createPrismaClient defers instantiation until first access", () => {
+	let constructed = false;
+	class TrackingClient {
+		constructor() {
+			constructed = true;
+		}
+		get ready() {
+			return true;
+		}
+	}
+
+	const client = createPrismaClient(TrackingClient);
+	assert.equal(constructed, false, "should not construct at creation time");
+
+	// Access a property to trigger construction
+	const _ = client.ready;
+	assert.equal(constructed, true, "should construct on first access");
+	delete globalThis.__quark_prisma_TrackingClient;
+});
+
+test("db - createPrismaClient passes adapterOptions to constructor", () => {
+	let receivedOpts;
+	class OptsClient {
+		constructor(opts) {
+			receivedOpts = opts;
+		}
+		get check() {
+			return true;
+		}
+	}
+
+	// Reset global
+	delete globalThis.__quark_prisma_OptsClient;
+
+	const client = createPrismaClient(OptsClient, {
+		adapterOptions: { connectionString: "test" },
+	});
+	const _ = client.check;
+	assert.deepEqual(receivedOpts, { connectionString: "test" });
+	delete globalThis.__quark_prisma_OptsClient;
+});
+
+test("db - createPrismaClient keeps a separate slot per client class", () => {
+	class AlphaClient {
+		get marker() {
+			return "alpha";
+		}
+	}
+	class BetaClient {
+		get marker() {
+			return "beta";
+		}
+	}
+
+	try {
+		const alpha = createPrismaClient(AlphaClient);
+		const beta = createPrismaClient(BetaClient);
+		assert.equal(alpha.marker, "alpha");
+		assert.equal(beta.marker, "beta");
+	} finally {
+		delete globalThis.__quark_prisma_AlphaClient;
+		delete globalThis.__quark_prisma_BetaClient;
+	}
+});
+
+test("db - createPrismaClient honours an explicit globalKey", () => {
+	const globalKey = "__quark_prisma_test_explicit";
+	class FirstClient {
+		get marker() {
+			return 1;
+		}
+	}
+	class SecondClient {
+		get marker() {
+			return 2;
+		}
+	}
+
+	try {
+		const first = createPrismaClient(FirstClient, { globalKey });
+		assert.equal(first.marker, 1);
+
+		// Same explicit slot → the existing client wins (singleton semantics)
+		const second = createPrismaClient(SecondClient, { globalKey });
+		assert.equal(second.marker, 1);
+	} finally {
+		delete globalThis[globalKey];
+	}
+});
+
+test("db - createPrismaClient supports a named slot for same-named classes", () => {
+	class PrismaClient {
+		get marker() {
+			return "primary";
+		}
+	}
+	class OtherPrismaClient {
+		get marker() {
+			return "secondary";
+		}
+	}
+
+	try {
+		const primary = createPrismaClient(PrismaClient, { name: "primary" });
+		const secondary = createPrismaClient(OtherPrismaClient, {
+			name: "secondary",
+		});
+		assert.equal(primary.marker, "primary");
+		assert.equal(secondary.marker, "secondary");
+	} finally {
+		delete globalThis.__quark_prisma_primary;
+		delete globalThis.__quark_prisma_secondary;
+	}
+});
+
+// ---------------------------------------------------------------------------
+// pingDatabase
+// ---------------------------------------------------------------------------
+
+test("db - pingDatabase reports ok or error without throwing", async () => {
+	// This test verifies the error-handling path.  In most CI environments
+	// pg IS installed, so we test the general error handling by verifying
+	// the function never throws.
+	const result = await pingDatabase({ timeout: 1000 });
+	assert.ok(result);
+	assert.ok(["ok", "error"].includes(result.status));
+	if (result.status === "error") {
+		assert.equal(typeof result.message, "string");
+	}
+});
+
+// Copy db.js to a directory with no node_modules so `pg` is unresolvable and
+// prove that the optional peer dependency surfaces as an error result rather
+// than an import-time/build-time failure.
+test("db - pingDatabase reports a missing pg install without throwing", async () => {
+	const dir = await mkdtemp(join(tmpdir(), "quark-db-"));
+	try {
+		await copyFile(new URL("./db.js", import.meta.url), join(dir, "db.js"));
+
+		const isolated = await import(pathToFileURL(join(dir, "db.js")).href);
+		const result = await isolated.pingDatabase({ timeout: 500 });
+
+		assert.equal(result.status, "error");
+		assert.match(result.message, /pg is not installed/);
+	} finally {
+		await rm(dir, { recursive: true, force: true });
+	}
+});

package/src/email-templates.js

@@ -0,0 +1,134 @@
+/**
+ * @techstream/quark-core - Email Templates
+ *
+ * Reusable HTML email templates with plain-text fallbacks.
+ * Each template function returns { subject, html, text }.
+ */
+
+/**
+ * Escape HTML entities to prevent XSS in user-provided values
+ * @param {string} str
+ * @returns {string}
+ */
+function escapeHtml(str) {
+	return String(str)
+		.replace(/&/g, "&")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/"/g, "&quot;")
+		.replace(/'/g, "&#039;");
+}
+
+/**
+ * Shared outer layout for all emails
+ * @param {string} body - Inner HTML content
+ * @returns {string}
+ */
+function layout(body) {
+	return `<!DOCTYPE html>
+<html lang="en">
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"></head>
+<body style="margin:0;padding:0;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;background:#f4f4f5">
+  <table width="100%" cellpadding="0" cellspacing="0" style="padding:32px 16px">
+    <tr><td align="center">
+      <table width="100%" style="max-width:560px;background:#fff;border-radius:8px;border:1px solid #e4e4e7;padding:32px">
+        <tr><td>${body}</td></tr>
+      </table>
+      <p style="color:#a1a1aa;font-size:12px;margin-top:24px">
+        You received this email because an account was created with this address.
+      </p>
+    </td></tr>
+  </table>
+</body>
+</html>`;
+}
+
+/**
+ * Welcome email - sent after user registration
+ *
+ * @param {{ name?: string, appName?: string, loginUrl?: string }} data
+ * @returns {{ subject: string, html: string, text: string }}
+ */
+export function welcomeEmail(data = {}) {
+	const name = data.name ? escapeHtml(data.name) : "there";
+	const appName = data.appName || "Quark";
+	const loginUrl = data.loginUrl || "";
+
+	const buttonHtml = loginUrl
+		? `<p style="text-align:center;margin:24px 0">
+        <a href="${escapeHtml(loginUrl)}" style="display:inline-block;padding:12px 24px;background:#18181b;color:#fff;text-decoration:none;border-radius:6px;font-weight:500">
+          Sign in to ${escapeHtml(appName)}
+        </a>
+      </p>`
+		: "";
+
+	const html = layout(`
+    <h1 style="margin:0 0 16px;font-size:24px;color:#18181b">Welcome, ${name}!</h1>
+    <p style="color:#3f3f46;line-height:1.6;margin:0 0 16px">
+      Your account has been created successfully. You can now sign in and start using ${escapeHtml(appName)}.
+    </p>
+    ${buttonHtml}
+    <p style="color:#71717a;font-size:14px;margin:0">
+      If you didn't create this account, you can safely ignore this email.
+    </p>
+  `);
+
+	const text = [
+		`Welcome, ${data.name || "there"}!`,
+		"",
+		`Your account has been created successfully. You can now sign in and start using ${appName}.`,
+		...(loginUrl ? ["", `Sign in: ${loginUrl}`] : []),
+		"",
+		"If you didn't create this account, you can safely ignore this email.",
+	].join("\n");
+
+	return { subject: `Welcome to ${appName}!`, html, text };
+}
+
+/**
+ * Password reset email - sent when user requests a reset
+ *
+ * @param {{ name?: string, resetUrl: string, appName?: string, expiresIn?: string }} data
+ * @returns {{ subject: string, html: string, text: string }}
+ */
+export function passwordResetEmail(data) {
+	if (!data?.resetUrl) {
+		throw new Error("resetUrl is required for password reset email");
+	}
+
+	const name = data.name ? escapeHtml(data.name) : "there";
+	const appName = data.appName || "Quark";
+	const expiresIn = data.expiresIn || "1 hour";
+
+	const html = layout(`
+    <h1 style="margin:0 0 16px;font-size:24px;color:#18181b">Reset your password</h1>
+    <p style="color:#3f3f46;line-height:1.6;margin:0 0 16px">
+      Hi ${name}, we received a request to reset your ${escapeHtml(appName)} password.
+    </p>
+    <p style="text-align:center;margin:24px 0">
+      <a href="${escapeHtml(data.resetUrl)}" style="display:inline-block;padding:12px 24px;background:#18181b;color:#fff;text-decoration:none;border-radius:6px;font-weight:500">
+        Reset password
+      </a>
+    </p>
+    <p style="color:#71717a;font-size:14px;margin:0 0 8px">
+      This link will expire in ${escapeHtml(expiresIn)}.
+    </p>
+    <p style="color:#71717a;font-size:14px;margin:0">
+      If you didn't request this, you can safely ignore this email. Your password will not be changed.
+    </p>
+  `);
+
+	const text = [
+		`Reset your password`,
+		"",
+		`Hi ${data.name || "there"}, we received a request to reset your ${appName} password.`,
+		"",
+		`Reset your password: ${data.resetUrl}`,
+		"",
+		`This link will expire in ${expiresIn}.`,
+		"",
+		"If you didn't request this, you can safely ignore this email. Your password will not be changed.",
+	].join("\n");
+
+	return { subject: `Reset your ${appName} password`, html, text };
+}

package/src/email-templates.test.js

@@ -0,0 +1,124 @@
+import assert from "node:assert";
+import { test } from "node:test";
+import { passwordResetEmail, welcomeEmail } from "./email-templates.js";
+
+test("welcomeEmail", async (t) => {
+	await t.test("returns subject, html, and text", () => {
+		const result = welcomeEmail({});
+		assert.ok(result.subject);
+		assert.ok(result.html);
+		assert.ok(result.text);
+	});
+
+	await t.test("uses default app name in subject", () => {
+		const result = welcomeEmail({});
+		assert.strictEqual(result.subject, "Welcome to Quark!");
+	});
+
+	await t.test("uses custom app name in subject", () => {
+		const result = welcomeEmail({ appName: "MyApp" });
+		assert.strictEqual(result.subject, "Welcome to MyApp!");
+	});
+
+	await t.test("includes user name in html when provided", () => {
+		const result = welcomeEmail({ name: "Alice" });
+		assert.ok(result.html.includes("Alice"));
+		assert.ok(result.text.includes("Alice"));
+	});
+
+	await t.test("uses fallback greeting when no name provided", () => {
+		const result = welcomeEmail({});
+		assert.ok(result.html.includes("there"));
+		assert.ok(result.text.includes("there"));
+	});
+
+	await t.test("includes login URL when provided", () => {
+		const result = welcomeEmail({ loginUrl: "https://app.test/login" });
+		assert.ok(result.html.includes("https://app.test/login"));
+		assert.ok(result.text.includes("https://app.test/login"));
+	});
+
+	await t.test("omits sign-in button when no login URL", () => {
+		const result = welcomeEmail({});
+		assert.ok(!result.html.includes("Sign In"));
+	});
+
+	await t.test("escapes HTML in user name", () => {
+		const result = welcomeEmail({ name: "<script>alert('xss')</script>" });
+		assert.ok(!result.html.includes("<script>"));
+		assert.ok(result.html.includes("&lt;script&gt;"));
+	});
+
+	await t.test("wraps content in html layout", () => {
+		const result = welcomeEmail({});
+		assert.ok(result.html.includes("<!DOCTYPE html>"));
+		assert.ok(result.html.includes("</html>"));
+	});
+});
+
+test("passwordResetEmail", async (t) => {
+	const validArgs = { resetUrl: "https://app.test/reset?token=abc123" };
+
+	await t.test("returns subject, html, and text", () => {
+		const result = passwordResetEmail(validArgs);
+		assert.ok(result.subject);
+		assert.ok(result.html);
+		assert.ok(result.text);
+	});
+
+	await t.test("throws when resetUrl is missing", () => {
+		assert.throws(() => passwordResetEmail({}), /resetUrl is required/);
+	});
+
+	await t.test("includes reset URL in html and text", () => {
+		const result = passwordResetEmail(validArgs);
+		assert.ok(result.html.includes(validArgs.resetUrl));
+		assert.ok(result.text.includes(validArgs.resetUrl));
+	});
+
+	await t.test("uses default app name", () => {
+		const result = passwordResetEmail(validArgs);
+		assert.ok(result.subject.includes("Quark"));
+	});
+
+	await t.test("uses custom app name", () => {
+		const result = passwordResetEmail({ ...validArgs, appName: "MyApp" });
+		assert.ok(result.subject.includes("MyApp"));
+	});
+
+	await t.test("includes user name when provided", () => {
+		const result = passwordResetEmail({ ...validArgs, name: "Bob" });
+		assert.ok(result.html.includes("Bob"));
+		assert.ok(result.text.includes("Bob"));
+	});
+
+	await t.test("uses default expiry time", () => {
+		const result = passwordResetEmail(validArgs);
+		assert.ok(result.html.includes("1 hour"));
+		assert.ok(result.text.includes("1 hour"));
+	});
+
+	await t.test("uses custom expiry time", () => {
+		const result = passwordResetEmail({
+			...validArgs,
+			expiresIn: "30 minutes",
+		});
+		assert.ok(result.html.includes("30 minutes"));
+		assert.ok(result.text.includes("30 minutes"));
+	});
+
+	await t.test("escapes HTML in user name", () => {
+		const result = passwordResetEmail({
+			...validArgs,
+			name: '<img src=x onerror="alert(1)">',
+		});
+		assert.ok(!result.html.includes("<img"));
+		assert.ok(result.html.includes("&lt;img"));
+	});
+
+	await t.test("wraps content in html layout", () => {
+		const result = passwordResetEmail(validArgs);
+		assert.ok(result.html.includes("<!DOCTYPE html>"));
+		assert.ok(result.html.includes("</html>"));
+	});
+});