@orkestrel/database 0.0.13 → 0.0.15

package/dist/src/server/index.d.ts

@@ -1,26 +1,21 @@
-import { AggregateOperation } from '@orkestrel/database';
-import { AggregateOperation as AggregateOperation_2 } from '@orkestrel/database';
-import { ColumnSchema } from '@orkestrel/database';
-import { ColumnStorage } from '@orkestrel/database';
-import { Condition } from '@orkestrel/database';
-import { DriverInterface } from '@orkestrel/database';
-import { DriverInterface as DriverInterface_2 } from '@orkestrel/database';
-import { DriverMetadata } from '@orkestrel/database';
-import { FieldPath } from '@orkestrel/contract';
-import { Key } from '@orkestrel/database';
-import { MigrationInput } from '@orkestrel/database';
-import { MigrationStep } from '@orkestrel/database';
-import { OperationOptions } from '@orkestrel/database';
-import { Order } from '@orkestrel/database';
-import { QueryInput } from '@orkestrel/database';
-import { QueryInput as QueryInput_2 } from '@orkestrel/database';
-import { Row } from '@orkestrel/database';
-import { Row as Row_2 } from '@orkestrel/database';
-import { SQLiteRow } from '@orkestrel/sqlite';
-import { SQLiteValue } from '@orkestrel/sqlite';
-import { StorageInterface } from '@orkestrel/database';
-import { TableSchema } from '@orkestrel/database';
-import { TableSchema as TableSchema_2 } from '@orkestrel/database';
+import type { AggregateOperation } from '@orkestrel/database';
+import type { ColumnSchema } from '@orkestrel/database';
+import type { ColumnStorage } from '@orkestrel/database';
+import type { Condition } from '@orkestrel/database';
+import type { DriverInterface } from '@orkestrel/database';
+import type { DriverMetadata } from '@orkestrel/database';
+import type { FieldPath } from '@orkestrel/contract';
+import type { Key } from '@orkestrel/database';
+import type { MigrationInput } from '@orkestrel/database';
+import type { MigrationStep } from '@orkestrel/database';
+import type { OperationOptions } from '@orkestrel/database';
+import type { Order } from '@orkestrel/database';
+import type { QueryInput } from '@orkestrel/database';
+import type { Row } from '@orkestrel/database';
+import type { SQLiteRow } from '@orkestrel/sqlite';
+import type { SQLiteValue } from '@orkestrel/sqlite';
+import type { StorageInterface } from '@orkestrel/database';
+import type { TableSchema } from '@orkestrel/database';
 
 /**
  * Compiles an {@link AggregateOperation} over a {@link FieldPath}.
@@ -45,20 +40,20 @@ export declare function compileColumnSQL(storage: ColumnStorage): string;
  *
  * @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
@@ -84,15 +79,15 @@ export declare function compileColumnSQL(storage: ColumnStorage): string;
  * 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.
  *
@@ -111,7 +106,8 @@ export declare function compileColumnSQL(storage: ColumnStorage): string;
 export declare function compileConditionSQL(condition: Condition, schema: TableSchema): CompiledSQL;
 
 /**
- * Represents a parameterized SQL fragment or statement plus its bind values.
+ * Represents a parameterized SQL fragment or statement plus its bind values. The
+ * `@orkestrel/database/server` entry point exports this type.
  *
  * @remarks
  * Produced by the pure SQL compilers (`compilers.ts`) that turn a core
@@ -128,15 +124,19 @@ export declare interface CompiledSQL {
 /**
  * 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
  */
 export declare function compileFieldSQL(path: FieldPath): string;
 
 /**
- * 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).
  *
@@ -211,7 +211,7 @@ export declare function compilePageSQL(limit: number | undefined, offset: number
  * `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)
@@ -236,7 +236,7 @@ export declare function compileQuerySQL(input: QueryInput | undefined, schema: T
  * @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.
  *
@@ -253,7 +253,7 @@ export declare function compileQuerySQL(input: QueryInput | undefined, schema: T
 export declare function compileWhereSQL(conditions: readonly Condition[], schema: TableSchema): CompiledSQL;
 
 /**
- * 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
@@ -285,7 +285,8 @@ export declare function compileWhereSQL(conditions: readonly Condition[], schema
 export declare function createJSONDriver(path: string): DriverInterface;
 
 /**
- * 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
@@ -371,7 +372,7 @@ export declare function decodeValue(value: SQLiteValue, column: ColumnSchema): u
  * 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
@@ -431,28 +432,28 @@ export declare function encodeRow(row: Row, schema: TableSchema): SQLiteRow;
 export declare function encodeValue(value: unknown, column: ColumnSchema): SQLiteValue;
 
 /**
- * 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.
  */
 export declare const EXACT_COLUMN_STORAGE: readonly ColumnStorage[];
 
 /**
- * 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
@@ -484,7 +485,7 @@ export declare function extractValues(row: SQLiteRow, names: readonly string[],
 
 /**
  * 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
@@ -541,17 +542,17 @@ export declare function inferValueStorage(value: unknown): ColumnStorage;
  * remains an `ABORTED` `DatabaseError` in `context.cause`. The fail-closed read path
  * ({@link JSONDriver.#document}) remains separate from this write-error contract.
  */
-export declare class JSONDriver implements DriverInterface_2 {
+export declare class JSONDriver implements DriverInterface {
     #private;
     constructor(path: string);
-    open(schema: readonly TableSchema_2[]): Promise<void>;
+    open(schema: readonly TableSchema[]): Promise<void>;
     close(): Promise<void>;
-    read(table: string, key: Key): Promise<Row_2 | undefined>;
-    write(table: string, key: Key, row: Row_2, options?: OperationOptions): Promise<void>;
-    insert(table: string, key: Key, row: Row_2, options?: OperationOptions): Promise<void>;
+    read(table: string, key: Key): Promise<Row | undefined>;
+    write(table: string, key: Key, row: Row, options?: OperationOptions): Promise<void>;
+    insert(table: string, key: Key, row: Row, options?: OperationOptions): Promise<void>;
     delete(table: string, key: Key, options?: OperationOptions): Promise<boolean>;
     keys(table: string): Promise<readonly Key[]>;
-    scan(table: string): AsyncIterable<Row_2>;
+    scan(table: string): AsyncIterable<Row>;
     /**
      * Iterates rows lazily with native filtering — delegates to the inner {@link MemoryDriver}.
      *
@@ -563,7 +564,7 @@ export declare class JSONDriver implements DriverInterface_2 {
      * @param table - The table to stream
      * @param input - The filter / offset / limit to apply lazily
      */
-    stream(table: string, input: QueryInput_2): AsyncIterable<Row_2>;
+    stream(table: string, input: QueryInput): AsyncIterable<Row>;
     clear(table: string): Promise<void>;
     /**
      * Runs an isolated native transaction callback over a candidate memory store.
@@ -660,7 +661,7 @@ export declare function matchesAbsentPath(error: unknown): boolean;
 export declare function matchesAggregateExactly(operation: AggregateOperation, column: FieldPath, schema: TableSchema): boolean;
 
 /**
- * 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.
  *
@@ -674,18 +675,18 @@ export declare function matchesAggregateExactly(operation: AggregateOperation, c
  * 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.
  *
@@ -700,7 +701,7 @@ export declare function matchesConditionExactly(condition: Condition, schema: Ta
  * — 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
@@ -717,16 +718,19 @@ export declare function matchesDeclaredStorage(value: unknown, storage: ColumnSt
 
 /**
  * Reports whether one {@link Order} term's column compiles to an `ORDER BY`
- * that matches the engine's {@link import('@src/core').sortRows} exactly.
+ * that matches the engine's {@link import('@orkestrel/database').sortRows} exactly.
  *
  * @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
@@ -739,6 +743,10 @@ export declare function matchesOrderExactly(order: Order, schema: TableSchema):
  * 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
@@ -786,6 +794,10 @@ export declare function quoteIdentifier(identifier: string): string;
 /**
  * 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
  */
@@ -847,21 +859,21 @@ export declare function schemaToTable(schema: TableSchema): string;
  * from a migration-plan fault) passes through `#guard` unchanged, never
  * re-wrapped.
  */
-export declare class SQLiteDriver implements DriverInterface_2 {
+export declare class SQLiteDriver implements DriverInterface {
     #private;
     constructor(options?: SQLiteDriverOptions);
-    open(schema: readonly TableSchema_2[]): Promise<void>;
+    open(schema: readonly TableSchema[]): Promise<void>;
     close(): Promise<void>;
-    read(table: string, key: Key): Promise<Row_2 | undefined>;
-    write(table: string, key: Key, row: Row_2, options?: OperationOptions): Promise<void>;
-    insert(table: string, key: Key, row: Row_2, options?: OperationOptions): Promise<void>;
+    read(table: string, key: Key): Promise<Row | undefined>;
+    write(table: string, key: Key, row: Row, options?: OperationOptions): Promise<void>;
+    insert(table: string, key: Key, row: Row, options?: OperationOptions): Promise<void>;
     delete(table: string, key: Key, options?: OperationOptions): Promise<boolean>;
     keys(table: string): Promise<readonly Key[]>;
-    scan(table: string): AsyncIterable<Row_2>;
+    scan(table: string): AsyncIterable<Row>;
     clear(table: string): Promise<void>;
-    records(table: string, input: QueryInput_2): Promise<readonly Row_2[]>;
-    aggregate(table: string, operation: AggregateOperation_2, column: FieldPath, input: QueryInput_2): Promise<number | undefined>;
-    stream(table: string, input: QueryInput_2): AsyncIterable<Row_2>;
+    records(table: string, input: QueryInput): Promise<readonly Row[]>;
+    aggregate(table: string, operation: AggregateOperation, column: FieldPath, input: QueryInput): Promise<number | undefined>;
+    stream(table: string, input: QueryInput): AsyncIterable<Row>;
     /**
      * Begins a native transaction — real `BEGIN`, `COMMIT`, `ROLLBACK`.
      *
@@ -918,7 +930,8 @@ export declare class SQLiteDriver implements DriverInterface_2 {
 }
 
 /**
- * Options for {@link import('./factories.js').createSQLiteDriver}.
+ * Configures {@link import('./factories.js').createSQLiteDriver}. The
+ * `@orkestrel/database/server` entry point exports this type.
  *
  * @remarks
  * Threaded into the underlying `@orkestrel/sqlite` wrapper's connection.
@@ -945,6 +958,10 @@ export declare interface SQLiteDriverOptions {
 /**
  * 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
  */