@orkestrel/database 0.0.13 → 0.0.14

package/dist/src/server/index.cjs

@@ -6,22 +6,22 @@ let node_path = require("node:path");
 let _orkestrel_sqlite = require("@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([
@@ -31,7 +31,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
@@ -91,7 +91,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
@@ -110,7 +110,7 @@ function matchesDeclaredStorage(value, storage) {
 	return (0, _orkestrel_contract.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.
 *
@@ -124,18 +124,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.
 *
@@ -175,11 +175,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
@@ -196,6 +199,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
@@ -427,7 +434,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
@@ -451,7 +458,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
@@ -498,6 +505,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
 */
@@ -525,9 +536,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).
 *
@@ -551,20 +562,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
@@ -590,15 +601,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.
 *
@@ -742,7 +753,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.
 *
@@ -860,7 +871,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)
@@ -903,6 +914,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
 */
@@ -912,6 +927,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
 */
@@ -2298,7 +2317,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
@@ -2331,7 +2350,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