@c9up/atlas 0.1.19 → 0.2.1

package/src/Transaction.ts

@@ -5,55 +5,233 @@
  */
 
 import { randomBytes } from "node:crypto";
+import { EventEmitter } from "node:events";
 import type { TransactionOptions } from "./adapters/NapiDbAdapter.js";
 import type { DatabaseConnection } from "./BaseRepository.js";
+import {
+	makeTransactionQueryBuilders,
+	type TransactionQueryBuilders,
+} from "./query/DatabaseQueryBuilder.js";
+import { getAtlasDialect } from "./query/native.js";
 import {
 	isTransactionClient,
 	TRANSACTION_BRAND,
 } from "./utils/transactionBrand.js";
 
-export interface TransactionClient extends DatabaseConnection {
+/** A post-commit / post-rollback side effect (Lucid `trx.after(...)`). */
+export type AfterHook = () => void | Promise<void>;
+
+export interface TransactionClient
+	extends Omit<DatabaseConnection, "query">,
+		TransactionQueryBuilders {
 	commit(): Promise<void>;
 	rollback(): Promise<void>;
+	/**
+	 * Register a side effect to run AFTER the transaction is durable (Lucid
+	 * `trx.after('commit' | 'rollback', cb)`). A `commit` hook fires only once the
+	 * ROOT transaction commits — inside a nested (SAVEPOINT) transaction it is
+	 * forwarded to the parent, so a later outer rollback never runs it. Errors
+	 * thrown by a hook are swallowed (the caller already saw the transaction
+	 * succeed).
+	 */
+	after(event: "commit" | "rollback", cb: AfterHook): void;
+	/**
+	 * Subscribe to the client's `commit`/`rollback` EventEmitter (Lucid — the trx
+	 * client IS a Node EventEmitter). These are SYNCHRONOUS, pre-hook notifications
+	 * fired the moment this client commits/rolls back — DISTINCT from {@link after},
+	 * which are durable post-commit hooks that forward to the root when nested.
+	 */
+	on(event: "commit" | "rollback", cb: AfterHook): this;
+	/** One-shot {@link on} (Lucid/Node EventEmitter `once`). */
+	once(event: "commit" | "rollback", cb: AfterHook): this;
+	/** Remove a listener added via {@link on}/{@link once} (Node EventEmitter `off`). */
+	off(event: "commit" | "rollback", cb: AfterHook): this;
+	/**
+	 * Open a nested transaction (Lucid `const sp = await trx.transaction()`),
+	 * implemented as a SAVEPOINT on the same pinned connection. Managed when given
+	 * a callback (auto RELEASE / ROLLBACK TO), manual otherwise. Works on all three
+	 * dialects — MySQL's SAVEPOINT statements (which can't be prepared) route
+	 * through the text protocol in the napi layer.
+	 */
+	transaction(): Promise<TransactionClient>;
+	transaction(options: TransactionOptions): Promise<TransactionClient>;
+	transaction<T>(
+		callback: (trx: TransactionClient) => Promise<T> | T,
+		options?: TransactionOptions,
+	): Promise<T>;
 	readonly isNested: boolean;
 	readonly [TRANSACTION_BRAND]: true;
 }
 
-export async function transaction<T>(
-	db: DatabaseConnection,
+/**
+ * Build the overloaded `transaction()` method for a client. Managed when given a
+ * callback (auto RELEASE / ROLLBACK TO), manual otherwise — both open a SAVEPOINT
+ * on `getParent()`. The impl signature is deliberately broader than the overloads.
+ */
+export function makeNestedTransactionFn(getParent: () => TransactionClient) {
+	function tx(): Promise<TransactionClient>;
+	function tx(options: TransactionOptions): Promise<TransactionClient>;
+	function tx<T>(
+		callback: (trx: TransactionClient) => Promise<T> | T,
+		options?: TransactionOptions,
+	): Promise<T>;
+	function tx(
+		arg1?:
+			| TransactionOptions
+			| ((trx: TransactionClient) => Promise<unknown> | unknown),
+		arg2?: TransactionOptions,
+	): Promise<unknown> {
+		const parent = getParent();
+		const callback = typeof arg1 === "function" ? arg1 : undefined;
+		const options = typeof arg1 === "function" ? arg2 : arg1;
+		return callback
+			? runManagedSavepoint(parent, callback, options)
+			: openSavepoint(parent);
+	}
+	return tx;
+}
+
+/** Managed nested savepoint: open, run the callback, RELEASE on success / ROLLBACK TO on throw. */
+async function runManagedSavepoint<T>(
+	parent: TransactionClient,
 	callback: (trx: TransactionClient) => Promise<T> | T,
-	options?: TransactionOptions,
+	_options?: TransactionOptions,
 ): Promise<T> {
-	if (isTransactionClient(db)) {
-		const name = `sp_${randomBytes(6).toString("hex")}`;
-		await db.execute(`SAVEPOINT ${name}`, []);
-
-		const trx: TransactionClient = {
-			execute: db.execute.bind(db),
-			query: db.query.bind(db),
-			async commit() {
-				await db.execute(`RELEASE SAVEPOINT ${name}`, []);
-			},
-			async rollback() {
-				await db.execute(`ROLLBACK TO SAVEPOINT ${name}`, []);
-			},
-			isNested: true,
-			[TRANSACTION_BRAND]: true,
-		};
-
+	const sp = await openSavepoint(parent);
+	try {
+		const result = await callback(sp);
+		await sp.commit();
+		return result;
+	} catch (err) {
 		try {
-			const result = await callback(trx);
-			await trx.commit();
-			return result;
-		} catch (err) {
+			await sp.rollback();
+		} catch {
+			/* best-effort */
+		}
+		throw err;
+	}
+}
+
+/**
+ * Open a SAVEPOINT-backed nested transaction client on `parent`. Shared by the
+ * standalone {@link transaction} helper, `trx.transaction()`, and the napi pinned
+ * client. Commit RELEASEs the savepoint and forwards hooks to the parent (a
+ * nested commit isn't durable until the root commits); rollback does ROLLBACK TO
+ * + RELEASE and fires the local rollback hooks.
+ */
+export async function openSavepoint(
+	parent: TransactionClient,
+): Promise<TransactionClient> {
+	const name = `sp_${randomBytes(6).toString("hex")}`;
+	await parent.execute(`SAVEPOINT ${name}`, []);
+	const commitHooks: AfterHook[] = [];
+	const rollbackHooks: AfterHook[] = [];
+	const evt = makeTrxEvents();
+	const base = {
+		execute: parent.execute.bind(parent),
+		query: parent.query.bind(parent),
+		async commit(): Promise<void> {
+			await parent.execute(`RELEASE SAVEPOINT ${name}`, []);
+			evt.emit("commit"); // synchronous EventEmitter notification (this savepoint)
+			for (const hook of commitHooks) parent.after("commit", hook);
+			for (const hook of rollbackHooks) parent.after("rollback", hook);
+		},
+		async rollback(): Promise<void> {
+			await parent.execute(`ROLLBACK TO SAVEPOINT ${name}`, []);
 			try {
-				await trx.rollback();
+				await parent.execute(`RELEASE SAVEPOINT ${name}`, []);
 			} catch {
-				/* best-effort */
+				/* best-effort — the savepoint is already logically unwound */
 			}
-			throw err;
+			evt.emit("rollback");
+			await runAfterHooks(rollbackHooks);
+		},
+		after(event: "commit" | "rollback", cb: AfterHook): void {
+			(event === "commit" ? commitHooks : rollbackHooks).push(cb);
+		},
+		on: evt.on,
+		once: evt.once,
+		off: evt.off,
+		isNested: true,
+		[TRANSACTION_BRAND]: true as const,
+	};
+	const trx: TransactionClient = Object.assign(
+		base,
+		makeTransactionQueryBuilders(base, getAtlasDialect()),
+		{ transaction: makeNestedTransactionFn(() => trx) },
+	);
+	return trx;
+}
+
+/**
+ * Run every registered after-hook, swallowing errors — a post-commit side
+ * effect must never surface a failure on a transaction the caller already saw
+ * commit (Lucid parity). Shared with the napi adapter's pinned-transaction path.
+ */
+export async function runAfterHooks(hooks: AfterHook[]): Promise<void> {
+	for (const hook of hooks) {
+		try {
+			await hook();
+		} catch {
+			/* swallowed — the transaction already succeeded */
 		}
 	}
+}
+
+/**
+ * The `on`/`once`/`off` EventEmitter surface for a transaction client, plus an
+ * internal `emit` the client fires at commit/rollback. Distinct from `after`
+ * hooks: these are synchronous, per-client, pre-hook notifications (Lucid — the
+ * trx client is a Node EventEmitter). `on`/`once`/`off` return the client for
+ * chaining via their `this` binding.
+ */
+export function makeTrxEvents(): {
+	on(
+		this: TransactionClient,
+		e: "commit" | "rollback",
+		cb: AfterHook,
+	): TransactionClient;
+	once(
+		this: TransactionClient,
+		e: "commit" | "rollback",
+		cb: AfterHook,
+	): TransactionClient;
+	off(
+		this: TransactionClient,
+		e: "commit" | "rollback",
+		cb: AfterHook,
+	): TransactionClient;
+	emit(e: "commit" | "rollback"): void;
+} {
+	const ee = new EventEmitter();
+	return {
+		on(e, cb) {
+			ee.on(e, cb);
+			return this;
+		},
+		once(e, cb) {
+			ee.once(e, cb);
+			return this;
+		},
+		off(e, cb) {
+			ee.off(e, cb);
+			return this;
+		},
+		emit(e) {
+			ee.emit(e);
+		},
+	};
+}
+
+export async function transaction<T>(
+	db: DatabaseConnection,
+	callback: (trx: TransactionClient) => Promise<T> | T,
+	options?: TransactionOptions,
+): Promise<T> {
+	// Nested (the caller passed a live trx) → a SAVEPOINT-backed managed savepoint.
+	if (isTransactionClient(db)) {
+		return runManagedSavepoint(db, callback, options);
+	}
 
 	// Pinned interactive transaction (napi-backed): db.transaction() acquires ONE
 	// connection and issues BEGIN on it; the managed form commits on success /
@@ -68,18 +246,37 @@ export async function transaction<T>(
 
 	await db.execute("BEGIN", []);
 
-	const trx: TransactionClient = {
+	const commitHooks: AfterHook[] = [];
+	const rollbackHooks: AfterHook[] = [];
+	const evt = makeTrxEvents();
+
+	const base = {
 		execute: db.execute.bind(db),
 		query: db.query.bind(db),
 		async commit() {
 			await db.execute("COMMIT", []);
+			evt.emit("commit"); // synchronous EventEmitter notification
+			await runAfterHooks(commitHooks);
 		},
 		async rollback() {
 			await db.execute("ROLLBACK", []);
+			evt.emit("rollback");
+			await runAfterHooks(rollbackHooks);
+		},
+		after(event: "commit" | "rollback", cb: AfterHook) {
+			(event === "commit" ? commitHooks : rollbackHooks).push(cb);
 		},
+		on: evt.on,
+		once: evt.once,
+		off: evt.off,
 		isNested: false,
-		[TRANSACTION_BRAND]: true,
+		[TRANSACTION_BRAND]: true as const,
 	};
+	const trx: TransactionClient = Object.assign(
+		base,
+		makeTransactionQueryBuilders(base, getAtlasDialect()),
+		{ transaction: makeNestedTransactionFn(() => trx) },
+	);
 
 	try {
 		const result = await callback(trx);

package/src/adapters/NapiDbAdapter.ts

@@ -2,10 +2,54 @@
  * NapiDbAdapter — bridges the Rust atlas-db NAPI binding to Atlas.
  */
 
-import type { TransactionClient } from "../Transaction.js";
+import { emitDbQuery, hasDbQueryListeners } from "../events.js";
+import { makeTransactionQueryBuilders } from "../query/DatabaseQueryBuilder.js";
+import {
+	type AfterHook,
+	makeNestedTransactionFn,
+	makeTrxEvents,
+	runAfterHooks,
+	type TransactionClient,
+} from "../Transaction.js";
 import { dialectFromUrl } from "../utils/dialectFromUrl.js";
 import { TRANSACTION_BRAND } from "../utils/transactionBrand.js";
 
+/**
+ * JSON replacer for the napi boundary. `BigInt` throws in a plain
+ * `JSON.stringify` and a `Uint8Array`/`Buffer` serializes to a useless
+ * index-map, so both are wrapped in envelopes the Rust side decodes and binds
+ * losslessly: `{"$bigint": "123"}` → i64, `{"$bytes": "<base64>"}` → BLOB/BYTEA.
+ */
+function napiReplacer(_key: string, value: unknown): unknown {
+	if (typeof value === "bigint") return { $bigint: value.toString() };
+	if (value instanceof Uint8Array) {
+		return { $bytes: Buffer.from(value).toString("base64") };
+	}
+	return value;
+}
+
+/**
+ * JSON reviver for napi result sets. Rebuilds `{"$bytes": …}` envelopes (emitted
+ * by the Rust decoder for BLOB/BYTEA columns) into a `Uint8Array`. Integers
+ * beyond JS's safe range arrive pre-stringified by Rust — no precision loss — so
+ * they stay strings, matching the pg/mysql driver convention.
+ */
+function napiReviver(_key: string, value: unknown): unknown {
+	if (
+		typeof value === "object" &&
+		value !== null &&
+		!Array.isArray(value) &&
+		"$bytes" in value &&
+		Object.keys(value).length === 1
+	) {
+		const bytes = value.$bytes;
+		if (typeof bytes === "string") {
+			return Uint8Array.from(Buffer.from(bytes, "base64"));
+		}
+	}
+	return value;
+}
+
 /** One `(sql, params)` pair passed to `runInTransaction`. */
 export interface BatchStatement {
 	sql: string;
@@ -28,6 +72,48 @@ export interface TransactionOptions {
 	isolationLevel?: IsolationLevel;
 }
 
+/**
+ * Context a caller can attach to a statement so the `db:query` event can say
+ * where it came from. Optional everywhere — a connection that ignores it stays
+ * a valid `AsyncDatabaseConnection`, which is what lets test doubles skip it.
+ */
+export interface QueryMeta {
+	/** Entity class name, when the statement came from a repository/model. */
+	model?: string;
+	/** The call that produced it (`exec`, `first`, `paginate`, …). */
+	method?: string;
+	/** True for schema statements. */
+	ddl?: boolean;
+	/**
+	 * Force emission for this statement even when the connection has
+	 * `debug: false` — this is what `ModelQuery.debug()` sets.
+	 */
+	debug?: boolean;
+	/**
+	 * Arbitrary metadata attached to the `db:query` event (Adonis Lucid
+	 * `reporterData`) — request id, user id, feature flag, … — for listeners.
+	 */
+	reporterData?: Record<string, unknown>;
+	/**
+	 * Server-side statement timeout in ms (Lucid `timeout(ms, { cancel: true })`).
+	 * Routes to the driver's `statement_timeout` (Postgres) / `MAX_EXECUTION_TIME`
+	 * (MySQL SELECT) so the server aborts the query — not just the client race.
+	 */
+	serverTimeoutMs?: number;
+}
+
+/** Per-connection observability settings (Lucid's `debug` connection option). */
+export interface ObservabilityOptions {
+	/**
+	 * Emit a `db:query` event for every statement on this connection. Off by
+	 * default: it costs a timing pair per query, and nothing is emitted anyway
+	 * unless something subscribed via `onDbQuery`.
+	 */
+	debug?: boolean;
+	/** Connection name, reported on each event so multi-connection apps can tell them apart. */
+	connectionName?: string;
+}
+
 /** Async database connection backed by Rust (sqlx). */
 export interface AsyncDatabaseConnection {
 	/** The dialect this connection targets — derived from the URL scheme at connect time. */
@@ -35,8 +121,13 @@ export interface AsyncDatabaseConnection {
 	query<T = Record<string, unknown>>(
 		sql: string,
 		params?: unknown[],
+		meta?: QueryMeta,
 	): Promise<T[]>;
-	execute(sql: string, params?: unknown[]): Promise<{ rowsAffected: number }>;
+	execute(
+		sql: string,
+		params?: unknown[],
+		meta?: QueryMeta,
+	): Promise<{ rowsAffected: number }>;
 	/**
 	 * Run every statement in `batch` atomically inside a single sqlx transaction.
 	 * Either every statement commits or none do — used by MigrationRunner to
@@ -72,7 +163,7 @@ export interface AsyncDatabaseConnection {
 /** Shape of the NAPI ReamTransaction handle returned by `ReamDatabase.begin()`. */
 interface NapiReamTransaction {
 	query(sql: string, paramsJson: string): Promise<string>;
-	execute(sql: string, paramsJson: string): Promise<number>;
+	execute(sql: string, paramsJson: string): Promise<string>;
 	commit(): Promise<void>;
 	rollback(): Promise<void>;
 }
@@ -80,7 +171,19 @@ interface NapiReamTransaction {
 /** Shape of the NAPI ReamDatabase class. */
 interface NapiReamDatabase {
 	query(sql: string, paramsJson: string): Promise<string>;
-	execute(sql: string, paramsJson: string): Promise<number>;
+	execute(sql: string, paramsJson: string): Promise<string>;
+	/** query with a server-side statement timeout (Lucid `timeout(ms,{cancel:true})`). */
+	queryTimed(
+		sql: string,
+		paramsJson: string,
+		timeoutMs: number,
+	): Promise<string>;
+	/** execute with a server-side statement timeout (Postgres). */
+	executeTimed(
+		sql: string,
+		paramsJson: string,
+		timeoutMs: number,
+	): Promise<string>;
 	runInTransaction(batchJson: string): Promise<number>;
 	begin(isolationLevel?: string): Promise<NapiReamTransaction>;
 	close(): Promise<void>;
@@ -129,7 +232,9 @@ export async function createNapiConnection(
 	poolMax = 10,
 	pragmas?: Record<string, string | number>,
 	retry?: ConnectRetryOptions,
+	observability: ObservabilityOptions = {},
 ): Promise<AsyncDatabaseConnection> {
+	const { debug = false, connectionName } = observability;
 	// Throws with the underlying cause if the binary can't be loaded.
 	const native = await loadNativeDb();
 
@@ -184,30 +289,65 @@ export async function createNapiConnection(
 		isolationLevel?: IsolationLevel,
 	): Promise<TransactionClient> {
 		const native = await db.begin(isolationLevel);
-		return {
+		// Root (non-nested) transaction: after-hooks fire once the underlying
+		// COMMIT / ROLLBACK is durable (Lucid `trx.after(...)`), errors swallowed.
+		const commitHooks: AfterHook[] = [];
+		const rollbackHooks: AfterHook[] = [];
+		const evt = makeTrxEvents();
+		const base = {
 			async execute(
 				sql: string,
 				params: unknown[] = [],
-			): Promise<{ rowsAffected: number }> {
-				const affected = await native.execute(sql, JSON.stringify(params));
-				return { rowsAffected: affected };
+			): Promise<{ rowsAffected: number; lastInsertId?: number }> {
+				const json = await native.execute(
+					sql,
+					JSON.stringify(params, napiReplacer),
+				);
+				const r = JSON.parse(json);
+				return {
+					rowsAffected: Number(r.rows_affected),
+					lastInsertId:
+						r.last_insert_id == null ? undefined : Number(r.last_insert_id),
+				};
 			},
 			async query<T = Record<string, unknown>>(
 				sql: string,
 				params: unknown[] = [],
 			): Promise<T[]> {
-				const json = await native.query(sql, JSON.stringify(params));
-				return JSON.parse(json) as T[];
+				const json = await native.query(
+					sql,
+					JSON.stringify(params, napiReplacer),
+				);
+				return JSON.parse(json, napiReviver) as T[];
 			},
 			async commit(): Promise<void> {
 				await native.commit();
+				evt.emit("commit"); // synchronous EventEmitter notification (Lucid trx.on)
+				await runAfterHooks(commitHooks);
 			},
 			async rollback(): Promise<void> {
 				await native.rollback();
+				evt.emit("rollback");
+				await runAfterHooks(rollbackHooks);
 			},
+			after(event: "commit" | "rollback", cb: AfterHook): void {
+				(event === "commit" ? commitHooks : rollbackHooks).push(cb);
+			},
+			on: evt.on,
+			once: evt.once,
+			off: evt.off,
 			isNested: false,
-			[TRANSACTION_BRAND]: true,
+			[TRANSACTION_BRAND]: true as const,
 		};
+		// Lucid: the transaction client is also a query-builder entry point
+		// (trx.table()/from()/insertQuery()), routed through THIS pinned connection.
+		// `trx.transaction()` opens a SAVEPOINT-backed nested client on this one.
+		const client: TransactionClient = Object.assign(
+			base,
+			makeTransactionQueryBuilders(base, dialect),
+			{ transaction: makeNestedTransactionFn(() => client) },
+		);
+		return client;
 	}
 
 	// Lucid-compatible `transaction`: managed when given a callback (auto
@@ -240,29 +380,96 @@ export async function createNapiConnection(
 		}
 	}
 
+	/**
+	 * Run `fn`, emitting a `db:query` event around it when observation is on.
+	 *
+	 * The fast path is a single boolean pair: with no listeners, or with debug
+	 * off and no per-query override, this adds nothing but the check. The event
+	 * is emitted on failure too — a slow query that then throws is exactly the
+	 * one worth seeing.
+	 */
+	async function observed<T>(
+		sql: string,
+		params: unknown[],
+		meta: QueryMeta | undefined,
+		fn: () => Promise<T>,
+	): Promise<T> {
+		if (!(debug || meta?.debug) || !hasDbQueryListeners()) return fn();
+
+		const startedAt = performance.now();
+		try {
+			const result = await fn();
+			emitDbQuery({
+				sql,
+				bindings: params,
+				duration: performance.now() - startedAt,
+				connection: connectionName,
+				model: meta?.model,
+				method: meta?.method,
+				ddl: meta?.ddl,
+				inTransaction: false,
+				reporterData: meta?.reporterData,
+			});
+			return result;
+		} catch (error) {
+			emitDbQuery({
+				sql,
+				bindings: params,
+				duration: performance.now() - startedAt,
+				connection: connectionName,
+				model: meta?.model,
+				method: meta?.method,
+				ddl: meta?.ddl,
+				inTransaction: false,
+				error: error instanceof Error ? error : new Error(String(error)),
+				reporterData: meta?.reporterData,
+			});
+			throw error;
+		}
+	}
+
 	return {
 		dialect,
 		transaction,
 		async query<T = Record<string, unknown>>(
 			sql: string,
 			params: unknown[] = [],
+			meta?: QueryMeta,
 		): Promise<T[]> {
-			const json = await db.query(sql, JSON.stringify(params));
-			return JSON.parse(json) as T[];
+			return observed(sql, params, meta, async () => {
+				const paramsJson = JSON.stringify(params, napiReplacer);
+				const json =
+					meta?.serverTimeoutMs != null
+						? await db.queryTimed(sql, paramsJson, meta.serverTimeoutMs)
+						: await db.query(sql, paramsJson);
+				return JSON.parse(json, napiReviver) as T[];
+			});
 		},
 
 		async execute(
 			sql: string,
 			params: unknown[] = [],
-		): Promise<{ rowsAffected: number }> {
-			const affected = await db.execute(sql, JSON.stringify(params));
-			return { rowsAffected: affected };
+			meta?: QueryMeta,
+		): Promise<{ rowsAffected: number; lastInsertId?: number }> {
+			return observed(sql, params, meta, async () => {
+				const paramsJson = JSON.stringify(params, napiReplacer);
+				const json =
+					meta?.serverTimeoutMs != null
+						? await db.executeTimed(sql, paramsJson, meta.serverTimeoutMs)
+						: await db.execute(sql, paramsJson);
+				const r = JSON.parse(json);
+				return {
+					rowsAffected: Number(r.rows_affected),
+					lastInsertId:
+						r.last_insert_id == null ? undefined : Number(r.last_insert_id),
+				};
+			});
 		},
 
 		async runInTransaction(batch: readonly BatchStatement[]): Promise<number> {
 			// Rust side expects `[[sql, params], ...]`
 			const payload = batch.map((s) => [s.sql, s.params ?? []]);
-			return db.runInTransaction(JSON.stringify(payload));
+			return db.runInTransaction(JSON.stringify(payload, napiReplacer));
 		},
 
 		async close(): Promise<void> {