@orkestrel/database 0.0.18 → 0.0.19

package/dist/src/server/index.js

@@ -1,9 +1,75 @@
-import { DatabaseError, DriverIterator, MemoryDriver, applyQuery, bindRowKey, checkAbort, cloneDriverMetadata, cloneMigrationInput, computeAggregate, equalsValue, extractKey, filterRows, findColumn, isDatabaseError, isKey, matchesQuery, migrateRows, normalizeDriverSchema, planMigration, projectMigrationSchema, validatePage } from "../core/index.js";
-import { cloneJSONValue, isArray, isBigInt, isBoolean, isError, isFiniteNumber, isInteger, isNumber, isObject, isRecord, isString, isUint8Array } from "@orkestrel/contract";
+import { DatabaseError, DriverIterator, MemoryDriver, StreamPage, applyQuery, bindRowKey, checkAbort, cloneDriverMetadata, cloneMigrationInput, computeAggregate, equalsValue, extractKey, filterRows, findColumn, isDatabaseError, isKey, matchesQuery, migrateRows, normalizeDriverSchema, planMigration, projectMigrationSchema, validatePage } from "../core/index.js";
+import { attempt, cloneJSONValue, isArray, isBigInt, isBoolean, isError, isFiniteNumber, isInteger, isNumber, isObject, isRecord, isString, isUint8Array } from "@orkestrel/contract";
 import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
 import { createSQLiteDatabase, isSQLiteError } from "@orkestrel/sqlite";
-//#region src/server/constants.ts
+// src/server/SQLiteTransaction.ts
+/**
+* Owns the candidate schema and table identities of one SQLite transaction.
+*
+* @example
+* ```ts
+* const transaction = new SQLiteTransaction(new Map(), new Map())
+* transaction.schema.size // 0
+* ```
+*/
+var SQLiteTransaction = class {
+	#schema;
+	#identities;
+	constructor(schema, identities) {
+		this.#schema = new Map(schema);
+		this.#identities = new Map(identities);
+	}
+	get schema() {
+		return this.#schema;
+	}
+	get identities() {
+		return this.#identities;
+	}
+	project(schema, identities) {
+		this.#schema = new Map(schema.map((table) => [table.name, table]));
+		this.#identities = identities;
+	}
+};
+// src/server/JSONTransaction.ts
+/**
+* Owns the isolated memory store and schema of one JSON transaction.
+*
+* @example
+* ```ts
+* const transaction = new JSONTransaction(new MemoryDriver(), [], new Map())
+* transaction.stop()
+* // transaction.memory throws CONFLICT after settlement.
+* ```
+*/
+var JSONTransaction = class {
+	#memory;
+	#schema;
+	#identities;
+	constructor(memory, schema, identities) {
+		this.#memory = memory;
+		this.#schema = schema;
+		this.#identities = new Map(identities);
+	}
+	get memory() {
+		if (this.#memory === void 0) throw new DatabaseError("CONFLICT", "Transaction scope has settled");
+		return this.#memory;
+	}
+	get schema() {
+		return this.#schema;
+	}
+	get identities() {
+		return this.#identities;
+	}
+	project(schema, identities) {
+		this.#schema = schema;
+		this.#identities = identities;
+	}
+	stop() {
+		this.#memory = void 0;
+	}
+};
+// src/server/constants.ts
 /**
 * Lists the declared {@link ColumnStorage}s whose SQL equality comparisons (`equals` /
 * `not` / `any` / `none`) and `starts` / `ends` compiles are provably
@@ -52,8 +118,7 @@ var EXACT_RANGE_COLUMN_STORAGE = Object.freeze([
 * reservation — the caller's concern to avoid, documented on the driver class.
 */
 var METADATA_TABLE = "_metadata";
-//#endregion
-//#region src/server/helpers.ts
+// src/server/helpers.ts
 /**
 * Reports whether a caught filesystem error says that nothing is there to read.
 *
@@ -235,12 +300,7 @@ function matchesAggregateExactly(operation, column, schema) {
 function matchesSQLiteAffinity(declared, storage) {
 	if (!isString(declared)) return false;
 	const type = declared.toUpperCase();
-	let affinity;
-	if (type.includes("INT")) affinity = "INTEGER";
-	else if (type.includes("CHAR") || type.includes("CLOB") || type.includes("TEXT")) affinity = "TEXT";
-	else if (type === "" || type.includes("BLOB")) affinity = "BLOB";
-	else if (type.includes("REAL") || type.includes("FLOA") || type.includes("DOUB")) affinity = "REAL";
-	else affinity = "NUMERIC";
+	const affinity = type.includes("INT") ? "INTEGER" : type.includes("CHAR") || type.includes("CLOB") || type.includes("TEXT") ? "TEXT" : type === "" || type.includes("BLOB") ? "BLOB" : type.includes("REAL") || type.includes("FLOA") || type.includes("DOUB") ? "REAL" : "NUMERIC";
 	if (storage === "integer" || storage === "boolean") return affinity === "INTEGER";
 	if (storage === "text" || storage === "json") return affinity === "TEXT";
 	if (storage === "blob") return affinity === "BLOB";
@@ -453,8 +513,7 @@ function decodeRow(row, schema) {
 function deriveSQLiteIndexName(table, columns) {
 	return "idx_" + [table, ...columns].map((part) => String(part.length) + "_" + part).join("_");
 }
-//#endregion
-//#region src/server/inferers.ts
+// src/server/inferers.ts
 /**
 * Reads the storage type a nested (`json_extract`) operand encodes as from its
 * runtime value, never as `json`.
@@ -483,8 +542,7 @@ function inferValueStorage(value) {
 	if (isObject(value)) return "json";
 	return "text";
 }
-//#endregion
-//#region src/server/compilers.ts
+// src/server/compilers.ts
 /**
 * Maps a portable {@link ColumnStorage} to its SQLite column type.
 *
@@ -632,17 +690,13 @@ function compileConditionSQL(condition, schema) {
 	const second = condition.values[1];
 	const nullOperand = first === null || first === void 0;
 	const jsonType = !isString(condition.column) ? compileJSONTypeSQL(condition.column) : "";
-	let sql;
-	let values;
 	switch (condition.operator) {
 		case "equals":
 			if (nullOperand && nested) return {
 				sql: jsonType + " = 'null'",
 				parameters: []
 			};
-			sql = column + " = ?";
-			values = [first];
-			break;
+			return compileBoundSQL(column + " = ?", [first], nested, declared);
 		case "not":
 			if (nullOperand) {
 				if (nested) return {
@@ -654,37 +708,14 @@ function compileConditionSQL(condition, schema) {
 					parameters: []
 				};
 			}
-			sql = "(" + column + " != ? OR " + column + " IS NULL)";
-			values = [first];
-			break;
-		case "above":
-			sql = column + " > ?";
-			values = [first];
-			break;
-		case "below":
-			sql = "(" + column + " < ? OR " + column + " IS NULL)";
-			values = [first];
-			break;
-		case "from":
-			sql = column + " >= ?";
-			values = [first];
-			break;
-		case "to":
-			sql = "(" + column + " <= ? OR " + column + " IS NULL)";
-			values = [first];
-			break;
-		case "between":
-			sql = column + " BETWEEN ? AND ?";
-			values = [first, second];
-			break;
-		case "like":
-			sql = column + " LIKE ?";
-			values = [first];
-			break;
-		case "glob":
-			sql = column + " GLOB ?";
-			values = [first];
-			break;
+			return compileBoundSQL("(" + column + " != ? OR " + column + " IS NULL)", [first], nested, declared);
+		case "above": return compileBoundSQL(column + " > ?", [first], nested, declared);
+		case "below": return compileBoundSQL("(" + column + " < ? OR " + column + " IS NULL)", [first], nested, declared);
+		case "from": return compileBoundSQL(column + " >= ?", [first], nested, declared);
+		case "to": return compileBoundSQL("(" + column + " <= ? OR " + column + " IS NULL)", [first], nested, declared);
+		case "between": return compileBoundSQL(column + " BETWEEN ? AND ?", [first, second], nested, declared);
+		case "like": return compileBoundSQL(column + " LIKE ?", [first], nested, declared);
+		case "glob": return compileBoundSQL(column + " GLOB ?", [first], nested, declared);
 		case "starts": {
 			const text = isString(first) ? first : "";
 			if (text === "") return {
@@ -692,9 +723,7 @@ function compileConditionSQL(condition, schema) {
 				parameters: []
 			};
 			const length = Array.from(text).length;
-			sql = "(typeof(" + column + ") = 'text' AND substr(" + column + ", 1, " + length + ") = ?)";
-			values = [first];
-			break;
+			return compileBoundSQL("(typeof(" + column + ") = 'text' AND substr(" + column + ", 1, " + length + ") = ?)", [first], nested, declared);
 		}
 		case "ends": {
 			const text = isString(first) ? first : "";
@@ -703,26 +732,26 @@ function compileConditionSQL(condition, schema) {
 				parameters: []
 			};
 			const length = Array.from(text).length;
-			sql = "(typeof(" + column + ") = 'text' AND substr(" + column + ", -" + length + ") = ?)";
-			values = [first];
-			break;
+			return compileBoundSQL("(typeof(" + column + ") = 'text' AND substr(" + column + ", -" + length + ") = ?)", [first], nested, declared);
 		}
-		case "any":
+		case "any": {
 			if (condition.values.length === 0) return {
 				sql: "0",
 				parameters: []
 			};
-			sql = column + " IN (" + condition.values.map(() => "?").join(", ") + ")";
-			values = condition.values;
-			break;
-		case "none":
+			const sql = column + " IN (" + condition.values.map(() => "?").join(", ") + ")";
+			const values = condition.values;
+			return compileBoundSQL(sql, values, nested, declared);
+		}
+		case "none": {
 			if (condition.values.length === 0) return {
 				sql: "1",
 				parameters: []
 			};
-			sql = "(" + column + " NOT IN (" + condition.values.map(() => "?").join(", ") + ") OR " + column + " IS NULL)";
-			values = condition.values;
-			break;
+			const sql = "(" + column + " NOT IN (" + condition.values.map(() => "?").join(", ") + ") OR " + column + " IS NULL)";
+			const values = condition.values;
+			return compileBoundSQL(sql, values, nested, declared);
+		}
 		case "absent": return {
 			sql: column + " IS NULL",
 			parameters: []
@@ -732,6 +761,17 @@ function compileConditionSQL(condition, schema) {
 			parameters: []
 		};
 	}
+}
+/**
+* Encodes condition operands for a SQL fragment using their declared or inferred storage.
+*
+* @example
+* ```ts
+* compileBoundSQL('"age" > ?', [18], false, undefined)
+* // { sql: '"age" > ?', parameters: ['18'] }
+* ```
+*/
+function compileBoundSQL(sql, values, nested, declared) {
 	return {
 		sql,
 		parameters: values.map((value) => {
@@ -773,17 +813,18 @@ function compileWhereSQL(conditions, schema) {
 		parameters: []
 	};
 	const head = compileConditionSQL(first, schema);
-	let clause = head.sql;
-	const parameters = [...head.parameters];
-	for (const condition of remaining) {
+	const fragments = remaining.map((condition) => {
 		const next = compileConditionSQL(condition, schema);
-		const operator = condition.connector === "or" ? "OR" : "AND";
-		clause = "(" + clause + " " + operator + " " + next.sql + ")";
-		parameters.push(...next.parameters);
-	}
+		return {
+			sql: " " + (condition.connector === "or" ? "OR" : "AND") + " " + next.sql + ")",
+			parameters: next.parameters
+		};
+	});
+	const opening = "(".repeat(fragments.length);
+	const tail = fragments.map((part) => part.sql).join("");
 	return {
-		sql: "WHERE " + clause,
-		parameters
+		sql: "WHERE " + opening + head.sql + tail,
+		parameters: [...head.parameters, ...fragments.flatMap((part) => part.parameters)]
 	};
 }
 /**
@@ -943,8 +984,7 @@ function stepToSQL(step) {
 		case "index.remove": return ["DROP INDEX IF EXISTS " + quoteIdentifier(deriveSQLiteIndexName(step.table, step.index))];
 	}
 }
-//#endregion
-//#region src/server/drivers/JSONDriver.ts
+// src/server/drivers/JSONDriver.ts
 /**
 * Implements a persistent {@link DriverInterface} backed by a single JSON file — the
 * reference {@link MemoryDriver} plus file load / flush.
@@ -989,10 +1029,7 @@ var JSONDriver = class {
 	#metadata;
 	#flushCount = 0;
 	#chain = Promise.resolve();
-	#transaction;
-	#candidate;
-	#candidateIdentities;
-	#candidateSchema;
+	#transactions = /* @__PURE__ */ new Set();
 	constructor(path) {
 		this.#path = path;
 	}
@@ -1136,33 +1173,7 @@ var JSONDriver = class {
 	}
 	async #open(declared) {
 		const parsed = await this.#document();
-		let stored;
-		let tables;
-		if (parsed === void 0) {
-			const fresh = {};
-			for (const table of declared) fresh[table.name] = [];
-			tables = fresh;
-		} else {
-			if (!isRecord(parsed) || !Object.hasOwn(parsed, "tables") || Object.keys(parsed).some((key) => key !== "tables" && key !== "metadata")) throw new DatabaseError("DRIVER", "Stored JSON database document is invalid", {
-				path: this.#path,
-				aspect: "document"
-			});
-			if (!isRecord(parsed.tables)) throw new DatabaseError("DRIVER", "Stored JSON tables are invalid", {
-				path: this.#path,
-				aspect: "tables"
-			});
-			tables = parsed.tables;
-			if (Object.hasOwn(parsed, "metadata")) try {
-				stored = cloneDriverMetadata(parsed.metadata);
-			} catch {
-				const cause = new DatabaseError("VALIDATION", "Stored JSON metadata failed validation", { path: "metadata" });
-				throw new DatabaseError("DRIVER", "Stored JSON metadata is invalid", {
-					path: this.#path,
-					aspect: "metadata",
-					cause
-				});
-			}
-		}
+		const [stored, tables] = this.#decodeDocument(parsed, declared);
 		const schema = normalizeDriverSchema(stored?.schema ?? declared);
 		const names = new Set(schema.map((table) => table.name));
 		for (const table of schema) if (!Object.hasOwn(tables, table.name)) throw new DatabaseError("DRIVER", "Stored JSON table set is invalid", {
@@ -1209,33 +1220,23 @@ var JSONDriver = class {
 	async #transact(scope) {
 		this.#root();
 		const candidate = await this.#clone();
-		const token = {};
-		this.#transaction = token;
-		this.#candidate = candidate;
-		this.#candidateIdentities = new Map(this.#identities);
-		this.#candidateSchema = this.#schema;
+		const token = new JSONTransaction(candidate, this.#schema, this.#identities);
+		this.#transactions.add(token);
 		try {
 			const value = await scope(this.#capability(token));
-			const schema = this.#candidateSchema;
-			const identities = this.#candidateIdentities;
-			if (schema === void 0 || identities === void 0) throw new DatabaseError("CONFLICT", "Transaction scope has settled");
-			this.#candidate = void 0;
-			this.#candidateIdentities = void 0;
-			this.#candidateSchema = void 0;
+			const schema = token.schema;
+			const identities = token.identities;
+			token.stop();
 			const metadata = await candidate.metadata();
 			await this.#serialize(void 0, candidate, schema, metadata);
 			this.#memory = candidate;
-			this.#identities = identities;
+			this.#identities = new Map(identities);
 			this.#schema = schema;
 			this.#metadata = metadata === void 0 ? void 0 : cloneDriverMetadata(metadata);
 			return value;
 		} finally {
-			if (this.#transaction === token) {
-				this.#transaction = void 0;
-				this.#candidate = void 0;
-				this.#candidateIdentities = void 0;
-				this.#candidateSchema = void 0;
-			}
+			token.stop();
+			this.#transactions.delete(token);
 		}
 	}
 	async #clone() {
@@ -1335,13 +1336,11 @@ var JSONDriver = class {
 	}
 	async #migrateCandidate(token, input) {
 		const memory = this.#requireCandidate(token);
-		const schema = this.#candidateSchema;
-		const identities = this.#candidateIdentities;
-		if (schema === void 0 || identities === void 0) throw new DatabaseError("CONFLICT", "Transaction scope has settled");
+		const schema = token.schema;
+		const identities = token.identities;
 		const owned = cloneMigrationInput(input);
 		const projected = this.#projectIdentities(identities, owned.plan.steps);
-		this.#candidateSchema = await this.#apply(memory, schema, owned);
-		this.#candidateIdentities = projected;
+		token.project(await this.#apply(memory, schema, owned), projected);
 	}
 	async #metadataCandidate(token) {
 		const metadata = await this.#requireCandidate(token).metadata();
@@ -1353,8 +1352,8 @@ var JSONDriver = class {
 		await memory.stamp(owned);
 	}
 	#requireCandidate(token) {
-		if (this.#transaction !== token || this.#candidate === void 0) throw new DatabaseError("CONFLICT", "Transaction scope has settled");
-		return this.#candidate;
+		if (!this.#transactions.has(token)) throw new DatabaseError("CONFLICT", "Transaction scope has settled");
+		return token.memory;
 	}
 	#alignIdentities(schema) {
 		const aligned = /* @__PURE__ */ new Map();
@@ -1370,19 +1369,34 @@ var JSONDriver = class {
 		return projected;
 	}
 	#root() {
-		if (this.#transaction !== void 0) throw new DatabaseError("CONFLICT", "A transaction is active on this driver");
+		if (this.#transactions.size !== 0) throw new DatabaseError("CONFLICT", "A transaction is active on this driver");
 	}
-	async #document() {
-		let raw;
-		try {
-			raw = await readFile(this.#path, "utf-8");
-		} catch (error) {
-			if (matchesAbsentPath(error)) return void 0;
-			throw new DatabaseError("DRIVER", "Failed to read the JSON database file", {
+	#decodeDocument(parsed, declared) {
+		if (parsed === void 0) return [void 0, Object.fromEntries(Iterator.from(declared).map((table) => [table.name, []]))];
+		if (!isRecord(parsed) || !Object.hasOwn(parsed, "tables") || Object.keys(parsed).some((key) => key !== "tables" && key !== "metadata")) throw new DatabaseError("DRIVER", "Stored JSON database document is invalid", {
+			path: this.#path,
+			aspect: "document"
+		});
+		if (!isRecord(parsed.tables)) throw new DatabaseError("DRIVER", "Stored JSON tables are invalid", {
+			path: this.#path,
+			aspect: "tables"
+		});
+		const tables = parsed.tables;
+		if (Object.hasOwn(parsed, "metadata")) try {
+			return [cloneDriverMetadata(parsed.metadata), tables];
+		} catch {
+			const cause = new DatabaseError("VALIDATION", "Stored JSON metadata failed validation", { path: "metadata" });
+			throw new DatabaseError("DRIVER", "Stored JSON metadata is invalid", {
 				path: this.#path,
-				cause: error
+				aspect: "metadata",
+				cause
 			});
 		}
+		return [void 0, tables];
+	}
+	async #document() {
+		const raw = await this.#readDocument();
+		if (raw === void 0) return void 0;
 		try {
 			return JSON.parse(raw);
 		} catch {
@@ -1392,6 +1406,17 @@ var JSONDriver = class {
 			});
 		}
 	}
+	async #readDocument() {
+		try {
+			return await readFile(this.#path, "utf-8");
+		} catch (error) {
+			if (matchesAbsentPath(error)) return void 0;
+			throw new DatabaseError("DRIVER", "Failed to read the JSON database file", {
+				path: this.#path,
+				cause: error
+			});
+		}
+	}
 	async #hydrate(memory, schema, tables) {
 		for (const table of schema) {
 			const rows = tables[table.name];
@@ -1428,18 +1453,16 @@ var JSONDriver = class {
 	}
 	async #enqueue(operation, signal) {
 		checkAbort(signal);
-		let started = false;
+		const cleanup = new AbortController();
 		const next = this.#chain.then(async () => {
-			started = true;
+			cleanup.abort();
 			checkAbort(signal);
 			return operation();
 		});
 		this.#chain = next.then(() => {}, () => {});
 		if (signal === void 0) return next;
-		const cleanup = new AbortController();
 		return new Promise((resolve, reject) => {
 			signal.addEventListener("abort", () => {
-				if (started) return;
 				try {
 					checkAbort(signal);
 				} catch (error) {
@@ -1532,7 +1555,6 @@ var JSONDriver = class {
 			metadata: owned,
 			tables
 		};
-		let dispatched = false;
 		try {
 			await mkdir(dirname(this.#path), { recursive: true });
 			const serialized = JSON.stringify(payload, null, 2);
@@ -1543,35 +1565,35 @@ var JSONDriver = class {
 				signal
 			});
 			checkAbort(signal);
-			dispatched = true;
+		} catch (error) {
+			const aborted = attempt(() => checkAbort(signal));
+			await this.#persistFailure(aborted.success ? error : aborted.error, temp);
+		}
+		try {
 			await rename(temp, this.#path);
 		} catch (error) {
-			let cause = error;
-			if (!dispatched) try {
-				checkAbort(signal);
-			} catch (abort) {
-				cause = abort;
-			}
-			try {
-				await rm(temp, { force: true });
-			} catch (cleanup) {
-				if (!matchesAbsentPath(cleanup)) throw new DatabaseError("DRIVER", "Failed to persist and clean the database file", {
-					path: this.#path,
-					temp,
-					cause,
-					cleanup
-				});
-			}
-			if (isDatabaseError(cause) && cause.code === "ABORTED") throw cause;
-			throw new DatabaseError("DRIVER", "Failed to persist the database file", {
+			await this.#persistFailure(error, temp);
+		}
+	}
+	async #persistFailure(cause, temp) {
+		try {
+			await rm(temp, { force: true });
+		} catch (cleanup) {
+			if (!matchesAbsentPath(cleanup)) throw new DatabaseError("DRIVER", "Failed to persist and clean the database file", {
 				path: this.#path,
-				cause
+				temp,
+				cause,
+				cleanup
 			});
 		}
+		if (isDatabaseError(cause) && cause.code === "ABORTED") throw cause;
+		throw new DatabaseError("DRIVER", "Failed to persist the database file", {
+			path: this.#path,
+			cause
+		});
 	}
 };
-//#endregion
-//#region src/server/drivers/SQLiteDriver.ts
+// src/server/drivers/SQLiteDriver.ts
 /**
 * Implements the {@link DriverInterface} over SQLite — the server-native, trusted-mode
 * backend built on the published `@orkestrel/sqlite` synchronous wrapper.
@@ -1626,9 +1648,7 @@ var SQLiteDriver = class {
 	#database;
 	#schema = /* @__PURE__ */ new Map();
 	#identities = /* @__PURE__ */ new Map();
-	#transaction;
-	#candidateSchema;
-	#candidateIdentities;
+	#transactions = /* @__PURE__ */ new Set();
 	constructor(options = {}) {
 		this.#path = options.path ?? ":memory:";
 		this.#options = options;
@@ -1776,36 +1796,22 @@ var SQLiteDriver = class {
 		this.#root();
 		const database = this.#require();
 		this.#guard(() => database.begin());
-		const token = {};
-		this.#transaction = token;
-		this.#candidateSchema = new Map(this.#schema);
-		this.#candidateIdentities = new Map(this.#identities);
+		const token = new SQLiteTransaction(this.#schema, this.#identities);
+		this.#transactions.add(token);
 		try {
-			let value;
-			try {
-				value = await scope(this.#capability(token));
-			} catch (error) {
-				this.#guard(() => database.rollback());
-				throw error;
-			}
+			const value = await this.#invokeTransaction(scope, token, database);
 			try {
 				this.#guard(() => database.commit());
 			} catch (error) {
 				if (database.transacting) this.#guard(() => database.rollback());
 				throw error;
 			}
-			const schema = this.#candidateSchema;
-			const identities = this.#candidateIdentities;
-			if (schema === void 0 || identities === void 0) throw new DatabaseError("CONFLICT", "Transaction scope has settled");
-			this.#schema = schema;
-			this.#identities = identities;
+			this.#requireTransaction(token);
+			this.#schema = new Map(token.schema);
+			this.#identities = new Map(token.identities);
 			return value;
 		} finally {
-			if (this.#transaction === token) {
-				this.#transaction = void 0;
-				this.#candidateSchema = void 0;
-				this.#candidateIdentities = void 0;
-			}
+			this.#transactions.delete(token);
 		}
 	}
 	/**
@@ -1996,17 +2002,12 @@ var SQLiteDriver = class {
 		}
 		const offset = input.offset ?? 0;
 		const limit = input.limit;
-		let skipped = 0;
-		let yielded = 0;
+		const page = new StreamPage(offset);
 		for await (const row of this.#scan(table)) {
-			if (limit !== void 0 && yielded >= limit) return;
+			if (limit !== void 0 && page.count >= limit) return;
 			if (conditions.length > 0 && !matchesQuery(row, conditions)) continue;
-			if (skipped < offset) {
-				skipped += 1;
-				continue;
-			}
+			if (!page.next()) continue;
 			yield row;
-			yielded += 1;
 		}
 	}
 	async *#iterate(schema, sql, parameters = []) {
@@ -2131,16 +2132,13 @@ var SQLiteDriver = class {
 			table: METADATA_TABLE,
 			aspect: "metadata"
 		});
-		let parsed;
-		try {
-			parsed = JSON.parse(text);
-		} catch (error) {
-			throw new DatabaseError("DRIVER", "Stored SQLite metadata JSON is invalid", {
-				table: METADATA_TABLE,
-				aspect: "metadata",
-				cause: error
-			});
-		}
+		const decoded = attempt(() => JSON.parse(text));
+		if (!decoded.success) throw new DatabaseError("DRIVER", "Stored SQLite metadata JSON is invalid", {
+			table: METADATA_TABLE,
+			aspect: "metadata",
+			cause: decoded.error
+		});
+		const parsed = decoded.value;
 		if (!isArray(parsed)) throw new DatabaseError("DRIVER", "Stored SQLite metadata schema is invalid", {
 			table: METADATA_TABLE,
 			aspect: "metadata"
@@ -2168,6 +2166,14 @@ var SQLiteDriver = class {
 	#writeMetadata(database, metadata) {
 		database.prepare("INSERT OR REPLACE INTO " + quoteIdentifier(METADATA_TABLE) + " (\"id\", \"version\", \"schema\") VALUES (1, ?, ?)").execute([metadata.version, JSON.stringify(metadata.schema)]);
 	}
+	async #invokeTransaction(scope, token, database) {
+		try {
+			return await scope(this.#capability(token));
+		} catch (error) {
+			this.#guard(() => database.rollback());
+			throw error;
+		}
+	}
 	#capability(token) {
 		return {
 			read: this.#readTransaction.bind(this, token),
@@ -2215,9 +2221,8 @@ var SQLiteDriver = class {
 		this.#requireTransaction(token);
 		const database = this.#require();
 		const owned = cloneMigrationInput(input);
-		const candidate = this.#candidateSchema;
-		const identities = this.#candidateIdentities;
-		if (candidate === void 0 || identities === void 0) throw new DatabaseError("CONFLICT", "Transaction scope has settled");
+		const candidate = token.schema;
+		const identities = token.identities;
 		const projected = projectMigrationSchema([...candidate.values()], owned.plan.steps);
 		const projectedIdentities = this.#projectIdentities(identities, owned.plan.steps);
 		if (owned.metadata !== void 0 && !equalsValue(normalizeDriverSchema(owned.metadata.schema), projected)) throw new DatabaseError("MIGRATION", "Migration metadata schema does not match the plan", {
@@ -2239,8 +2244,7 @@ var SQLiteDriver = class {
 				throw error;
 			}
 		});
-		this.#candidateSchema = new Map(projected.map((table) => [table.name, table]));
-		this.#candidateIdentities = projectedIdentities;
+		token.project(projected, projectedIdentities);
 	}
 	async #metadataTransaction(token) {
 		this.#requireTransaction(token);
@@ -2251,10 +2255,10 @@ var SQLiteDriver = class {
 		await this.#stamp(metadata);
 	}
 	#requireTransaction(token) {
-		if (this.#transaction !== token) throw new DatabaseError("CONFLICT", "Transaction scope has settled");
+		if (!this.#transactions.has(token)) throw new DatabaseError("CONFLICT", "Transaction scope has settled");
 	}
 	#root() {
-		if (this.#transaction !== void 0) throw new DatabaseError("CONFLICT", "A transaction is active on this driver");
+		if (this.#transactions.size !== 0) throw new DatabaseError("CONFLICT", "A transaction is active on this driver");
 	}
 	#guard(operation) {
 		try {
@@ -2297,7 +2301,8 @@ var SQLiteDriver = class {
 	}
 	#table(name) {
 		this.#require();
-		const schema = (this.#candidateSchema ?? this.#schema).get(name);
+		const [transaction] = this.#transactions;
+		const schema = (transaction?.schema ?? this.#schema).get(name);
 		if (schema === void 0) throw new DatabaseError("NOT_FOUND", `Table '${name}' is not in the schema`, { table: name });
 		return schema;
 	}
@@ -2313,8 +2318,7 @@ var SQLiteDriver = class {
 		for (const step of input.plan.steps) for (const sql of stepToSQL(step)) database.execute(sql);
 	}
 };
-//#endregion
-//#region src/server/factories.ts
+// src/server/factories.ts
 /**
 * Creates a persistent JSON-file {@link DriverInterface} for a given path.
 *
@@ -2388,7 +2392,6 @@ function createJSONDriver(path) {
 function createSQLiteDriver(options) {
 	return new SQLiteDriver(options);
 }
-//#endregion
-export { EXACT_COLUMN_STORAGE, EXACT_RANGE_COLUMN_STORAGE, JSONDriver, METADATA_TABLE, SQLiteDriver, compileAggregateSQL, compileColumnSQL, compileConditionSQL, compileFieldSQL, compileJSONTypeSQL, compileOrderSQL, compilePageSQL, compileQuerySQL, compileWhereSQL, createJSONDriver, createSQLiteDriver, decodeRow, decodeValue, deriveSQLiteIndexName, encodeRow, encodeValue, extractValues, inferValueStorage, matchesAbsentPath, matchesAggregateExactly, matchesConditionExactly, matchesDeclaredStorage, matchesOrderExactly, matchesQueryExactly, matchesSQLiteAffinity, quoteIdentifier, schemaToIndexes, schemaToTable, stepToSQL };
+export { EXACT_COLUMN_STORAGE, EXACT_RANGE_COLUMN_STORAGE, JSONDriver, JSONTransaction, METADATA_TABLE, SQLiteDriver, SQLiteTransaction, compileAggregateSQL, compileBoundSQL, compileColumnSQL, compileConditionSQL, compileFieldSQL, compileJSONTypeSQL, compileOrderSQL, compilePageSQL, compileQuerySQL, compileWhereSQL, createJSONDriver, createSQLiteDriver, decodeRow, decodeValue, deriveSQLiteIndexName, encodeRow, encodeValue, extractValues, inferValueStorage, matchesAbsentPath, matchesAggregateExactly, matchesConditionExactly, matchesDeclaredStorage, matchesOrderExactly, matchesQueryExactly, matchesSQLiteAffinity, quoteIdentifier, schemaToIndexes, schemaToTable, stepToSQL };
 
 //# sourceMappingURL=index.js.map