@orkestrel/database 0.0.13 → 0.0.15

package/dist/src/server/index.js

@@ -1,26 +1,26 @@
 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, isBoolean, isFiniteNumber, isRecord, isString } from "@orkestrel/contract";
+import { 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
 /**
-* Lists the declared {@link ColumnStorage}s whose SQL EQUALITY comparisons (`equals` /
+* Lists the declared {@link ColumnStorage}s whose SQL equality comparisons (`equals` /
 * `not` / `any` / `none`) and `starts` / `ends` compiles are provably
 * engine-exact under declared-type trust — `text` / `integer` / `real` /
 * `boolean`; a `json` or `blob` column always refines instead.
 *
 * @remarks
-* This set governs equality and prefix/suffix matching only. RANGE
+* This set governs equality and prefix/suffix matching only. Range
 * comparisons (`above` / `below` / `from` / `to` / `between`) and `ORDER BY`
-* are exact for `integer` / `real` / `boolean` but NOT for `text`: compiled
+* are exact for `integer` / `real` / `boolean` but not for `text`: compiled
 * SQL orders/ranges under SQLite's default BINARY collation, which compares
-* TEXT byte-for-byte as UTF-8 — equivalent to Unicode CODE-POINT order —
+* TEXT byte-for-byte as UTF-8 — equivalent to Unicode code-point order —
 * while the core engine's `compareValues` orders JS strings with `<`, which
-* compares UTF-16 CODE-UNIT order. The two orders diverge for supplementary-
+* compares UTF-16 code-unit order. The two orders diverge for supplementary-
 * plane characters (code points ≥ U+10000, for example many emoji): a lead surrogate
-* (`\uD800`–`\uDBFF`) sorts BELOW ``–`￿` in code-unit order, while
-* its code point sorts ABOVE them. So `matchesConditionExactly`'s range family and
+* (`\uD800`–`\uDBFF`) sorts below ``–`￿` in code-unit order, while
+* its code point sorts above them. So `matchesConditionExactly`'s range family and
 * `matchesOrderExactly` exclude `text`, refining through the core engine instead.
 */
 var EXACT_COLUMN_STORAGE = Object.freeze([
@@ -30,7 +30,7 @@ var EXACT_COLUMN_STORAGE = Object.freeze([
 	"boolean"
 ]);
 /**
-* Lists the declared {@link ColumnStorage}s whose SQL RANGE comparisons
+* Lists the declared {@link ColumnStorage}s whose SQL range comparisons
 * (`above` / `below` / `from` / `to` / `between`) and `ORDER BY` compiles are
 * provably engine-exact — `integer` / `real` / `boolean` only. `text` is
 * excluded: see {@link EXACT_COLUMN_STORAGE}'s remarks for the BINARY-collation
@@ -82,7 +82,7 @@ var METADATA_TABLE = "_metadata";
 * ```
 */
 function matchesAbsentPath(error) {
-	if (!(error instanceof Error) || !("code" in error)) return false;
+	if (!isError(error) || !("code" in error)) return false;
 	return error.code === "ENOENT" || error.code === "ENOTDIR";
 }
 /**
@@ -90,7 +90,7 @@ function matchesAbsentPath(error) {
 * — the operand side of the declared-type-trust proof.
 *
 * @remarks
-* `text` ↔ string, `integer` / `real` ↔ FINITE number (`NaN` / `±Infinity`
+* `text` ↔ string, `integer` / `real` ↔ finite number (`NaN` / `±Infinity`
 * fail), `boolean` ↔ boolean. Backs {@link matchesConditionExactly}'s operand checks.
 *
 * @param value - The condition operand to test
@@ -109,7 +109,7 @@ function matchesDeclaredStorage(value, storage) {
 	return isFiniteNumber(value);
 }
 /**
-* Reports whether one {@link Condition} compiles to SQL that is PROVABLY
+* Reports whether one {@link Condition} compiles to SQL that is provably
 * identical to the core engine's `matchesCondition` for every value its
 * column's declared type can store.
 *
@@ -123,18 +123,18 @@ function matchesDeclaredStorage(value, storage) {
 * Required non-null `equals` / `not` require an operand matching the declared
 * storage and exclude `json` / `blob`. `above` / `below` / `from` / `to` /
 * `between` are exact only for {@link EXACT_RANGE_COLUMN_STORAGE} (`integer` /
-* `real` / `boolean`) — a `text` column's range conditions REFINE, because
-* SQLite's default BINARY collation orders TEXT by Unicode CODE POINT while
-* the core engine's `compareValues` orders JS strings by UTF-16 CODE UNIT,
+* `real` / `boolean`) — a `text` column's range conditions refine, because
+* SQLite's default BINARY collation orders TEXT by Unicode code point while
+* the core engine's `compareValues` orders JS strings by UTF-16 code unit,
 * and the two diverge for supplementary-plane characters (see
 * {@link EXACT_COLUMN_STORAGE}'s remarks for the full rationale).
-* `any` / `none` require a NON-EMPTY list where every element matches (an empty
+* `any` / `none` require a non-empty list where every element matches (an empty
 * list is exact under neither: the engine's `any([])` matches nothing while
 * `none([])` matches everything, and SQL `IN ()` is a syntax error) — these
 * stay exact on `text` (byte equality is collation-independent and engine-
 * identical). `starts` / `ends` are exact only on a `text` column with a
 * string operand (case-sensitive `substr` compile, see {@link compileConditionSQL}) —
-* likewise collation-independent. `like` / `glob` are NEVER exact — SQLite
+* likewise collation-independent. `like` / `glob` are never exact — SQLite
 * `LIKE` folds case ASCII-only against the engine's Unicode fold, and `GLOB`
 * has character classes the engine treats literally.
 *
@@ -174,11 +174,14 @@ function matchesConditionExactly(condition, schema) {
 * @remarks
 * `false` for a nested `FieldPath`, a column absent from `schema`, or a
 * declared type outside {@link EXACT_RANGE_COLUMN_STORAGE} (`integer` / `real` /
-* `boolean`). `text` is NOT exact here: SQLite's default BINARY collation
+* `boolean`). `text` is not exact here: SQLite's default BINARY collation
 * orders TEXT by Unicode code point while the core engine's `compareValues`
 * orders JS strings by UTF-16 code unit, and the two diverge for
 * supplementary-plane characters (see {@link EXACT_COLUMN_STORAGE}'s remarks) —
-* a `text` order term REFINES through the core engine instead.
+* a `text` order term refines through the core engine instead. The column must
+* also be required and non-null: an optional or nullable column refines, because
+* SQL orders its `NULL`s ahead of every value while the core total order ranks
+* `undefined` before `null` before every other value.
 *
 * @param order - The order term to test
 * @param schema - The table's schema
@@ -195,6 +198,10 @@ function matchesOrderExactly(order, schema) {
 * every order term is exact. `limit` / `offset` never affect exactness (SQL
 * `LIMIT` / `OFFSET` are always engine-identical).
 *
+* @remarks
+* The gate {@link import('./drivers/SQLiteDriver.js').SQLiteDriver} checks before
+* trusting a native SQL read over a full-scan refine through the core engine.
+*
 * @param input - The query input to test
 * @param schema - The table's schema
 * @returns True if every part of `input` is exact; false otherwise
@@ -285,16 +292,16 @@ function encodeValue(value, column) {
 		return column.storage === "text" || column.storage === "json" ? /* @__PURE__ */ new Uint8Array() : String(null);
 	}
 	switch (column.storage) {
-		case "boolean": return typeof value === "boolean" ? value ? 1 : 0 : null;
+		case "boolean": return isBoolean(value) ? value ? 1 : 0 : null;
 		case "json": try {
 			return JSON.stringify(cloneJSONValue(value));
 		} catch {
 			return null;
 		}
-		case "integer": return typeof value === "bigint" || typeof value === "number" && Number.isFinite(value) && Number.isInteger(value) ? value : null;
-		case "real": return typeof value === "bigint" || typeof value === "number" && Number.isFinite(value) ? value : null;
-		case "text": return typeof value === "string" ? value : null;
-		case "blob": return value instanceof Uint8Array ? value : null;
+		case "integer": return isBigInt(value) || isFiniteNumber(value) && isInteger(value) ? value : null;
+		case "real": return isBigInt(value) || isFiniteNumber(value) ? value : null;
+		case "text": return isString(value) ? value : null;
+		case "blob": return isUint8Array(value) ? value : null;
 	}
 }
 /**
@@ -319,23 +326,23 @@ function encodeValue(value, column) {
 */
 function decodeValue(value, column) {
 	if (value === null) return column.nullable && !column.optional ? null : void 0;
-	if (column.optional && column.nullable && (column.storage === "text" || column.storage === "json" ? value instanceof Uint8Array && value.byteLength === 0 : value === String(null))) return null;
+	if (column.optional && column.nullable && (column.storage === "text" || column.storage === "json" ? isUint8Array(value) && value.byteLength === 0 : value === String(null))) return null;
 	switch (column.storage) {
 		case "boolean":
 			if (value === 0 || value === 0n) return false;
 			if (value === 1 || value === 1n) return true;
 			return;
 		case "json":
-			if (typeof value !== "string") return void 0;
+			if (!isString(value)) return void 0;
 			try {
 				return structuredClone(cloneJSONValue(JSON.parse(value)));
 			} catch {
 				return;
 			}
-		case "integer": return typeof value === "bigint" || typeof value === "number" && Number.isFinite(value) && Number.isInteger(value) ? value : void 0;
-		case "real": return typeof value === "bigint" || typeof value === "number" && Number.isFinite(value) ? value : void 0;
-		case "text": return typeof value === "string" ? value : void 0;
-		case "blob": return value instanceof Uint8Array ? value : void 0;
+		case "integer": return isBigInt(value) || isFiniteNumber(value) && isInteger(value) ? value : void 0;
+		case "real": return isBigInt(value) || isFiniteNumber(value) ? value : void 0;
+		case "text": return isString(value) ? value : void 0;
+		case "blob": return isUint8Array(value) ? value : void 0;
 	}
 }
 /**
@@ -426,7 +433,7 @@ function decodeRow(row, schema) {
 * so a plan-built index name always matches one `open` would have created.
 *
 * @remarks
-* A naive `idx_<table>_<cols joined by _>` is AMBIGUOUS: table `'a_b'` with
+* A naive `idx_<table>_<cols joined by _>` is ambiguous: table `'a_b'` with
 * column `'c'` and table `'a'` with columns `['b', 'c']` both produce
 * `idx_a_b_c`. This encodes each part (the table name, then each column name)
 * length-prefixed (`<len>_<part>`) so the boundary between parts is always
@@ -450,7 +457,7 @@ function deriveSQLiteIndexName(table, columns) {
 //#region src/server/inferers.ts
 /**
 * Reads the storage type a nested (`json_extract`) operand encodes as from its
-* RUNTIME value — NOT `json`.
+* runtime value, never as `json`.
 *
 * @remarks
 * `json_extract` returns the unquoted, natively-typed scalar (a JSON boolean as
@@ -470,10 +477,10 @@ function deriveSQLiteIndexName(table, columns) {
 * ```
 */
 function inferValueStorage(value) {
-	if (typeof value === "boolean") return "boolean";
-	if (typeof value === "number") return Number.isInteger(value) ? "integer" : "real";
-	if (typeof value === "bigint") return "integer";
-	if (typeof value === "object" && value !== null) return "json";
+	if (isBoolean(value)) return "boolean";
+	if (isNumber(value)) return isInteger(value) ? "integer" : "real";
+	if (isBigInt(value)) return "integer";
+	if (isObject(value)) return "json";
 	return "text";
 }
 //#endregion
@@ -497,6 +504,10 @@ function compileColumnSQL(storage) {
 /**
 * Compiles a {@link FieldPath} to the SQL expression that reads it.
 *
+* @remarks
+* A flat path compiles to the quoted column; a nested path compiles to a
+* `json_extract` over the head column with the rest of the path as its accessor.
+*
 * @param path - The field path
 * @returns The SQL expression selecting the value
 */
@@ -524,9 +535,9 @@ function compileAggregateSQL(operation, column) {
 	}
 }
 /**
-* Compiles a NESTED {@link FieldPath} to the `json_type(<col>, <path>)` SQL
+* Compiles a nested {@link FieldPath} to the `json_type(<col>, <path>)` SQL
 * expression — the {@link compileFieldSQL} `json_extract` sibling used to tell a
-* PRESENT JSON `null` apart from an ABSENT path (both read back as SQL `NULL`
+* present JSON `null` apart from an absent path (both read back as SQL `NULL`
 * through `json_extract`, but `json_type` reports `'null'` for the former and
 * SQL `NULL` for the latter).
 *
@@ -550,20 +561,20 @@ function compileJSONTypeSQL(path) {
 *
 * @remarks
 * Every operand is run through `encodeValue`, so a bound value matches the SQL
-* the column side compiles to. A flat column encodes operands with its DECLARED
+* the column side compiles to. A flat column encodes operands with its declared
 * schema type (a flat `json` column → `JSON.stringify`); a nested `FieldPath`
-* encodes each operand as the NATIVE scalar `json_extract` returns, derived from
+* encodes each operand as the native scalar `json_extract` returns, derived from
 * the operand's runtime type (per-operand, since `between` / `any` / `none` can
 * mix types). `any` / `none` collapse an empty list to a constant (`0` matches
 * nothing, `1` matches all) with no parameters.
 *
-* The core engine's total order ranks `undefined` (rank 0) BELOW `null`
-* (rank 1) (see `compareValues`), so a MISSING/`NULL` column MATCHES
+* The core engine's total order ranks `undefined` (rank 0) below `null`
+* (rank 1) (see `compareValues`), so a missing/`NULL` column matches
 * `below` / `to` / a scalar `not` / `none` — the opposite of raw SQL, where a
 * comparison against `NULL` is `NULL` (excluded). This fragment replicates the
 * engine exactly. Truth table (`value` = the engine's decoded field read; a
-* FLAT column's stored `NULL` decodes to `undefined` per `decodeRow`, so a
-* flat `value` is NEVER a present `null` — only a NESTED path can be
+* flat column's stored `NULL` decodes to `undefined` per `decodeRow`, so a
+* flat `value` is never a present `null` — only a nested path can be
 * present-but-`null`):
 *
 * ```text
@@ -589,15 +600,15 @@ function compileJSONTypeSQL(path) {
 * refines every optional or nullable scalar comparison through the core engine.
 * This compiler still emits a total SQL fragment for direct consumers.
 *
-* A NESTED path can be present-but-`null` (a stored JSON `null`), which
-* `json_extract` reads back as SQL `NULL` — indistinguishable from an ABSENT
+* A nested path can be present-but-`null` (a stored JSON `null`), which
+* `json_extract` reads back as SQL `NULL` — indistinguishable from an absent
 * path. `json_type(col, path)` disambiguates them (`'null'` for present-null,
 * SQL `NULL` for absent), so nested `equals` / `not` against a `null` operand
 * compile through `json_type` instead of `IS NULL` / `IS NOT NULL`.
 *
 * Every other MATCH-on-null-or-absent row is expressed uniformly (flat and
 * nested alike) as `(<column> <op> ? OR <column> IS NULL)` — for a nested
-* path, `json_extract` already collapses BOTH absent and present-null to SQL
+* path, `json_extract` already collapses both absent and present-null to SQL
 * `NULL`, so `IS NULL` catches both in one clause; for a flat column there is
 * only the absent case to catch.
 *
@@ -741,7 +752,7 @@ function compileConditionSQL(condition, schema) {
 * @remarks
 * The first condition's connector is ignored, per the {@link Condition} types.
 * Every fragment (see {@link compileConditionSQL}'s truth table) replicates the core
-* engine's total order EXACTLY under SQL's three-valued NULL logic, so this
+* engine's total order exactly under SQL's three-valued NULL logic, so this
 * clause matches `applyQuery` row-for-row over the same table — a native
 * `records` / `count` read never disagrees with a scan-and-filter fallback.
 *
@@ -859,7 +870,7 @@ function compilePageSQL(limit, offset) {
 * `FieldPath` (a `json_extract` read) encodes each operand as the native scalar
 * the extract returns — derived from the operand's runtime type — so it compares.
 * Every operator maps per the databases guide's operator table, with
-* `starts` / `ends` compiling to a CODE-POINT `substr` slice guarded by
+* `starts` / `ends` compiling to a code-point `substr` slice guarded by
 * `typeof(<column>) = 'text'` (case-sensitive, matching the engine's
 * `String.prototype.startsWith` / `endsWith`) and an empty `any` / `none` list
 * collapsing to a constant. An `undefined` input (or one with no parts)
@@ -902,6 +913,10 @@ function schemaToTable(schema) {
 /**
 * Projects a {@link TableSchema} to its declared SQLite indexes.
 *
+* @remarks
+* Each statement is a `CREATE INDEX IF NOT EXISTS` named by
+* {@link deriveSQLiteIndexName}, so a reopen re-issues the set safely.
+*
 * @param schema - The table schema
 * @returns One statement per declared index
 */
@@ -911,6 +926,10 @@ function schemaToIndexes(schema) {
 /**
 * Projects one {@link MigrationStep} to SQLite DDL.
 *
+* @remarks
+* These are the statements the SQLite driver's `migrate` executes for the step,
+* inside whichever native transaction is active.
+*
 * @param step - The migration step
 * @returns The statements that apply the step
 */
@@ -1376,7 +1395,7 @@ var JSONDriver = class {
 	async #hydrate(memory, schema, tables) {
 		for (const table of schema) {
 			const rows = tables[table.name];
-			if (!Array.isArray(rows)) throw new DatabaseError("DRIVER", "Stored JSON table is invalid", {
+			if (!isArray(rows)) throw new DatabaseError("DRIVER", "Stored JSON table is invalid", {
 				path: this.#path,
 				table: table.name,
 				aspect: "container"
@@ -1954,7 +1973,7 @@ var SQLiteDriver = class {
 			const keys = [];
 			for (const row of rows) {
 				const value = row[schema.primary];
-				if (typeof value === "string" || typeof value === "number") keys.push(value);
+				if (isString(value) || isNumber(value)) keys.push(value);
 			}
 			return keys;
 		});
@@ -2087,7 +2106,7 @@ var SQLiteDriver = class {
 			});
 			for (const [position, column] of group.entries()) {
 				const entry = entries.find((candidate) => candidate.seqno === position || candidate.seqno === BigInt(position));
-				const stored = entry !== void 0 && (typeof entry.cid === "number" && Number.isInteger(entry.cid) && entry.cid >= 0 || typeof entry.cid === "bigint" && entry.cid >= 0n);
+				const stored = entry !== void 0 && (isInteger(entry.cid) && entry.cid >= 0 || isBigInt(entry.cid) && entry.cid >= 0n);
 				if (entry === void 0 || entry.name !== column || !stored || entry.desc !== 0 && entry.desc !== 0n || entry.coll !== "BINARY") throw new DatabaseError("DRIVER", "SQLite index column does not match its declaration", {
 					table: schema.name,
 					aspect: "index",
@@ -2104,11 +2123,11 @@ var SQLiteDriver = class {
 		if (row === void 0) return void 0;
 		const version = row.version;
 		const text = row.schema;
-		if (typeof text !== "string") throw new DatabaseError("DRIVER", "Stored SQLite metadata schema is invalid", {
+		if (!isString(text)) throw new DatabaseError("DRIVER", "Stored SQLite metadata schema is invalid", {
 			table: METADATA_TABLE,
 			aspect: "metadata"
 		});
-		if (typeof version !== "number" && typeof version !== "bigint") throw new DatabaseError("DRIVER", "Stored SQLite metadata version is invalid", {
+		if (!isNumber(version) && !isBigInt(version)) throw new DatabaseError("DRIVER", "Stored SQLite metadata version is invalid", {
 			table: METADATA_TABLE,
 			aspect: "metadata"
 		});
@@ -2122,7 +2141,7 @@ var SQLiteDriver = class {
 				cause: error
 			});
 		}
-		if (!Array.isArray(parsed)) throw new DatabaseError("DRIVER", "Stored SQLite metadata schema is invalid", {
+		if (!isArray(parsed)) throw new DatabaseError("DRIVER", "Stored SQLite metadata schema is invalid", {
 			table: METADATA_TABLE,
 			aspect: "metadata"
 		});
@@ -2241,7 +2260,7 @@ var SQLiteDriver = class {
 		try {
 			return operation();
 		} catch (error) {
-			if (error instanceof DatabaseError) throw error;
+			if (isDatabaseError(error)) throw error;
 			if (isSQLiteError(error)) {
 				if (error.code === "CONSTRAINT") throw new DatabaseError("CONFLICT", error.message, {
 					cause: error,
@@ -2261,7 +2280,7 @@ var SQLiteDriver = class {
 					code: error.code
 				});
 			}
-			throw new DatabaseError("DRIVER", error instanceof Error ? error.message : String(error), { cause: error });
+			throw new DatabaseError("DRIVER", isError(error) ? error.message : String(error), { cause: error });
 		}
 	}
 	#require() {
@@ -2297,7 +2316,7 @@ var SQLiteDriver = class {
 //#endregion
 //#region src/server/factories.ts
 /**
-* Creates a persistent JSON-file {@link DriverInterface} for the core database layer.
+* Creates a persistent JSON-file {@link DriverInterface} for a given path.
 *
 * @remarks
 * Pass it to `createDatabase` from `@orkestrel/database` to run the typed
@@ -2330,7 +2349,8 @@ function createJSONDriver(path) {
 	return new JSONDriver(path);
 }
 /**
-* Creates a trusted-mode SQLite {@link DriverInterface} for the core database layer.
+* Creates a trusted-mode, server-native SQLite {@link DriverInterface} for a database path,
+* or for `:memory:` when the options bag omits one.
 *
 * @remarks
 * Pass it to `createDatabase` from `@orkestrel/database` to run the typed