@c9up/atlas 0.3.10 → 0.3.12

package/scripts/build-napi-types.mjs

@@ -7,7 +7,8 @@
  * cargo a `/tmp/...` path the native proc-macro cannot write to, so the
  * type-def file comes back empty and the build fails for no visible reason.
  *
- * One crate at a time on purpose: napi-derive APPENDS to `TYPE_DEF_TMP_PATH`
+ * One crate at a time on purpose: with napi-derive 2 the writes all went to a
+ * single `TYPE_DEF_TMP_PATH` and a parallel build interleaved them
  * while cargo compiles, and a parallel build interleaves the writes —
  * definitions go missing, silently, and the generated file comes out short.
  */
@@ -28,11 +29,11 @@ const scratch = mkdtempSync(join(tmpdir(), 'napi-types-'))
 try {
   const lines = []
   for (const crate of CRATES) {
-    const perCrate = join(scratch, `${crate}.jsonl`)
+    const perCrate = join(scratch, crate)
     writeFileSync(perCrate, '')
     execFileSync('cargo', ['build', '-p', crate], {
       cwd: packageRoot,
-      env: { ...process.env, TYPE_DEF_TMP_PATH: perCrate },
+      env: { ...process.env, NAPI_TYPE_DEF_TMP_FOLDER: scratch },
       stdio: ['ignore', 'ignore', 'inherit'],
     })
     const emitted = readFileSync(perCrate, 'utf8').split('\n').filter(Boolean)

package/scripts/generate-napi-types.mjs

@@ -130,12 +130,15 @@ for (const fn of fns) {
   // napi-derive emits the whole declaration for a function, unlike a struct
   // where `def` holds only the members.
   const declaration = fn.def.trim()
-  out.push(
-    declaration.startsWith('export declare function')
-      ? `${declaration};`
-      : `export declare function ${fn.name}${declaration};`,
-    '',
-  )
+  // napi-derive 3 emits a bare `function name(...)` where 2 emitted the
+  // signature after the name; concatenating onto the former produced
+  // `function xfunction x(...)`.
+  const rendered = declaration.startsWith('export declare function')
+    ? declaration
+    : declaration.startsWith('function ')
+      ? `export declare ${declaration}`
+      : `export declare function ${fn.name}${declaration}`
+  out.push(`${rendered};`, '')
 }
 
 const stale = Object.keys(CALLBACK_REFINEMENTS).filter((k) => !used.has(k))

package/src/AtlasProvider.ts

@@ -21,6 +21,7 @@
  *     const tenant1 = await app.container.resolve('db:tenant1') // named
  */
 
+import "./augmentations.js";
 import {
 	type AsyncDatabaseConnection,
 	createNapiConnection,
@@ -63,10 +64,42 @@ export interface AtlasAppContext {
 	config: { get<T = unknown>(key: string): T | undefined };
 }
 
-/** True when `x` looks like an event emitter with `emit(event, data)`. */
+/**
+ * Forward one event to the application's emitter without letting it come back.
+ *
+ * `@adonisjs/events` declares `emit(): Promise<void>` and rethrows when a
+ * listener fails and the application registered no error handler. These bridges
+ * are driven by driver callbacks that nobody awaits, so that rejection had
+ * nowhere to go and ended the process — a query-log listener taking down the
+ * request it was observing.
+ *
+ * Called INSIDE the async function: `Promise.resolve(emit(...))` runs `emit`
+ * first, so a synchronous throw would still escape.
+ */
+function forward(
+	emitter: { emit: (event: string, data: unknown) => unknown },
+	event: string,
+	data: unknown,
+): void {
+	void (async () => emitter.emit(event, data))().catch((error: unknown) => {
+		process.stderr.write(
+			`[atlas] '${event}' listener failed: ${
+				error instanceof Error ? error.message : String(error)
+			}\n`,
+		);
+	});
+}
+
+/**
+ * True when `x` looks like an event emitter with `emit(event, data)`.
+ *
+ * The return is `unknown`, not `void`: `void` ACCEPTS a promise-returning
+ * function and then reads as if there were nothing to handle, which is exactly
+ * how an Adonis emitter's rejection went unnoticed here.
+ */
 function hasEmit(
 	x: unknown,
-): x is { emit: (event: string, data: unknown) => void } {
+): x is { emit: (event: string, data: unknown) => unknown } {
 	return (
 		typeof x === "object" &&
 		x !== null &&
@@ -287,7 +320,7 @@ export default class AtlasProvider {
 		const { onDbQuery } = await import("./events.js");
 		this.#dbQueryBridge?.();
 		this.#dbQueryBridge = onDbQuery((event) => {
-			emitter.emit("db:query", event);
+			forward(emitter, "db:query", event);
 		});
 	}
 
@@ -313,11 +346,11 @@ export default class AtlasProvider {
 		const mgr = connectionManager();
 		this.#connectionBridge?.();
 		const onConnect = (node: unknown) =>
-			emitter.emit("db:connection:connect", node);
+			forward(emitter, "db:connection:connect", node);
 		const onDisconnect = (node: unknown) =>
-			emitter.emit("db:connection:disconnect", node);
+			forward(emitter, "db:connection:disconnect", node);
 		const onError = (node: unknown, err?: unknown) =>
-			emitter.emit("db:connection:error", [err, node]);
+			forward(emitter, "db:connection:error", [err, node]);
 		mgr.on("connect", onConnect);
 		mgr.on("disconnect", onDisconnect);
 		mgr.on("error", onError);
@@ -382,7 +415,10 @@ export default class AtlasProvider {
 		const successes: Array<{ name: string; conn: AsyncDatabaseConnection }> =
 			[];
 		results.forEach((r, i) => {
-			const [name] = entries[i];
+			// `results` came from `entries`, one for one, so the pair is there.
+			const entry = entries[i];
+			if (entry === undefined) return;
+			const [name] = entry;
 			if (r.status === "fulfilled") successes.push({ name, conn: r.value });
 			else failures.push({ name, error: r.reason });
 		});
@@ -396,7 +432,8 @@ export default class AtlasProvider {
 			// has already opened. Closures run in parallel with allSettled so a
 			// stuck close doesn't block the rollback path.
 			await Promise.allSettled(successes.map((s) => s.conn.close()));
-			const first = failures[0];
+			const [first = { name: "(unknown)", error: new Error("unknown") }] =
+				failures;
 			const others = failures
 				.slice(1)
 				.map((f) => `${f.name}: ${String(f.error)}`)
@@ -432,18 +469,26 @@ export default class AtlasProvider {
 			for (const { name, conn } of successes) {
 				this.#connections.set(name, conn);
 				dbServices.registerConnection(name, conn, connections[name]);
+				this.app.container.singleton(`atlas.db:${name}`, () =>
+					this.#requireConnection(name),
+				);
 				this.app.container.singleton(`db:${name}`, () =>
 					this.#requireConnection(name),
 				);
 			}
 
 			// Expose the default under the short aliases `db` and `db.connection`.
-			this.app.container.singleton("db", () =>
-				this.#requireConnection(this.#defaultName),
-			);
-			this.app.container.singleton("db.connection", () =>
-				this.#requireConnection(this.#defaultName),
-			);
+			// Namespaced by the package that owns it, the way upstream namespaces
+			// `lucid.db`, `auth.manager` and `drive.manager` by theirs. The bare
+			// token stays bound beside it: it is what every existing
+			// `container.make(...)` asks for, and a token is not worth breaking an
+			// application over.
+			const defaultConnection = (): AsyncDatabaseConnection =>
+				this.#requireConnection(this.#defaultName);
+			this.app.container.singleton("atlas.db", defaultConnection);
+			this.app.container.singleton("db", defaultConnection);
+			this.app.container.singleton("atlas.db.connection", defaultConnection);
+			this.app.container.singleton("db.connection", defaultConnection);
 
 			// Populate the `@c9up/atlas/services/db` proxy so apps can
 			// `import db from '@c9up/atlas/services/db'` from anywhere.
@@ -456,7 +501,7 @@ export default class AtlasProvider {
 			// The dialect set module-wide is the DEFAULT connection's dialect.
 			// Per-connection dialect (when a user hits a non-default) is read from
 			// the connection URL at query time by each call site that cares.
-			setAtlasDialect(dialectFromUrl(connections[defaultName]?.url));
+			setAtlasDialect(dialectFromUrl(connections[defaultName]?.url ?? ""));
 
 			// Auto-run migrations on boot — but NOT in production unless explicitly
 			// opted in: starting the app should not silently mutate the schema in
@@ -485,7 +530,7 @@ export default class AtlasProvider {
 			if (migrationsPath) {
 				await this.#registerMigrationSource(
 					migrationsPath,
-					connections[defaultName]?.url,
+					connections[defaultName]?.url ?? "",
 					defaultConn,
 					config.migrations?.tableName ?? config.migrations?.table,
 					{
@@ -497,7 +542,7 @@ export default class AtlasProvider {
 			if (migrationsPath && !cliDrivesMigrations && autoMigrateAllowed) {
 				await this.#runMigrations(
 					migrationsPath,
-					connections[defaultName]?.url,
+					connections[defaultName]?.url ?? "",
 					defaultConn,
 					config.migrations?.tableName ?? config.migrations?.table,
 					{
@@ -557,7 +602,9 @@ export default class AtlasProvider {
 		clearCastRegistry();
 		const errors = results
 			.map((r, i) =>
-				r.status === "rejected" ? { name: named[i][0], error: r.reason } : null,
+				r.status === "rejected"
+					? { name: named[i]?.[0] ?? "(unknown)", error: r.reason }
+					: null,
 			)
 			.filter((x): x is { name: string; error: unknown } => x !== null);
 		if (errors.length > 0) {

package/src/BaseRepository.ts

@@ -1060,17 +1060,20 @@ export class BaseRepository<T extends BaseEntity> {
 			};
 			const compiled = compileStatementNative(spec, this.#dialect);
 			const returned = await this.#db.query<Record<string, unknown>>(
-				compiled.statements[0],
+				onlyStatement(compiled),
 				compiled.params,
 			);
 			returned.forEach((row, i) => {
+				// One returned row per entity written, in the same order.
+				const entity = entities[i];
+				if (entity === undefined) return;
 				for (const [k, v] of Object.entries(row)) {
 					const prop = this.#columnByDbName.get(k) ?? snakeToCamel(k);
 					// Run the DB value through consume so date columns come back as
 					// Chronos DateTime (not the raw ISO string) — mirrors #hydrate.
-					entities[i].setProp(prop, this.#applyConsume(prop, v, entities[i]));
+					entity.setProp(prop, this.#applyConsume(prop, v, entity));
 				}
-				entities[i].markAsPersisted();
+				entity.markAsPersisted();
 			});
 		}
 
@@ -1187,7 +1190,7 @@ export class BaseRepository<T extends BaseEntity> {
 		};
 		const compiled = compileStatementNative(spec, this.#dialect);
 		const result = await this.#db.execute(
-			compiled.statements[0],
+			onlyStatement(compiled),
 			compiled.params,
 		);
 		return result.rowsAffected;
@@ -1852,7 +1855,7 @@ export class BaseRepository<T extends BaseEntity> {
 			{ kind: "delete", table: this.#tableName, wheres },
 			this.#dialect,
 		);
-		await this.#db.execute(compiled.statements[0], compiled.params);
+		await this.#db.execute(onlyStatement(compiled), compiled.params);
 	}
 
 	/**
@@ -1878,7 +1881,7 @@ export class BaseRepository<T extends BaseEntity> {
 			},
 			this.#dialect,
 		);
-		await this.#db.execute(compiled.statements[0], compiled.params);
+		await this.#db.execute(onlyStatement(compiled), compiled.params);
 	}
 
 	/**
@@ -1910,13 +1913,13 @@ export class BaseRepository<T extends BaseEntity> {
 		const compiled = compileStatementNative(spec, this.#dialect);
 		if (supportsReturning) {
 			const rows = await this.#db.query<Row>(
-				compiled.statements[0],
+				onlyStatement(compiled),
 				compiled.params,
 			);
 			const first = rows[0];
 			return first ? { row: first } : {};
 		}
-		await this.#db.execute(compiled.statements[0], compiled.params);
+		await this.#db.execute(onlyStatement(compiled), compiled.params);
 		// MySQL path: napi adapter doesn't surface lastInsertRowid through
 		// `execute()`. Callers that need it must use an explicit dialect-
 		// specific query (e.g. `SELECT LAST_INSERT_ID()`). For Atlas's
@@ -2900,7 +2903,7 @@ export class BaseRepository<T extends BaseEntity> {
 				};
 				const compiled = compileStatementNative(selectSpec, dialect);
 				const rows = await conn.query<Record<string, unknown>>(
-					compiled.statements[0],
+					onlyStatement(compiled),
 					compiled.params,
 				);
 				return rows.map((r) => ({ id: asId(r[pivotOther]), row: r }));
@@ -2937,7 +2940,7 @@ export class BaseRepository<T extends BaseEntity> {
 					casts: pivotKeyCasts,
 				};
 				const compiled = compileStatementNative(spec, dialect);
-				await conn.execute(compiled.statements[0], compiled.params);
+				await conn.execute(onlyStatement(compiled), compiled.params);
 			};
 
 			const attach = async (
@@ -2978,7 +2981,7 @@ export class BaseRepository<T extends BaseEntity> {
 					casts: pivotCasts,
 				};
 				const compiled = compileStatementNative(spec, dialect);
-				await conn.execute(compiled.statements[0], compiled.params);
+				await conn.execute(onlyStatement(compiled), compiled.params);
 			};
 
 			// Refresh one already-attached pivot row's attributes (sync's update arm,
@@ -3016,7 +3019,7 @@ export class BaseRepository<T extends BaseEntity> {
 					casts,
 				};
 				const compiled = compileStatementNative(spec, dialect);
-				await conn.execute(compiled.statements[0], compiled.params);
+				await conn.execute(onlyStatement(compiled), compiled.params);
 			};
 
 			/**
@@ -3381,3 +3384,18 @@ export function assertNotPromise(
 		);
 	}
 }
+
+/**
+ * The single statement a compile produced.
+ *
+ * `compileStatementNative` answers a list because a few specs expand to more
+ * than one; the callers here compile specs that do not, and this is where that
+ * is stated instead of reading index zero as a value that might not be there.
+ */
+function onlyStatement(compiled: { statements: string[] }): string {
+	const [statement] = compiled.statements;
+	if (statement === undefined) {
+		throw new Error("atlas: the query compiler produced no statement");
+	}
+	return statement;
+}

package/src/ModelQuery.ts

@@ -1040,7 +1040,10 @@ export class ModelQuery<T extends BaseEntity> {
 		const aliased = col.match(
 			/^([A-Za-z_][A-Za-z0-9_]*)\s+as\s+([A-Za-z_][A-Za-z0-9_]*)$/i,
 		);
-		if (aliased) return `${this.#resolveColumn(aliased[1])} AS ${aliased[2]}`;
+		const [, aliasSource, aliasName] = aliased ?? [];
+		if (aliasSource !== undefined && aliasName !== undefined) {
+			return `${this.#resolveColumn(aliasSource)} AS ${aliasName}`;
+		}
 		return col;
 	}
 
@@ -3001,7 +3004,13 @@ export class ModelQuery<T extends BaseEntity> {
 				`Expected exactly one ${this.#tableName} but the query matched multiple rows (sole()).`,
 			);
 		}
-		return rows[0];
+		const [only] = rows;
+		if (only === undefined) {
+			throw new Error(
+				`Expected exactly one ${this.#tableName} but the query matched none (sole()).`,
+			);
+		}
+		return only;
 	}
 
 	/**
@@ -3182,7 +3191,7 @@ export class ModelQuery<T extends BaseEntity> {
 	 */
 	#compiledNative(): { sql: string; params: unknown[] } {
 		const compiled = compileStatementNative(this.#buildSpec(), this.#dialect);
-		const sql = this.#commentPrefix() + compiled.statements[0];
+		const sql = this.#commentPrefix() + onlyStatement(compiled);
 		return { sql, params: compiled.params };
 	}
 
@@ -4003,7 +4012,7 @@ export class ModelQuery<T extends BaseEntity> {
 		};
 		const compiled = compileStatementNative(spec, this.#dialect);
 		return this.#db.query<Record<string, unknown>>(
-			compiled.statements[0],
+			onlyStatement(compiled),
 			compiled.params,
 		);
 	}
@@ -4730,12 +4739,14 @@ export class ModelQuery<T extends BaseEntity> {
 			}
 			// Build the disjunctive tuple comparison as a nested group of WHEREs.
 			clone.where((q) => {
-				for (let i = 0; i < cols.length; i++) {
+				for (const [i, col] of cols.entries()) {
 					q.orWhere((inner) => {
-						for (let j = 0; j < i; j++) inner.where(cols[j], decoded.v[j]);
+						for (const [j, earlier] of cols.slice(0, i).entries()) {
+							inner.where(earlier, decoded.v[j]);
+						}
 						// The comparison has to follow the walk: `>` reads forward
 						// through an ascending order, `<` through a descending one.
-						inner.where(cols[i], descending ? "<" : ">", decoded.v[i]);
+						inner.where(col, descending ? "<" : ">", decoded.v[i]);
 					});
 				}
 			});
@@ -5340,7 +5351,7 @@ export class ModelQuery<T extends BaseEntity> {
 		const compiled = compileStatementNative(spec, this.#dialect);
 		const r = await this.#raceTimeout(
 			this.#db.execute(
-				this.#commentPrefix() + compiled.statements[0],
+				this.#commentPrefix() + onlyStatement(compiled),
 				compiled.params,
 				this.#meta("dml"),
 			),
@@ -5394,7 +5405,7 @@ export class ModelQuery<T extends BaseEntity> {
 		params: unknown[];
 	} {
 		const compiled = compileStatementNative(spec, this.#dialect);
-		const sql = this.#commentPrefix() + compiled.statements[0];
+		const sql = this.#commentPrefix() + onlyStatement(compiled);
 		return { sql, bindings: compiled.params, params: compiled.params };
 	}
 
@@ -5453,7 +5464,7 @@ export class ModelQuery<T extends BaseEntity> {
 		if (returning && returning.length > 0) {
 			return this.#raceTimeout(
 				this.#db.query<Record<string, unknown>>(
-					this.#commentPrefix() + compiled.statements[0],
+					this.#commentPrefix() + onlyStatement(compiled),
 					compiled.params,
 					this.#meta("dml"),
 				),
@@ -5461,7 +5472,7 @@ export class ModelQuery<T extends BaseEntity> {
 		}
 		const r = await this.#raceTimeout(
 			this.#db.execute(
-				this.#commentPrefix() + compiled.statements[0],
+				this.#commentPrefix() + onlyStatement(compiled),
 				compiled.params,
 				this.#meta("dml"),
 			),
@@ -5597,3 +5608,18 @@ export class ModelQuery<T extends BaseEntity> {
 
 /** `col as alias` — the Lucid aggregate spelling. */
 const ALIASED = /^(.*?)\s+as\s+(\S+)$/i;
+
+/**
+ * The single statement a compile produced.
+ *
+ * `compileStatementNative` answers a list because a few specs expand to more
+ * than one; the callers here compile specs that do not, and this is where that
+ * is stated instead of reading index zero as a value that might not be there.
+ */
+function onlyStatement(compiled: { statements: string[] }): string {
+	const [statement] = compiled.statements;
+	if (statement === undefined) {
+		throw new Error("atlas: the query compiler produced no statement");
+	}
+	return statement;
+}

package/src/augmentations.ts

@@ -0,0 +1,49 @@
+/**
+ * Teach ream's `ContainerBindings` what `container.make('db')` returns.
+ *
+ * ream declares that interface open on purpose: it registers its own entries
+ * and expects each package to contribute the one it owns — the comment on the
+ * interface names `db` (atlas) as exactly this. Nothing filled it in, so
+ * resolving by the string token answered `unknown` and every call site had to
+ * assert a type it could not prove.
+ *
+ * Loaded from the package barrel and from the provider, so registering atlas
+ * is enough — an application writes no `declare module` of its own.
+ *
+ * Type-only, and ream is an OPTIONAL peer: nothing here reaches a runtime
+ * import, the provider still duck-types its host, and a `declare module` for a
+ * specifier that does not resolve is simply inert. Atlas stays usable with no
+ * framework at all.
+ */
+
+// Referenced so the augmentation below resolves the module it augments.
+import type {} from "@c9up/ream/types";
+import type { AsyncDatabaseConnection } from "./adapters/NapiDbAdapter.js";
+
+declare module "@c9up/ream/types" {
+	interface ContainerBindings {
+		/** The default connection, bound by `AtlasProvider`. */
+		"atlas.db": AsyncDatabaseConnection;
+		/**
+		 * The same binding under the name it had before the token carried its
+		 * package. Kept bound so an existing `container.make(...)` resolves.
+		 */
+		db: AsyncDatabaseConnection;
+		/** The default connection, under the longer name. */
+		"atlas.db.connection": AsyncDatabaseConnection;
+		/**
+		 * The same binding under the name it had before the token carried its
+		 * package. Kept bound so an existing `container.make(...)` resolves.
+		 */
+		"db.connection": AsyncDatabaseConnection;
+		/**
+		 * One named connection per entry in the config — `db:primary`,
+		 * `db:replica`. A template-literal key rather than an enumeration,
+		 * because the names come from an application's config file and this
+		 * package cannot know them.
+		 */
+		[
+			connection: `atlas.db:${string}` | `db:${string}`
+		]: AsyncDatabaseConnection;
+	}
+}

package/src/index.ts

@@ -5,6 +5,7 @@
  */
 
 import "reflect-metadata";
+import "./augmentations.js";
 
 export { SQLITE_PROD_PRAGMAS } from "./AtlasProvider.js";
 export type {

package/src/query/DatabaseQueryBuilder.ts

@@ -2125,7 +2125,7 @@ export class DatabaseQueryBuilder<T = Record<string, unknown>> {
 	 */
 	#compiledNative(): { sql: string; params: unknown[] } {
 		const compiled = compileStatementNative(this.#selectSpec(), this.#dialect);
-		const sql = this.#commentPrefix() + compiled.statements[0];
+		const sql = this.#commentPrefix() + onlyStatement(compiled);
 		if (this.#debug) {
 			console.debug("[atlas:sql]", sql, compiled.params);
 		}
@@ -2222,7 +2222,7 @@ export class DatabaseQueryBuilder<T = Record<string, unknown>> {
 		);
 		const rows = await this.#raceTimeout(
 			this.#exec.query<{ aggregate: number | string | null }>(
-				compiled.statements[0],
+				onlyStatement(compiled),
 				compiled.params,
 				this.#queryMeta("aggregate"),
 			),
@@ -2235,8 +2235,10 @@ export class DatabaseQueryBuilder<T = Record<string, unknown>> {
 	 * `'* as total'` → `COUNT(*) AS total`; `'amount'` → `SUM(amount)`.
 	 */
 	#aggProjection(fn: string, expr: string): string {
-		const m = expr.match(/^(.*?)\s+as\s+(.+)$/i);
-		return m ? `${fn}(${m[1].trim()}) AS ${m[2].trim()}` : `${fn}(${expr})`;
+		const [, source, alias] = expr.match(/^(.*?)\s+as\s+(.+)$/i) ?? [];
+		return source !== undefined && alias !== undefined
+			? `${fn}(${source.trim()}) AS ${alias.trim()}`
+			: `${fn}(${expr})`;
 	}
 
 	/**
@@ -2401,7 +2403,7 @@ export class DatabaseQueryBuilder<T = Record<string, unknown>> {
 				? { ...spec, returning: this.#returningCols }
 				: spec;
 		const compiled = compileStatementNative(withReturning, this.#dialect);
-		const sql = this.#commentPrefix() + compiled.statements[0];
+		const sql = this.#commentPrefix() + onlyStatement(compiled);
 		return { sql, bindings: compiled.params, params: compiled.params };
 	}
 
@@ -2593,7 +2595,7 @@ export class DatabaseQueryBuilder<T = Record<string, unknown>> {
 		const rows = [Object.entries(data)];
 		return new DmlBuilder(
 			() =>
-				rows[0].length === 0
+				(rows[0]?.length ?? 0) === 0
 					? Promise.resolve<Array<Record<string, unknown> | number>>([])
 					: this.#runDml(
 							this.#buildInsertOrUpsertSpec(rows),
@@ -2728,7 +2730,7 @@ export class DatabaseQueryBuilder<T = Record<string, unknown>> {
 		);
 		const result = await this.#raceTimeout(
 			this.#exec.execute(
-				this.#commentPrefix() + compiled.statements[0],
+				this.#commentPrefix() + onlyStatement(compiled),
 				compiled.params,
 				this.#queryMeta(op),
 			),
@@ -2773,7 +2775,7 @@ export class DatabaseQueryBuilder<T = Record<string, unknown>> {
 		const countSql =
 			this.#groupBys.length > 0
 				? `SELECT COUNT(*) AS aggregate FROM (${this.#compiledNative().sql}) AS __paginate_count`
-				: countCompiled.statements[0];
+				: onlyStatement(countCompiled);
 		const countParams =
 			this.#groupBys.length > 0
 				? this.#compiledNative().params
@@ -2833,3 +2835,18 @@ function lastInsertIdOf(result: unknown): number | undefined {
 	}
 	return undefined;
 }
+
+/**
+ * The single statement a compile produced.
+ *
+ * `compileStatementNative` answers a list because a few specs expand to more
+ * than one; the callers here compile specs that do not, and this is where that
+ * is stated instead of reading index zero as a value that might not be there.
+ */
+function onlyStatement(compiled: { statements: string[] }): string {
+	const [statement] = compiled.statements;
+	if (statement === undefined) {
+		throw new Error("atlas: the query compiler produced no statement");
+	}
+	return statement;
+}

package/src/query/QueryBuilder.ts

@@ -415,7 +415,7 @@ export class QueryBuilder<_T = Record<string, unknown>> {
 			{ kind: "select", ...desc },
 			this.#dialect,
 		);
-		return { sql: compiled.statements[0], params: compiled.params };
+		return { sql: onlyStatement(compiled), params: compiled.params };
 	}
 
 	/** Get the table name. */
@@ -428,3 +428,18 @@ export class QueryBuilder<_T = Record<string, unknown>> {
 		return [...this.#preload];
 	}
 }
+
+/**
+ * The single statement a compile produced.
+ *
+ * `compileStatementNative` answers a list because a few specs expand to more
+ * than one; the callers here compile specs that do not, and this is where that
+ * is stated instead of reading index zero as a value that might not be there.
+ */
+function onlyStatement(compiled: { statements: string[] }): string {
+	const [statement] = compiled.statements;
+	if (statement === undefined) {
+		throw new Error("atlas: the query compiler produced no statement");
+	}
+	return statement;
+}