@orkestrel/database 0.0.4 → 0.0.6

package/dist/src/server/index.cjs

@@ -1,29 +1,11 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _src_core = require("../core/index.cjs");
 let _orkestrel_contract = require("@orkestrel/contract");
 let node_crypto = require("node:crypto");
-let _src_core = require("../core/index.cjs");
 let node_fs_promises = require("node:fs/promises");
 let node_path = require("node:path");
 let _orkestrel_sqlite = require("@orkestrel/sqlite");
-//#region src/server/helpers.ts
-/**
-* Generate a fresh unique key — a v4 UUID string, backed by `node:crypto`.
-*
-* @remarks
-* Supply this as {@link import('@orkestrel/database').DatabaseOptions.key} so a table mints
-* a key when a written row lacks its primary-key value. Strings work as keys on
-* every backend; supply your own key values directly to use numeric keys instead.
-*
-* @returns A new UUID string
-*
-* @example
-* ```ts
-* const db = createDatabase({ driver, tables, key: generateKey })
-* ```
-*/
-function generateKey() {
-	return (0, node_crypto.randomUUID)();
-}
+//#region src/server/constants.ts
 /**
 * The declared {@link ColumnType}s whose SQL EQUALITY comparisons (`equals` /
 * `not` / `any` / `none`) and `starts` / `ends` compiles are provably
@@ -46,12 +28,12 @@ function generateKey() {
 * values are BMP-only, or a custom SQLite collation matching `compareValues`
 * is registered) could restore native text ranges/ordering.
 */
-var EXACT_COLUMN_TYPES = [
+var EXACT_COLUMN_TYPES = Object.freeze([
 	"text",
 	"integer",
 	"real",
 	"boolean"
-];
+]);
 /**
 * The declared {@link ColumnType}s whose SQL RANGE comparisons
 * (`above` / `below` / `from` / `to` / `between`) and `ORDER BY` compiles are
@@ -60,11 +42,41 @@ var EXACT_COLUMN_TYPES = [
 * (code-point) vs. JS `<` (code-unit) divergence on supplementary-plane
 * characters.
 */
-var EXACT_RANGE_COLUMN_TYPES = [
+var EXACT_RANGE_COLUMN_TYPES = Object.freeze([
 	"integer",
 	"real",
 	"boolean"
-];
+]);
+/**
+* The reserved metadata table the {@link SQLiteDriver} creates on `open` to
+* persist its stamped `DriverMeta` (`version` + declared schema JSON) — the
+* SQLite realization of the `meta` / `stamp` driver hooks.
+*
+* @remarks
+* A single-row table (`id = 1`). A user table named `_meta` collides with the
+* reservation — the caller's concern to avoid, documented on the driver class.
+*/
+var META_TABLE = "_meta";
+//#endregion
+//#region src/server/helpers.ts
+/**
+* Generate a fresh unique key — a v4 UUID string, backed by `node:crypto`.
+*
+* @remarks
+* Supply this as {@link import('@orkestrel/database').DatabaseOptions.key} so a table mints
+* a key when a written row lacks its primary-key value. Strings work as keys on
+* every backend; supply your own key values directly to use numeric keys instead.
+*
+* @returns A new UUID string
+*
+* @example
+* ```ts
+* const db = createDatabase({ driver, tables, key: generateKey })
+* ```
+*/
+function generateKey() {
+	return (0, node_crypto.randomUUID)();
+}
 /**
 * Whether a value's runtime type matches a column's declared exact type —
 * the operand side of the declared-type-trust proof.
@@ -254,8 +266,10 @@ function quote(identifier) {
 */
 function fieldColumn(path) {
 	if ((0, _orkestrel_contract.isString)(path)) return quote(path);
-	const rest = path.slice(1).map((key) => "." + key.replaceAll("'", "''")).join("");
-	return "json_extract(" + quote(path[0]) + ", '$" + rest + "')";
+	const [column, ...nested] = path;
+	if (column === void 0) throw new _src_core.DatabaseError("VALIDATION", "A field path must contain at least one column");
+	const rest = nested.map((key) => "." + key.replaceAll("'", "''")).join("");
+	return "json_extract(" + quote(column) + ", '$" + rest + "')";
 }
 /**
 * Compile an {@link AggregateFunction} over a {@link FieldPath} to its SQL
@@ -373,6 +387,37 @@ function encodeRow(row, schema) {
 	return result;
 }
 /**
+* Extract a stored row's values in a declared positional order.
+*
+* @remarks
+* SQLite statements bind arrays positionally. Every requested column must be
+* present in `row`; an incomplete backend row is a typed `DRIVER` fault carrying
+* the table and missing column in its context.
+*
+* @param row - The stored SQLite row
+* @param names - The column names in binding order
+* @param table - The owning table name for fault context
+* @returns The row values in the same order as `names`
+* @throws A `DRIVER` {@link DatabaseError} when a requested column is missing
+*
+* @example
+* ```ts
+* extractValues({ id: 'u1', age: 36 }, ['age', 'id'], 'users') // [36, 'u1']
+* ```
+*/
+function extractValues(row, names, table) {
+	const values = [];
+	for (const name of names) {
+		const value = row[name];
+		if (value === void 0) throw new _src_core.DatabaseError("DRIVER", "SQLite row is missing a declared column", {
+			table,
+			column: name
+		});
+		values.push(value);
+	}
+	return values;
+}
+/**
 * Decode a stored {@link SQLiteRow} back to a {@link Row} by its table's schema.
 *
 * @remarks
@@ -395,7 +440,9 @@ function encodeRow(row, schema) {
 function decodeRow(row, schema) {
 	const result = {};
 	for (const column of schema.columns) {
-		const decoded = decodeValue(row[column.name], column.type);
+		const value = row[column.name];
+		if (value === void 0) continue;
+		const decoded = decodeValue(value, column.type);
 		if (decoded !== void 0) result[column.name] = decoded;
 	}
 	return result;
@@ -568,8 +615,10 @@ function stepToSchema(schema, step) {
 * ```
 */
 function jsonTypeColumn(path) {
-	const rest = path.slice(1).map((key) => "." + key.replaceAll("'", "''")).join("");
-	return "json_type(" + quote(path[0]) + ", '$" + rest + "')";
+	const [column, ...nested] = path;
+	if (column === void 0) throw new _src_core.DatabaseError("VALIDATION", "A field path must contain at least one column");
+	const rest = nested.map((key) => "." + key.replaceAll("'", "''")).join("");
+	return "json_type(" + quote(column) + ", '$" + rest + "')";
 }
 /**
 * Escape `\`, `%`, and `_` (each with a leading `\`) so a `starts` / `ends`
@@ -704,21 +753,21 @@ function fragment(condition, schema) {
 	const column = fieldColumn(condition.column);
 	const nested = !(0, _orkestrel_contract.isString)(condition.column);
 	const declared = (0, _orkestrel_contract.isString)(condition.column) ? declaredType(condition.column, schema) : void 0;
-	const encode = (value) => encodeValue(value, nested ? valueType(value) : declared ?? "json");
 	const first = condition.values[0];
 	const second = condition.values[1];
 	const nullOperand = first === null || first === void 0;
 	const jsonType = !(0, _orkestrel_contract.isString)(condition.column) ? jsonTypeColumn(condition.column) : "";
+	let sql;
+	let values;
 	switch (condition.operator) {
 		case "equals":
 			if (nullOperand && nested) return {
 				sql: jsonType + " = 'null'",
 				params: []
 			};
-			return {
-				sql: column + " = ?",
-				params: [encode(first)]
-			};
+			sql = column + " = ?";
+			values = [first];
+			break;
 		case "not":
 			if (nullOperand) {
 				if (nested) return {
@@ -730,38 +779,37 @@ function fragment(condition, schema) {
 					params: []
 				};
 			}
-			return {
-				sql: "(" + column + " != ? OR " + column + " IS NULL)",
-				params: [encode(first)]
-			};
-		case "above": return {
-			sql: column + " > ?",
-			params: [encode(first)]
-		};
-		case "below": return {
-			sql: "(" + column + " < ? OR " + column + " IS NULL)",
-			params: [encode(first)]
-		};
-		case "from": return {
-			sql: column + " >= ?",
-			params: [encode(first)]
-		};
-		case "to": return {
-			sql: "(" + column + " <= ? OR " + column + " IS NULL)",
-			params: [encode(first)]
-		};
-		case "between": return {
-			sql: column + " BETWEEN ? AND ?",
-			params: [encode(first), encode(second)]
-		};
-		case "like": return {
-			sql: column + " LIKE ?",
-			params: [encode(first)]
-		};
-		case "glob": return {
-			sql: column + " GLOB ?",
-			params: [encode(first)]
-		};
+			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;
 		case "starts": {
 			const text = (0, _orkestrel_contract.isString)(first) ? first : "";
 			if (text === "") return {
@@ -769,10 +817,9 @@ function fragment(condition, schema) {
 				params: []
 			};
 			const length = Array.from(text).length;
-			return {
-				sql: "(typeof(" + column + ") = 'text' AND substr(" + column + ", 1, " + length + ") = ?)",
-				params: [encode(first)]
-			};
+			sql = "(typeof(" + column + ") = 'text' AND substr(" + column + ", 1, " + length + ") = ?)";
+			values = [first];
+			break;
 		}
 		case "ends": {
 			const text = (0, _orkestrel_contract.isString)(first) ? first : "";
@@ -781,29 +828,26 @@ function fragment(condition, schema) {
 				params: []
 			};
 			const length = Array.from(text).length;
-			return {
-				sql: "(typeof(" + column + ") = 'text' AND substr(" + column + ", -" + length + ") = ?)",
-				params: [encode(first)]
-			};
+			sql = "(typeof(" + column + ") = 'text' AND substr(" + column + ", -" + length + ") = ?)";
+			values = [first];
+			break;
 		}
 		case "any":
 			if (condition.values.length === 0) return {
 				sql: "0",
 				params: []
 			};
-			return {
-				sql: column + " IN (" + condition.values.map(() => "?").join(", ") + ")",
-				params: condition.values.map(encode)
-			};
+			sql = column + " IN (" + condition.values.map(() => "?").join(", ") + ")";
+			values = condition.values;
+			break;
 		case "none":
 			if (condition.values.length === 0) return {
 				sql: "1",
 				params: []
 			};
-			return {
-				sql: "(" + column + " NOT IN (" + condition.values.map(() => "?").join(", ") + ") OR " + column + " IS NULL)",
-				params: condition.values.map(encode)
-			};
+			sql = "(" + column + " NOT IN (" + condition.values.map(() => "?").join(", ") + ") OR " + column + " IS NULL)";
+			values = condition.values;
+			break;
 		case "absent": return {
 			sql: column + " IS NULL",
 			params: []
@@ -813,6 +857,10 @@ function fragment(condition, schema) {
 			params: []
 		};
 	}
+	return {
+		sql,
+		params: values.map((value) => encodeValue(value, nested ? valueType(value) : declared ?? "json"))
+	};
 }
 /**
 * Fold the conditions into one WHERE clause, parenthesizing progressively
@@ -836,16 +884,17 @@ function fragment(condition, schema) {
 * ```
 */
 function compileWhere(conditions, schema) {
-	if (conditions.length === 0) return {
+	const [first, ...remaining] = conditions;
+	if (first === void 0) return {
 		sql: "",
 		params: []
 	};
-	const head = fragment(conditions[0], schema);
+	const head = fragment(first, schema);
 	let clause = head.sql;
 	const params = [...head.params];
-	for (let index = 1; index < conditions.length; index += 1) {
-		const next = fragment(conditions[index], schema);
-		const operator = conditions[index].connector === "or" ? "OR" : "AND";
+	for (const condition of remaining) {
+		const next = fragment(condition, schema);
+		const operator = condition.connector === "or" ? "OR" : "AND";
 		clause = "(" + clause + " " + operator + " " + next.sql + ")";
 		params.push(...next.params);
 	}
@@ -962,18 +1011,6 @@ function compileCriteria(criteria, schema) {
 	};
 }
 //#endregion
-//#region src/server/constants.ts
-/**
-* The reserved metadata table the {@link SQLiteDriver} creates on `open` to
-* persist its stamped `DriverMeta` (`version` + declared schema JSON) — the
-* SQLite realization of the `meta` / `stamp` driver hooks.
-*
-* @remarks
-* A single-row table (`id = 1`). A user table named `_meta` collides with the
-* reservation — the caller's concern to avoid, documented on the driver class.
-*/
-var META_TABLE = "_meta";
-//#endregion
 //#region src/server/drivers/JSONDriver.ts
 /**
 * A persistent {@link DriverInterface} backed by a single JSON file — the
@@ -1013,6 +1050,7 @@ var JSONDriver = class {
 	#flushCount = 0;
 	#chain = Promise.resolve();
 	#deferring = false;
+	#transaction;
 	constructor(path) {
 		this.#path = path;
 	}
@@ -1081,22 +1119,12 @@ var JSONDriver = class {
 	async transaction() {
 		if (this.#deferring) throw new _src_core.DatabaseError("CONFLICT", "A transaction is already active on this driver", {});
 		const rollback = await this.#memory.snapshot();
+		const token = {};
 		this.#deferring = true;
-		let settled = false;
+		this.#transaction = token;
 		return {
-			commit: async () => {
-				if (settled) throw new _src_core.DatabaseError("CONFLICT", "Transaction already settled", {});
-				settled = true;
-				this.#deferring = false;
-				await this.#flush();
-			},
-			rollback: async () => {
-				if (settled) throw new _src_core.DatabaseError("CONFLICT", "Transaction already settled", {});
-				settled = true;
-				await rollback();
-				this.#deferring = false;
-				await this.#flush();
-			}
+			commit: this.#commit.bind(this, token),
+			rollback: this.#rollback.bind(this, token, rollback)
 		};
 	}
 	async snapshot(tables) {
@@ -1149,6 +1177,19 @@ var JSONDriver = class {
 		this.#schema = schema;
 		await this.#flush();
 	}
+	async #commit(token) {
+		if (this.#transaction !== token) throw new _src_core.DatabaseError("CONFLICT", "Transaction already settled", {});
+		this.#transaction = void 0;
+		this.#deferring = false;
+		await this.#flush();
+	}
+	async #rollback(token, rollback) {
+		if (this.#transaction !== token) throw new _src_core.DatabaseError("CONFLICT", "Transaction already settled", {});
+		this.#transaction = void 0;
+		await rollback();
+		this.#deferring = false;
+		await this.#flush();
+	}
 	async #load() {
 		let raw;
 		try {
@@ -1261,7 +1302,7 @@ var SQLiteDriver = class {
 	#options;
 	#database;
 	#schema = /* @__PURE__ */ new Map();
-	#transacting = false;
+	#transaction;
 	constructor(path, options) {
 		this.#path = path;
 		this.#options = options ?? {};
@@ -1272,9 +1313,9 @@ var SQLiteDriver = class {
 			this.#database?.close();
 			const database = (0, _orkestrel_sqlite.createSQLiteDatabase)({
 				path: this.#path,
-				readonly: this.#options.readonly,
-				timeout: this.#options.timeout,
-				foreignKeys: this.#options.foreignKeys
+				...this.#options.readonly !== void 0 ? { readonly: this.#options.readonly } : {},
+				...this.#options.timeout !== void 0 ? { timeout: this.#options.timeout } : {},
+				...this.#options.foreignKeys !== void 0 ? { foreignKeys: this.#options.foreignKeys } : {}
 			});
 			database.connect();
 			for (const [name, value] of Object.entries(this.#options.pragmas ?? {})) database.pragma(name, value);
@@ -1308,7 +1349,7 @@ var SQLiteDriver = class {
 				[schema.primary]: key
 			}, schema);
 			const names = schema.columns.map((column) => column.name);
-			const values = names.map((name) => encoded[name]);
+			const values = extractValues(encoded, names, table);
 			this.#require().prepare("INSERT OR REPLACE INTO " + quote(table) + " (" + names.map(quote).join(", ") + ") VALUES (" + names.map(() => "?").join(", ") + ")").run(values);
 		});
 	}
@@ -1388,8 +1429,8 @@ var SQLiteDriver = class {
 		if (conditions.every((condition) => isExactCondition(condition, schema))) {
 			const compiled = compileCriteria({
 				conditions,
-				limit: criteria.limit,
-				offset: criteria.offset
+				...criteria.limit !== void 0 ? { limit: criteria.limit } : {},
+				...criteria.offset !== void 0 ? { offset: criteria.offset } : {}
 			}, schema);
 			for (const row of this.#require().prepare("SELECT * FROM " + quote(table) + (compiled.sql === "" ? "" : " " + compiled.sql)).iterate(compiled.params)) yield decodeRow(row, schema);
 			return;
@@ -1421,21 +1462,11 @@ var SQLiteDriver = class {
 	async transaction() {
 		const database = this.#require();
 		this.#guard(() => database.exec("BEGIN"));
-		let settled = false;
-		this.#transacting = true;
+		const token = {};
+		this.#transaction = token;
 		return {
-			commit: async () => {
-				if (settled) throw new _src_core.DatabaseError("CONFLICT", "Transaction already settled", {});
-				settled = true;
-				this.#transacting = false;
-				this.#guard(() => database.exec("COMMIT"));
-			},
-			rollback: async () => {
-				if (settled) throw new _src_core.DatabaseError("CONFLICT", "Transaction already settled", {});
-				settled = true;
-				this.#transacting = false;
-				this.#guard(() => database.exec("ROLLBACK"));
-			}
+			commit: this.#commit.bind(this, token, database),
+			rollback: this.#rollback.bind(this, token, database)
 		};
 	}
 	/**
@@ -1465,7 +1496,7 @@ var SQLiteDriver = class {
 		const database = this.#require();
 		const schema = new Map(this.#schema);
 		this.#guard(() => {
-			if (this.#transacting) this.#applyPlan(database, plan, schema);
+			if (this.#transaction !== void 0) this.#applyPlan(database, plan, schema);
 			else database.transaction(() => this.#applyPlan(database, plan, schema));
 		});
 		this.#schema = schema;
@@ -1525,11 +1556,21 @@ var SQLiteDriver = class {
 				for (const [name, snapshot] of captured) {
 					current.exec("DELETE FROM " + quote(name));
 					const statement = current.prepare("INSERT OR REPLACE INTO " + quote(name) + " (" + snapshot.names.map(quote).join(", ") + ") VALUES (" + snapshot.names.map(() => "?").join(", ") + ")");
-					for (const row of snapshot.rows) statement.run(snapshot.names.map((column) => row[column]));
+					for (const row of snapshot.rows) statement.run(extractValues(row, snapshot.names, name));
 				}
 			});
 		};
 	}
+	async #commit(token, database) {
+		if (this.#transaction !== token) throw new _src_core.DatabaseError("CONFLICT", "Transaction already settled", {});
+		this.#transaction = void 0;
+		this.#guard(() => database.exec("COMMIT"));
+	}
+	async #rollback(token, database) {
+		if (this.#transaction !== token) throw new _src_core.DatabaseError("CONFLICT", "Transaction already settled", {});
+		this.#transaction = void 0;
+		this.#guard(() => database.exec("ROLLBACK"));
+	}
 	#guard(run) {
 		try {
 			return run();
@@ -1678,6 +1719,7 @@ exports.decodeValue = decodeValue;
 exports.encodeRow = encodeRow;
 exports.encodeValue = encodeValue;
 exports.escapeLike = escapeLike;
+exports.extractValues = extractValues;
 exports.fieldColumn = fieldColumn;
 exports.fragment = fragment;
 exports.generateKey = generateKey;