emdash 0.5.0 → 0.6.0

package/src/database/connection.ts

@@ -1,6 +1,7 @@
 import BetterSqlite3 from "better-sqlite3";
 import { Kysely, SqliteDialect } from "kysely";
 
+import { kyselyLogOption } from "./instrumentation.js";
 import type { Database } from "./types.js";
 
 export interface DatabaseConfig {
@@ -18,6 +19,23 @@ export class EmDashDatabaseError extends Error {
 	}
 }
 
+/**
+ * Returns a helpful, actionable message when better-sqlite3's native binary
+ * was compiled against a different Node.js version than the one running. This
+ * happens after upgrading Node without rebuilding native deps.
+ *
+ * Returns null if the error is not a NODE_MODULE_VERSION mismatch.
+ */
+export function formatNativeModuleVersionError(error: unknown): string | null {
+	const message = error instanceof Error ? error.message : String(error);
+	if (!message.includes("NODE_MODULE_VERSION")) return null;
+	return (
+		"better-sqlite3's native binary was compiled against a different Node.js version. " +
+		"Rebuild it with `pnpm rebuild better-sqlite3` (or `npm rebuild better-sqlite3`), " +
+		"or reinstall dependencies with your current Node.js version."
+	);
+}
+
 /**
  * Creates a Kysely database instance
  * Supports:
@@ -45,7 +63,7 @@ export function createDatabase(config: DatabaseConfig): Kysely<Database> {
 				database: sqlite,
 			});
 
-			return new Kysely<Database>({ dialect });
+			return new Kysely<Database>({ dialect, log: kyselyLogOption() });
 		}
 
 		// Handle libSQL (Turso)
@@ -62,6 +80,10 @@ export function createDatabase(config: DatabaseConfig): Kysely<Database> {
 		if (error instanceof EmDashDatabaseError) {
 			throw error;
 		}
+		const nativeVersionHint = formatNativeModuleVersionError(error);
+		if (nativeVersionHint) {
+			throw new EmDashDatabaseError(nativeVersionHint, error);
+		}
 		throw new EmDashDatabaseError("Failed to create database", error);
 	}
 }

package/src/database/instrumentation.ts

@@ -0,0 +1,98 @@
+/**
+ * Query instrumentation
+ *
+ * Dev/test-only: captures every Kysely query executed inside a request,
+ * tagged with the route, method, and a caller-supplied phase (e.g. "cold"
+ * or "warm"). Events are emitted as prefixed NDJSON on stdout so the
+ * harness can capture them from both Node and workerd — workerd has no
+ * filesystem access, but `console.log` is portable.
+ *
+ * The recorder lives on the request context (AsyncLocalStorage). The
+ * Kysely `log` hook reads the recorder at query time and appends an
+ * event. When no recorder is attached, the hook is a null check.
+ */
+
+import type { LogEvent, Logger } from "kysely";
+
+import { getRequestContext } from "../request-context.js";
+
+export const QUERY_LOG_ENV = "EMDASH_QUERY_LOG";
+export const QUERY_LOG_PREFIX = "[emdash-query-log]";
+
+export interface QueryEvent {
+	sql: string;
+	params: readonly unknown[];
+	durationMs: number;
+	route: string;
+	method: string;
+	phase: string;
+}
+
+export interface QueryRecorder {
+	events: QueryEvent[];
+	route: string;
+	method: string;
+	phase: string;
+}
+
+export function createRecorder(route: string, method: string, phase: string): QueryRecorder {
+	return { events: [], route, method, phase };
+}
+
+export function recordEvent(
+	rec: QueryRecorder,
+	sql: string,
+	params: readonly unknown[],
+	durationMs: number,
+): void {
+	rec.events.push({
+		sql,
+		params,
+		durationMs,
+		route: rec.route,
+		method: rec.method,
+		phase: rec.phase,
+	});
+}
+
+/**
+ * Emit all events from a recorder as prefixed NDJSON on stdout. The
+ * harness pipes the child's stdout, filters lines beginning with
+ * QUERY_LOG_PREFIX, and writes them to its own file. Using stdout means
+ * the sink works uniformly in Node and in workerd (which has no fs).
+ */
+export function flushRecorder(rec: QueryRecorder): void {
+	if (rec.events.length === 0) return;
+	for (const e of rec.events) {
+		console.log(`${QUERY_LOG_PREFIX} ${JSON.stringify(e)}`);
+	}
+}
+
+/**
+ * Whether query instrumentation is enabled. Read at Kysely construction
+ * time and middleware entry — the env var is a process-lifetime flag, not
+ * per-request. Gated via `process.env` so adapters that ship env through
+ * to the worker (e.g. Miniflare via wrangler.jsonc `vars` or host env
+ * pass-through) can enable it at runtime.
+ */
+export function isInstrumentationEnabled(): boolean {
+	return Boolean(
+		typeof process !== "undefined" && process.env && process.env[QUERY_LOG_ENV] === "1",
+	);
+}
+
+function kyselyLog(event: LogEvent): void {
+	if (event.level !== "query") return;
+	const rec = getRequestContext()?.queryRecorder;
+	if (!rec) return;
+	recordEvent(rec, event.query.sql, event.query.parameters, event.queryDurationMillis);
+}
+
+/**
+ * Returns a Kysely `log` option when instrumentation is enabled, or undefined.
+ * Pass as `new Kysely({ dialect, log: kyselyLogOption() })` so disabled mode
+ * has zero overhead — Kysely skips query timing entirely when `log` is absent.
+ */
+export function kyselyLogOption(): Logger | undefined {
+	return isInstrumentationEnabled() ? kyselyLog : undefined;
+}

package/src/db/adapters.ts

@@ -33,6 +33,21 @@ export interface DatabaseDescriptor {
 	entrypoint: string;
 	config: unknown;
 	type: DatabaseDialectType;
+	/**
+	 * When true, the adapter's runtime entrypoint MUST export a named
+	 * `createRequestScopedDb` function matching the signature declared in
+	 * `virtual:emdash/dialect`. The virtual-module generator re-exports it
+	 * by name, so a missing export becomes a build-time bundler error.
+	 *
+	 * The function is called once per request and decides — based on its own
+	 * runtime config (e.g. whether the user opted into D1 sessions) — whether
+	 * to return a per-request Kysely or null. Use this for features like D1
+	 * read-replica sessions, bookmark cookies, or any per-request DB handle.
+	 *
+	 * When false or absent, the generator emits a stub that returns null and
+	 * the middleware takes its default (singleton) path.
+	 */
+	supportsRequestScope?: boolean;
 }
 
 export interface SqliteConfig {