@c9up/atlas 0.2.0 → 0.2.1

package/src/Transaction.ts

@@ -5,8 +5,14 @@
  */
 
 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,
@@ -15,7 +21,9 @@ import {
 /** A post-commit / post-rollback side effect (Lucid `trx.after(...)`). */
 export type AfterHook = () => void | Promise<void>;
 
-export interface TransactionClient extends DatabaseConnection {
+export interface TransactionClient
+	extends Omit<DatabaseConnection, "query">,
+		TransactionQueryBuilders {
 	commit(): Promise<void>;
 	rollback(): Promise<void>;
 	/**
@@ -27,10 +35,134 @@ export interface TransactionClient extends DatabaseConnection {
 	 * 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;
 }
 
+/**
+ * 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,
+): Promise<T> {
+	const sp = await openSavepoint(parent);
+	try {
+		const result = await callback(sp);
+		await sp.commit();
+		return result;
+	} catch (err) {
+		try {
+			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 parent.execute(`RELEASE SAVEPOINT ${name}`, []);
+			} catch {
+				/* best-effort — the savepoint is already logically unwound */
+			}
+			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
@@ -46,68 +178,59 @@ export async function runAfterHooks(hooks: AfterHook[]): Promise<void> {
 	}
 }
 
+/**
+ * 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)) {
-		const parent = db;
-		const name = `sp_${randomBytes(6).toString("hex")}`;
-		await parent.execute(`SAVEPOINT ${name}`, []);
-
-		const commitHooks: AfterHook[] = [];
-		const rollbackHooks: AfterHook[] = [];
-
-		const trx: TransactionClient = {
-			execute: parent.execute.bind(parent),
-			query: parent.query.bind(parent),
-			async commit() {
-				await parent.execute(`RELEASE SAVEPOINT ${name}`, []);
-				// A nested commit is NOT durable until the root commits — forward BOTH
-				// hook sets to the parent. Commit hooks fire on the real (root) commit
-				// and drop if the outer later rolls back. Rollback hooks must ALSO
-				// forward: this savepoint's released work is folded into the parent, so
-				// an outer rollback undoes it too — dropping them here would strand any
-				// in-memory restoration a nested caller registered on `after('rollback')`
-				// (the work IS rolled back, just by the parent). The parent fires exactly
-				// one of its two hook sets, so no double-run.
-				for (const hook of commitHooks) parent.after("commit", hook);
-				for (const hook of rollbackHooks) parent.after("rollback", hook);
-			},
-			async rollback() {
-				await parent.execute(`ROLLBACK TO SAVEPOINT ${name}`, []);
-				// ROLLBACK TO leaves the savepoint ESTABLISHED — release it so it doesn't
-				// stay stacked on the connection through a long outer transaction with
-				// many nested failures. Best-effort: the rollback already unwound the
-				// work, so a RELEASE failure must not surface. (PG/MySQL/SQLite all
-				// accept RELEASE after ROLLBACK TO.)
-				try {
-					await parent.execute(`RELEASE SAVEPOINT ${name}`, []);
-				} catch {
-					/* best-effort — the savepoint is already logically unwound */
-				}
-				await runAfterHooks(rollbackHooks);
-			},
-			after(event, cb) {
-				(event === "commit" ? commitHooks : rollbackHooks).push(cb);
-			},
-			isNested: true,
-			[TRANSACTION_BRAND]: true,
-		};
-
-		try {
-			const result = await callback(trx);
-			await trx.commit();
-			return result;
-		} catch (err) {
-			try {
-				await trx.rollback();
-			} catch {
-				/* best-effort */
-			}
-			throw err;
-		}
+		return runManagedSavepoint(db, callback, options);
 	}
 
 	// Pinned interactive transaction (napi-backed): db.transaction() acquires ONE
@@ -125,24 +248,35 @@ export async function transaction<T>(
 
 	const commitHooks: AfterHook[] = [];
 	const rollbackHooks: AfterHook[] = [];
+	const evt = makeTrxEvents();
 
-	const trx: TransactionClient = {
+	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, cb) {
+		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

@@ -3,8 +3,11 @@
  */
 
 import { emitDbQuery, hasDbQueryListeners } from "../events.js";
+import { makeTransactionQueryBuilders } from "../query/DatabaseQueryBuilder.js";
 import {
 	type AfterHook,
+	makeNestedTransactionFn,
+	makeTrxEvents,
 	runAfterHooks,
 	type TransactionClient,
 } from "../Transaction.js";
@@ -86,6 +89,17 @@ export interface QueryMeta {
 	 * `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). */
@@ -149,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>;
 }
@@ -157,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>;
@@ -267,16 +293,22 @@ export async function createNapiConnection(
 		// COMMIT / ROLLBACK is durable (Lucid `trx.after(...)`), errors swallowed.
 		const commitHooks: AfterHook[] = [];
 		const rollbackHooks: AfterHook[] = [];
-		return {
+		const evt = makeTrxEvents();
+		const base = {
 			async execute(
 				sql: string,
 				params: unknown[] = [],
-			): Promise<{ rowsAffected: number }> {
-				const affected = await native.execute(
+			): Promise<{ rowsAffected: number; lastInsertId?: number }> {
+				const json = await native.execute(
 					sql,
 					JSON.stringify(params, napiReplacer),
 				);
-				return { rowsAffected: affected };
+				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,
@@ -290,18 +322,32 @@ export async function createNapiConnection(
 			},
 			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
@@ -362,6 +408,7 @@ export async function createNapiConnection(
 				method: meta?.method,
 				ddl: meta?.ddl,
 				inTransaction: false,
+				reporterData: meta?.reporterData,
 			});
 			return result;
 		} catch (error) {
@@ -375,6 +422,7 @@ export async function createNapiConnection(
 				ddl: meta?.ddl,
 				inTransaction: false,
 				error: error instanceof Error ? error : new Error(String(error)),
+				reporterData: meta?.reporterData,
 			});
 			throw error;
 		}
@@ -389,7 +437,11 @@ export async function createNapiConnection(
 			meta?: QueryMeta,
 		): Promise<T[]> {
 			return observed(sql, params, meta, async () => {
-				const json = await db.query(sql, JSON.stringify(params, napiReplacer));
+				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[];
 			});
 		},
@@ -398,13 +450,19 @@ export async function createNapiConnection(
 			sql: string,
 			params: unknown[] = [],
 			meta?: QueryMeta,
-		): Promise<{ rowsAffected: number }> {
+		): Promise<{ rowsAffected: number; lastInsertId?: number }> {
 			return observed(sql, params, meta, async () => {
-				const affected = await db.execute(
-					sql,
-					JSON.stringify(params, napiReplacer),
-				);
-				return { rowsAffected: affected };
+				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),
+				};
 			});
 		},
 

package/src/console/contract.ts

@@ -0,0 +1,96 @@
+/**
+ * The console command contract, declared locally.
+ *
+ * Atlas stays framework-agnostic: it must not import `@c9up/ream`, so it
+ * describes the shape Ream's console kernel dispatches against rather than
+ * importing it. Same reasoning as the previous `AtlasCommand` interface — only
+ * the shape changed, from a plain object to a class carrying its inputs as
+ * metadata.
+ *
+ * Ream's decorators (`@args` / `@flags`) live in the framework, so the helpers
+ * below build the same metadata without them.
+ */
+
+export interface CommandOptions {
+	/** Boot the application before `run()`. Off by default. */
+	startApp?: boolean;
+	staysAlive?: boolean;
+	allowUnknownFlags?: boolean;
+}
+
+export interface ArgumentMetaData {
+	type: "string" | "spread";
+	propertyName: string;
+	argumentName: string;
+	description?: string;
+	required: boolean;
+	default?: string | string[];
+}
+
+export interface FlagMetaData {
+	type: "string" | "boolean" | "number" | "array";
+	propertyName: string;
+	flagName: string;
+	description?: string;
+	alias: string[];
+	default?: string | string[] | number | boolean;
+	required: boolean;
+}
+
+/** The static side the kernel reads. */
+export interface AtlasCommandClass {
+	new (): { run(): Promise<void> | void };
+	commandName: string;
+	description: string;
+	options?: CommandOptions;
+	args?: readonly ArgumentMetaData[];
+	flags?: readonly FlagMetaData[];
+	help?: string | string[];
+}
+
+/** `startServer` → `start-server`, matching the framework's decorators. */
+function dashCase(value: string): string {
+	return value.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+
+export function flag(
+	propertyName: string,
+	type: FlagMetaData["type"],
+	options: {
+		flagName?: string;
+		description?: string;
+		alias?: string[];
+		default?: FlagMetaData["default"];
+		required?: boolean;
+	} = {},
+): FlagMetaData {
+	return {
+		type,
+		propertyName,
+		flagName: options.flagName ?? dashCase(propertyName),
+		description: options.description,
+		alias: options.alias ?? [],
+		default: options.default,
+		required: options.required ?? false,
+	};
+}
+
+export function argument(
+	propertyName: string,
+	options: {
+		type?: ArgumentMetaData["type"];
+		argumentName?: string;
+		description?: string;
+		required?: boolean;
+		default?: ArgumentMetaData["default"];
+	} = {},
+): ArgumentMetaData {
+	return {
+		type: options.type ?? "string",
+		propertyName,
+		argumentName: options.argumentName ?? dashCase(propertyName),
+		description: options.description,
+		required: options.required ?? options.default === undefined,
+		default: options.default,
+	};
+}

package/src/console/factoryCommands.ts

@@ -0,0 +1,73 @@
+/**
+ * Factory console command — `make:factory` (Adonis Lucid). Scaffolds a model
+ * factory file. Same shape as the migration/seeder commands: a plain
+ * `{ name, description, run }` object registered in `reamrc.commands`.
+ *
+ * @example
+ *   // commands/make-factory.ts
+ *   import { makeFactoryCommand } from '@c9up/atlas'
+ *   export default makeFactoryCommand({ factoriesDir: 'database/factories' })
+ *   // run:  <console-entry> make:factory User
+ */
+
+import * as fsp from "node:fs/promises";
+import * as path from "node:path";
+import { camelToSnake } from "../utils/casing.js";
+import { assertSafeName } from "../utils/safePath.js";
+import { type AtlasCommandClass, argument } from "./contract.js";
+
+export interface FactoryCommandOptions {
+	/** Directory the factory files are scaffolded into. */
+	factoriesDir: string;
+}
+
+/** Scaffold body for a fresh factory (`make:factory <Model>`). */
+function factoryStub(model: string): string {
+	return `import { factory } from '@c9up/atlas'
+import ${model} from '#models/${model.toLowerCase()}'
+
+export const ${model}Factory = factory(${model}, ({ faker }) => ({
+  // email: faker.internet.email(),
+}))
+`;
+}
+
+/**
+ * `make:factory <Model>` — scaffold `<Model>Factory.ts` in `factoriesDir`. The
+ * name is validated (no path separators / traversal) and written with `wx` so an
+ * existing factory is never clobbered.
+ */
+export function makeFactoryCommand(
+	options: FactoryCommandOptions,
+): AtlasCommandClass {
+	return class MakeFactory {
+		static commandName = "make:factory";
+		static description = "Scaffold a new model factory file";
+		// Pure filesystem work: no reason to boot the app and open a connection.
+		static options = { startApp: false };
+		static args = [
+			argument("model", { description: "Model the factory is built for" }),
+		];
+
+		declare model: string;
+
+		async run(): Promise<void> {
+			// A missing model is caught by the kernel before `run()` — it reports
+			// the required argument by name, so there is no usage check here.
+			// Lucid convention: `make:factory User` → `user_factory.ts`
+			// (`BlogPost` → `blog_post_factory.ts`).
+			const fileName = `${camelToSnake(this.model)}_factory.ts`;
+			try {
+				assertSafeName(fileName, "FACTORY_INVALID", "factory");
+			} catch {
+				console.error(`[atlas] invalid factory name: ${this.model}`);
+				process.exitCode = 1;
+				return;
+			}
+			const filePath = path.join(options.factoriesDir, fileName);
+			await fsp.mkdir(options.factoriesDir, { recursive: true });
+			await fsp.writeFile(filePath, factoryStub(this.model), { flag: "wx" });
+			console.log(`Created ${filePath}`);
+		}
+	};
+}