@orkestrel/database 0.0.12 → 0.0.14

package/README.md

@@ -1,11 +1,15 @@
 # @orkestrel/database
 
-A typed database abstraction for the `@orkestrel` line — one public
-`Database` over internal table/query engines and pluggable storage drivers at
-the seams. Consumers use `TableInterface` and `QueryInterface`. Built to sit beside
-`@orkestrel/contract` (validation) and `@orkestrel/emitter` (observable
-lifecycle), reusing both directly. `TableInterface.cursor()` exposes the
-`CursorInterface` contract for serial bulk mutation.
+> One typed database API for keyed rows, fluent queries, cursors, and
+> whole-store transactions, running unchanged over an in-memory map, a JSON
+> file, SQLite, or IndexedDB.
+
+Declare your tables with the `createDatabase` function, hold each
+`TableInterface` it hands back, and reach rows by key or through the fluent
+`query()` builder. `TableInterface.cursor()` opens the `CursorInterface`
+contract for serial bulk mutation. Built on `@orkestrel/contract` for
+validation and `@orkestrel/emitter` for the observation surface, reusing both
+directly. Part of the `@orkestrel` line.
 
 ## Install
 
@@ -23,10 +27,10 @@ npm install @orkestrel/database
 
 ## Status
 
-Pre-release (`0.0.7`): the core engine and the memory, JSON file, SQLite,
+Pre-release: the core engine and the memory, JSON file, SQLite,
 and IndexedDB drivers are all implemented and tested, but the public API is
 still unstable and may change without notice. See
-[guides/src/database.md](./guides/src/database.md) for the full documented
+[guides/database.md](./guides/database.md) for the full documented
 surface.
 
 ## Package

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

@@ -1,37 +1,34 @@
-import { ColumnStorage } from '@orkestrel/database';
-import { Condition } from '@orkestrel/database';
+import type { ColumnStorage } from '@orkestrel/database';
+import type { Condition } from '@orkestrel/database';
 import { DatabaseError } from '@orkestrel/database';
-import { DriverInterface } from '@orkestrel/database';
-import { DriverInterface as DriverInterface_2 } from '@orkestrel/database';
-import { DriverMetadata } from '@orkestrel/database';
-import { IndexedDBError } from '@orkestrel/indexeddb';
-import { Key } from '@orkestrel/database';
-import { MigrationInput } from '@orkestrel/database';
-import { OperationOptions } from '@orkestrel/database';
-import { QueryInput } from '@orkestrel/database';
-import { QueryInput as QueryInput_2 } from '@orkestrel/database';
-import { Row } from '@orkestrel/database';
-import { StoreDefinition } from '@orkestrel/indexeddb';
-import { TableSchema } from '@orkestrel/database';
-import { TableSchema as TableSchema_2 } from '@orkestrel/database';
+import type { DriverInterface } from '@orkestrel/database';
+import type { DriverMetadata } from '@orkestrel/database';
+import type { IndexedDBError } from '@orkestrel/indexeddb';
+import type { Key } from '@orkestrel/database';
+import type { MigrationInput } from '@orkestrel/database';
+import type { OperationOptions } from '@orkestrel/database';
+import type { QueryInput } from '@orkestrel/database';
+import type { Row } from '@orkestrel/database';
+import type { StoreDefinition } from '@orkestrel/indexeddb';
+import type { TableSchema } from '@orkestrel/database';
 
 /**
- * The `IDBKeyRange` a single {@link Condition} maps to, when its operator is one
- * of the six exact key comparisons over scalar operands; otherwise
- * `undefined`.
+ * Translates one {@link Condition} to the `IDBKeyRange` it maps to, when its
+ * operator is one of the exact key comparisons over scalar operands; otherwise
+ * returns `undefined`.
  *
  * @remarks
  * Only the comparison operators (`equals`/`above`/`below`/`from`/`to`/`between`)
  * translate to a key range that a typed (string/number) column can back with an
  * IndexedDB store/index read — see {@link selectPlan} for the caveats that
- * decide WHICH of `below`/`to` may drive a SECONDARY-index read versus the
+ * decide which of `below`/`to` may drive a secondary-index read versus the
  * primary store only (a column-type / absent-row concern, not a range-shape
  * one). `starts` is excluded — its prefix range can miss strings past U+FFFF;
  * the membership / negation / pattern / existence operators (`not`/`like`/`glob`/
  * `ends`/`any`/`none`/`absent`/`present`) have no single exact range. The operand
- * guard (`typeof` string/number) rejects a non-scalar value (e.g. an array, a
+ * guard (`typeof` string/number) rejects a non-scalar value (for example an array, a
  * boolean) that is not a usable key. `between` additionally guards against a
- * REVERSED pair (`first > second`): native `IDBKeyRange.bound` throws a raw
+ * reversed pair (`first > second`): native `IDBKeyRange.bound` throws a raw
  * `DataError` `DOMException` for a lower bound above the upper bound, so a
  * reversed pair returns `undefined` here (falls back to a full scan, which the
  * engine then correctly resolves to an empty result) rather than letting a
@@ -47,7 +44,7 @@ import { TableSchema as TableSchema_2 } from '@orkestrel/database';
 export declare function conditionToRange(condition: Condition): IDBKeyRange | undefined;
 
 /**
- * Create a persistent IndexedDB {@link DriverInterface} for the core database layer.
+ * Creates a persistent IndexedDB {@link DriverInterface} for a browser database name.
  *
  * @remarks
  * Pass it to `createDatabase` from `@orkestrel/database` to run the typed database
@@ -74,23 +71,23 @@ export declare function conditionToRange(condition: Condition): IDBKeyRange | un
  * await db.table('users').set({ id: 'u1', name: 'Ada' }) // persisted to IndexedDB
  * ```
  */
-export declare function createIndexedDBDriver(name: string): DriverInterface_2;
+export declare function createIndexedDBDriver(name: string): DriverInterface;
 
 /**
- * Derive an IndexedDB index name for a declared column group — a bare column
+ * Derives an IndexedDB index name for a declared column group — a bare column
  * name for a single-column index, a deterministic collision-free encoding for a
  * compound one.
  *
  * @remarks
  * Naming a compound index by joining its columns with `_` (`['a', 'b'] →
- * 'a_b'`) collides with a single-column index over a column LITERALLY named
+ * 'a_b'`) collides with a single-column index over a column literally named
  * `'a_b'` — the same name, two different key paths (`'a_b'` vs `['a', 'b']`),
  * which either throws a native `ConstraintError` from a duplicate
  * `createIndex` call at open, or (worse) lets {@link selectPlan}'s name-based
- * lookup match the wrong index. A single-column index keeps the BARE column
+ * lookup match the wrong index. A single-column index keeps the bare column
  * name — {@link selectPlan} matches `available.includes(condition.column)` by
  * that exact name, so a single-column index must stay named after its column
- * verbatim. A compound index instead encodes each column as a LENGTH-PREFIXED
+ * verbatim. A compound index instead encodes each column as a length-prefixed
  * segment (`'2#1:a1:b'`), so the boundary between columns is self-describing
  * and cannot be reconstructed by any other column list — including one
  * containing a column that happens to look like an encoded segment.
@@ -106,11 +103,23 @@ export declare function createIndexedDBDriver(name: string): DriverInterface_2;
  */
 export declare function deriveIndexedDBIndexName(columns: readonly string[]): string;
 
-export declare const INDEXABLE_STORAGE: ReadonlySet<ColumnStorage>;
+/**
+ * Lists the declared {@link ColumnStorage}s that are valid, orderable IndexedDB keys.
+ *
+ * @remarks
+ * `text` / `integer` / `real` occupy IndexedDB's string / number key space, so a
+ * column declared with one of them can back a store or index range read.
+ * `boolean` / `json` / `blob` are not valid `IDBValidKey`s and a range over one
+ * would silently miss rows, so `selectPlan` never pushes a condition down on
+ * them and the core engine answers the read instead. A frozen array, matching
+ * `EXACT_COLUMN_STORAGE` in `src/server`: a consumer holding it reads the
+ * membership with `includes` and cannot change the driver's pushdown behavior.
+ */
+export declare const INDEXABLE_STORAGE: readonly ColumnStorage[];
 
 /**
- * The IndexedDB {@link DriverInterface} — the persistent browser backend, built on
- * the published `@orkestrel/indexeddb` wrapper.
+ * Implements the {@link DriverInterface} over IndexedDB — the persistent browser backend,
+ * built on the published `@orkestrel/indexeddb` wrapper.
  *
  * @remarks
  * A thin adapter: it implements the storage primitives the core database layer
@@ -126,12 +135,12 @@ export declare const INDEXABLE_STORAGE: ReadonlySet<ColumnStorage>;
  * wrapper's native `getAll` / `getAllKeys`, and `snapshot` rolls back through one
  * atomic wrapper transaction.
  *
- * It also implements the optional native `records` / `stream` hooks
- * (AGENTS §21): `selectPlan` ({@link selectPlan}) turns the {@link QueryInput} into a
+ * It also implements the optional native `records` / `stream` hooks:
+ * `selectPlan` ({@link selectPlan}) turns the {@link QueryInput} into a
  * key-range pushdown over the primary key or a single-column secondary index,
  * fetching a candidate **superset** that the core engine (`applyQuery` /
  * `matchesQuery`) then refines — so a native read is byte-identical to a full
- * scan, just cheaper. Pushdown is conservative: only the exact-comparison
+ * scan, only cheaper. Pushdown is conservative: only the exact-comparison
  * operators over orderable columns narrow to a range; everything else falls back
  * to a full scan + the engine.
  *
@@ -143,27 +152,28 @@ export declare const INDEXABLE_STORAGE: ReadonlySet<ColumnStorage>;
  * {@link Migration} plan natively: IndexedDB schema DDL (creating/dropping a
  * store, creating/dropping an index) is legal only inside a versionchange
  * transaction (`onupgradeneeded`), so `migrate` closes the current connection
- * and opens a FRESH one at `version + 1` with an `upgrade` hook that walks the
+ * and opens a fresh one at `version + 1` with an `upgrade` hook that walks the
  * plan's steps — dropping stores, adding/removing indexes on the raw
- * `IDBTransaction`, and rewriting rows for `column.remove` via a cursor walk
+ * `IDBTransaction`, and rewriting rows for `column.remove` through a cursor walk
  * (the one step needing to touch existing data; `column.add` is a no-op — this
  * driver stores whatever a row carries, so there is nothing to backfill). A
- * step referencing an unknown table is validated BEFORE the reconnect, so a
+ * step referencing an unknown table is validated before the reconnect, so a
  * `MIGRATION` `DatabaseError` never wastes a version bump.
  *
  * @remarks
- * This unit deliberately OMITS `aggregate` / `transaction`. There is no native
+ * This unit deliberately omits `aggregate` / `transaction`. There is no native
  * `aggregate` (IndexedDB has no native SUM/AVG); the engine over the narrowed
- * `records` covers it. `transaction` is impossible here: the wrapper auto-commits
- * an `IDBTransaction` when control yields outside its request chain, so arbitrary
- * callback awaits cannot remain inside one native transaction. Every atomic
- * multi-operation sequence in this driver
- * (`snapshot`'s rollback) instead runs entirely inside ONE `db.write(...)` scope.
+ * `records` covers it. `transaction` is impossible here: the wrapper
+ * auto-commits an `IDBTransaction` when control yields outside its request
+ * chain, so arbitrary callback awaits cannot remain inside one native
+ * transaction. Every atomic multi-operation sequence in this driver
+ * (`snapshot`'s rollback) instead runs entirely inside one `db.write(...)`
+ * scope.
  */
 export declare class IndexedDBDriver implements DriverInterface {
     #private;
     constructor(name: string);
-    open(schema: readonly TableSchema_2[]): Promise<void>;
+    open(schema: readonly TableSchema[]): Promise<void>;
     close(): Promise<void>;
     read(table: string, key: Key): Promise<Row | undefined>;
     write(table: string, key: Key, row: Row, options?: OperationOptions): Promise<void>;
@@ -172,11 +182,11 @@ export declare class IndexedDBDriver implements DriverInterface {
     keys(table: string): Promise<readonly Key[]>;
     scan(table: string): AsyncIterable<Row>;
     clear(table: string): Promise<void>;
-    records(table: string, input: QueryInput_2): Promise<readonly Row[]>;
-    stream(table: string, input: QueryInput_2): AsyncIterable<Row>;
+    records(table: string, input: QueryInput): Promise<readonly Row[]>;
+    stream(table: string, input: QueryInput): AsyncIterable<Row>;
     snapshot(tables?: readonly string[]): Promise<() => Promise<void>>;
     /**
-     * Return the persisted {@link DriverMetadata}, or `undefined` when the store has
+     * Returns the persisted {@link DriverMetadata}, or `undefined` when the store has
      * never been stamped.
      *
      * @remarks
@@ -189,22 +199,22 @@ export declare class IndexedDBDriver implements DriverInterface {
      */
     metadata(): Promise<DriverMetadata | undefined>;
     /**
-     * Persist an owned metadata snapshot for a later `metadata()` to return.
+     * Persists an owned metadata snapshot for a later `metadata()` to return.
      *
      * @param metadata - The {@link DriverMetadata} to persist
      */
     stamp(metadata: DriverMetadata): Promise<void>;
     /**
-     * Apply a {@link Migration} plan by reconnecting at a bumped version and
+     * Applies a {@link Migration} plan by reconnecting at a bumped version and
      * running the plan's steps inside the wrapper's `upgrade` hook.
      *
      * @remarks
      * IndexedDB schema DDL is legal only inside `onupgradeneeded`, so this closes
-     * the current connection and opens a FRESH one at `version + 1`, declaring
-     * every currently-known store (plus {@link METADATA_STORE}) so nothing is lost,
-     * and applying `table.remove` / `index.add` / `index.remove` /
+     * the current connection and opens a fresh one at `version + 1`, declaring
+     * every store known at that point (plus {@link METADATA_STORE}) so nothing is
+     * lost, and applying `table.remove` / `index.add` / `index.remove` /
      * `column.remove` inside `upgrade`. Every step's `table` is validated against
-     * the driver's own `#schema` BEFORE the reconnect — an unknown-table step
+     * the driver's own `#schema` before the reconnect — an unknown-table step
      * throws `DatabaseError` `MIGRATION` without ever bumping the version.
      * `table.add` / `column.add` need no upgrade-time action: `table.add` is
      * created by the wrapper's built-in create-missing-stores pass (its
@@ -220,7 +230,7 @@ export declare class IndexedDBDriver implements DriverInterface {
 }
 
 /**
- * Map a backend {@link IndexedDBError} to the portable `DatabaseError` taxonomy
+ * Maps a backend {@link IndexedDBError} to the portable `DatabaseError` taxonomy
  * — the default mapping used everywhere except inside `migrate()`.
  *
  * @remarks
@@ -246,8 +256,8 @@ export declare class IndexedDBDriver implements DriverInterface {
 export declare function mapIndexedDBError(error: IndexedDBError): DatabaseError;
 
 /**
- * Map a backend {@link IndexedDBError} to the portable `DatabaseError` taxonomy
- * for use INSIDE `migrate()` — the one context where `UPGRADE` means the
+ * Maps a backend {@link IndexedDBError} to the portable `DatabaseError` taxonomy
+ * for use inside `migrate()` — the one context where `UPGRADE` means the
  * migration itself failed, not a generic driver fault.
  *
  * @remarks
@@ -263,14 +273,24 @@ export declare function mapIndexedDBError(error: IndexedDBError): DatabaseError;
  */
 export declare function mapMigrationError(error: IndexedDBError): DatabaseError;
 
+/**
+ * Names the reserved out-of-line store `__metadata__` the {@link IndexedDBDriver}
+ * stamps its {@link DriverMetadata} into.
+ *
+ * @remarks
+ * Backs the driver's `metadata` / `stamp` hooks. A user table named `__metadata__`
+ * collides with the driver's own bookkeeping, so a caller must avoid it; the
+ * collision is caught at `open`.
+ */
 export declare const METADATA_STORE = "__metadata__";
 
 /**
- * A pushdown plan — an optional index and optional `IDBKeyRange` used to narrow
+ * Represents a pushdown plan — an optional index and optional `IDBKeyRange` used to narrow
  * a read. An omitted `index` selects the primary store; an omitted `range`
  * performs a full scan. The plan is always a superset of the matching rows;
  * the core engine refines it to the exact result. An empty plan (`{}`) is a
- * primary-store full scan.
+ * primary-store full scan. The `@orkestrel/database/browser` entry point exports
+ * this type.
  */
 export declare interface QueryPlan {
     readonly index?: string;
@@ -278,7 +298,12 @@ export declare interface QueryPlan {
 }
 
 /**
- * Project a table schema into the IndexedDB wrapper's store definition.
+ * Projects a table schema into the IndexedDB wrapper's store definition.
+ *
+ * @remarks
+ * The definition is what an ordered versionchange migration creates the store
+ * from, carrying each declared index under the name {@link deriveIndexedDBIndexName}
+ * derives for its column group.
  *
  * @param schema - Portable table schema
  * @returns Store definition with declared indexes
@@ -286,11 +311,11 @@ export declare interface QueryPlan {
 export declare function schemaToStore(schema: TableSchema): StoreDefinition;
 
 /**
- * Plan an IndexedDB read for a {@link QueryInput} — pick the index (or the primary
+ * Plans an IndexedDB read for a {@link QueryInput} — picks the index (or the primary
  * store) and {@link IDBKeyRange} to narrow by, falling back to a full scan.
  *
  * @remarks
- * Pushdown is sound ONLY when every condition is `and`-joined: the engine folds
+ * Pushdown is sound only when every condition is `and`-joined: the engine folds
  * conditions left-to-right (`c1 && c2 && … && cn`), so the result is a subset of
  * each — narrowing on any one is then a valid superset. A single `or` breaks that
  * (a row can match through a later condition the range would exclude), so any `or`
@@ -304,21 +329,21 @@ export declare function schemaToStore(schema: TableSchema): StoreDefinition;
  * type (`boolean`/`json`/`blob`), uses a non-comparison operator, or has a
  * non-scalar operand cannot push and is skipped.
  *
- * **`below`/`to` may drive a SECONDARY-index range only when the column has NO
+ * **`below`/`to` may drive a secondary-index range only when the column has no
  * absent/null rows to lose — which this planner cannot verify from the schema
- * alone, so it restricts them to the PRIMARY store, where that is always true.**
- * The engine's total order (`compareValues`, see `@src/core`) ranks
- * `undefined` (absent) and `null` BELOW every number/string, so
- * `matchesCondition('below' | 'to', …)` is TRUE for a row whose field is absent
- * or `null` — but a secondary IndexedDB index has NO ENTRY for a row whose
+ * alone, so it restricts them to the primary store, where that is always true.**
+ * The engine's total order (`compareValues`, see `@orkestrel/database`) ranks
+ * `undefined` (absent) and `null` below every number/string, so
+ * `matchesCondition('below' | 'to', …)` is true for a row whose field is absent
+ * or `null` — but a secondary IndexedDB index has no entry for a row whose
  * indexed field is absent/`null`, so a `below`/`to` range read against that
- * index would SILENTLY DROP those rows (they can never be over-fetched, only
+ * index would silently drop those rows (they can never be over-fetched, only
  * missed — the one shape of lossiness this planner must never produce). The
- * table's PRIMARY key is exempt: a row's primary-key value is always present
+ * table's primary key is exempt: a row's primary-key value is always present
  * and never `null` (it is the row's identity, enforced at write time), so a
  * `below`/`to` range against the primary store can never exclude an
  * absent/null-keyed row because no such row exists. `equals`/`above`/`from`/
- * `between` stay index-eligible on ANY orderable column, primary or secondary:
+ * `between` stay index-eligible on any orderable column, primary or secondary:
  * each is bounded below by a scalar (`equals`/`between`'s lower bound, `above`/
  * `from`'s lower bound), and every scalar strictly out-ranks `undefined`/`null`
  * in the total order, so an absent/null-valued row can never satisfy them — the
@@ -332,7 +357,7 @@ export declare function schemaToStore(schema: TableSchema): StoreDefinition;
  * metadata.
  *
  * When no condition qualifies the plan is a full scan (`{}`) and the engine
- * does everything. The plan is always a SUPERSET of the
+ * does everything. The plan is always a superset of the
  * matching rows — the only correctness contract — so the driver may safely run
  * the exact engine over it.
  *