@orkestrel/database 0.0.6 → 0.0.8

package/README.md

@@ -1,10 +1,11 @@
 # @orkestrel/database
 
-A typed database abstraction for the `@orkestrel` line — a single
-environment-agnostic core engine (`Database`, `Table`, `Query`, `Cursor`,
-`Clause`) over pluggable storage drivers at the seams. Built to sit beside
+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 as it takes shape.
+lifecycle), reusing both directly. `TableInterface.cursor()` exposes the
+`CursorInterface` contract for serial bulk mutation.
 
 ## Install
 
@@ -14,14 +15,15 @@ npm install @orkestrel/database
 
 ## Requirements
 
-- Node.js >= 24 (`node:sqlite`, used by the `./server` SQLite driver, emits an
-  `ExperimentalWarning` on Node's current stable line)
+- Node.js >= 22.12.0, matching the package engine declaration
+- The `./server` SQLite driver additionally requires a Node.js release that
+  provides `node:sqlite`
 - Core is ESM; the `./server` subpath ships dual ESM+CJS builds; `./browser`
   is ESM-only
 
 ## Status
 
-Pre-release (`0.0.2`): the core engine, and the memory, JSON file, SQLite,
+Pre-release (`0.0.7`): 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
@@ -35,34 +37,10 @@ the in-memory driver), `./server` (adds the JSON file and SQLite drivers),
 and `./browser` (adds the IndexedDB driver). Core and `./server` ship dual
 ESM+CJS builds; `./browser` is ESM-only.
 
-### Release order
-
-Everything currently on the npm registry is at `0.0.1` — the wrapper repos'
-`0.0.2`s were never published, so `0.0.2` is the next version for all three
-packages and absorbs every change on this line.
-
-This package's SQLite and IndexedDB drivers are built against the wrapper
-surfaces documented by the mirrored guides in this repo — that is,
-`@orkestrel/sqlite@0.0.2` and `@orkestrel/indexeddb@0.0.2` — and the
-dependency ranges pin exactly those versions (`^0.0.2`; on a `0.0.x` version
-a caret means exactly that patch: `>=0.0.2 <0.0.3`). Publish in this order:
-
-1. Publish `@orkestrel/sqlite@0.0.2` and `@orkestrel/indexeddb@0.0.2` — they
-   are independent of each other (either order; both depend only on the
-   already-published `@orkestrel/contract`).
-2. In this repo, run `npm install` to re-resolve `package-lock.json` against
-   the newly published wrappers and commit the refreshed lockfile.
-3. Run the `prepublishOnly` gates and publish `@orkestrel/database@0.0.2`.
-
-Until step 1 happens, a fresh `npm ci` in this repo fails to resolve
-`^0.0.2` — deliberately. The exact pin makes it impossible to install or
-publish this package against the older `0.0.1` wrappers, which lack driver
-fixes this package's behavior relies on (the SQLite wrapper's mid-stream
-`iterate` fault mapping, the IndexedDB wrapper's abnormal-close recovery and
-`READONLY` fault code) and whose surfaces the mirrored guides here no longer
-describe. The same discipline applies to every future wrapper release: bump
-the pinned range, re-mirror the wrapper guides, and republish this package
-deliberately — wrapper changes never flow in silently.
+The server and browser drivers use the declared `@orkestrel/sqlite` and
+`@orkestrel/indexeddb` package ranges. Wrapper upgrades are deliberate:
+update the declared range, refresh the lockfile, run the full package gates,
+and publish Database only after its wrapper dependencies are available.
 
 ## License
 

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

@@ -1,21 +1,24 @@
-import { ColumnType } from '../core/index.ts';
+import { ColumnStorage } from '../core/index.ts';
 import { Condition } from '../core/index.ts';
-import { Criteria } from '../core/index.ts';
-import { Criteria as Criteria_2 } from '../../core/index.ts';
 import { DatabaseError } from '../core/index.ts';
 import { DriverInterface } from '../../core/index.ts';
 import { DriverInterface as DriverInterface_2 } from '../core/index.ts';
-import { DriverMeta } from '../../core/index.ts';
+import { DriverMetadata } from '../../core/index.ts';
 import { IndexedDBError } from '@orkestrel/indexeddb';
 import { Key } from '../../core/index.ts';
-import { Migration } from '../../core/index.ts';
+import { MigrationInput } from '../../core/index.ts';
+import { OperationOptions } from '../../core/index.ts';
+import { QueryInput } from '../core/index.ts';
+import { QueryInput as QueryInput_2 } from '../../core/index.ts';
 import { Row } from '../../core/index.ts';
+import { StoreDefinition } from '@orkestrel/indexeddb';
 import { TableSchema } from '../core/index.ts';
 import { TableSchema as TableSchema_2 } from '../../core/index.ts';
 
 /**
  * The `IDBKeyRange` a single {@link Condition} maps to, when its operator is one
- * of the six exact key comparisons over scalar operands — else `null`.
+ * of the six exact key comparisons over scalar operands; otherwise
+ * `undefined`.
  *
  * @remarks
  * Only the comparison operators (`equals`/`above`/`below`/`from`/`to`/`between`)
@@ -30,7 +33,7 @@ import { TableSchema as TableSchema_2 } from '../../core/index.ts';
  * boolean) that is not a usable key. `between` additionally guards against a
  * 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 `null` here (falls back to a full scan, which the
+ * 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
  * native exception escape untyped — the same defensive posture as every other
  * backend, which returns empty for a reversed/empty range instead of throwing.
@@ -39,17 +42,17 @@ import { TableSchema as TableSchema_2 } from '../../core/index.ts';
  * to a (possibly lossy) range.
  *
  * @param condition - The condition to translate
- * @returns Its exact key range, or `null` when the operator/operands cannot push
+ * @returns Its exact key range, or `undefined` when the operator/operands cannot push
  */
-export declare function conditionRange(condition: Condition): IDBKeyRange | null;
+export declare function conditionToRange(condition: Condition): IDBKeyRange | undefined;
 
 /**
  * Create a persistent IndexedDB {@link DriverInterface} for the core database layer.
  *
  * @remarks
- * Pass it to `createDatabase` from `@orkestrel/database` to run the whole typed database +
- * relations stack against IndexedDB instead of memory — the `Database` / `Table` /
- * `Query` / relations API is unchanged; only where the bytes live changes. The
+ * Pass it to `createDatabase` from `@orkestrel/database` to run the typed database
+ * layer against IndexedDB instead of memory — the `Database` / `Table` / `Query`
+ * API is unchanged; only where the bytes live changes. The
  * driver is built on the published `@orkestrel/indexeddb` wrapper in auto-managed
  * mode, so a table added to the `tables` map is created on the next open with no
  * version bump. This unit omits `transaction` / `aggregate` (see
@@ -97,13 +100,13 @@ export declare function createIndexedDBDriver(name: string): DriverInterface_2;
  *
  * @example
  * ```ts
- * deriveIndexName(['age']) // 'age'
- * deriveIndexName(['a', 'b']) // '2#1:a1:b'
+ * deriveIndexedDBIndexName(['age']) // 'age'
+ * deriveIndexedDBIndexName(['a', 'b']) // '2#1:a1:b'
  * ```
  */
-export declare function deriveIndexName(columns: readonly string[]): string;
+export declare function deriveIndexedDBIndexName(columns: readonly string[]): string;
 
-export declare const INDEXABLE_TYPES: ReadonlySet<ColumnType>;
+export declare const INDEXABLE_STORAGE: ReadonlySet<ColumnStorage>;
 
 /**
  * The IndexedDB {@link DriverInterface} — the persistent browser backend, built on
@@ -115,25 +118,27 @@ export declare const INDEXABLE_TYPES: ReadonlySet<ColumnType>;
  * / `snapshot`) by delegating to the wrapper's typed store operations — it never
  * touches raw IndexedDB. Rows are stored with **out-of-line keys** (the database
  * passes the key explicitly, `store.set(row, key)`), so each table is declared as a
- * key-path-less store. The wrapper opens in **auto-managed** mode (no fixed
- * version), creating any missing store on demand, so a table added to the schema is
- * created on the next open with no manual version bump. The driver's bulk reads
- * (`scan` / `keys`) use the wrapper's native `getAll` / `getAllKeys`, and `snapshot`
- * rolls back through one atomic wrapper transaction.
+ * key-path-less store. A fresh database opens in **auto-managed** mode (no fixed
+ * version), creating missing declared stores on demand. Once metadata is persisted,
+ * bootstrap captures the live stores and version, rejects a missing persisted store,
+ * and pins the final open to that version so a competing versionchange cannot
+ * silently recreate lost storage. The driver's bulk reads (`scan` / `keys`) use the
+ * wrapper's native `getAll` / `getAllKeys`, and `snapshot` rolls back through one
+ * atomic wrapper transaction.
  *
- * It also implements the optional native `records` / `count` / `stream` hooks
- * (AGENTS §21): `selectPlan` ({@link selectPlan}) turns the {@link Criteria} into a
+ * It also implements the optional native `records` / `stream` hooks
+ * (AGENTS §21): `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 (`applyCriteria` /
- * `matchesCriteria`) then refines — so a native read is byte-identical to a full
+ * 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
  * operators over orderable columns narrow to a range; everything else falls back
  * to a full scan + the engine.
  *
  * @remarks
- * This driver also implements `migrate` / `meta` / `stamp`. `meta` / `stamp`
- * persist the {@link DriverMeta} in a reserved out-of-line store,
- * {@link META_STORE} (`__meta__`) — excluded from a whole-store `snapshot`
+ * This driver also implements `migrate` / `metadata` / `stamp`. `metadata` / `stamp`
+ * persist the {@link DriverMetadata} in a reserved out-of-line store,
+ * {@link METADATA_STORE} (`__metadata__`) — excluded from a whole-store `snapshot`
  * capture, since it is driver bookkeeping, not caller data. `migrate` applies a
  * {@link Migration} plan natively: IndexedDB schema DDL (creating/dropping a
  * store, creating/dropping an index) is legal only inside a versionchange
@@ -150,9 +155,9 @@ export declare const INDEXABLE_TYPES: ReadonlySet<ColumnType>;
  * 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` the moment control yields to a non-IDB `await`, so a
- * BEGIN-now / commit-or-rollback-later handle spanning arbitrary caller code
- * cannot be built on top of it — every atomic multi-op sequence in this driver
+ * 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 {
@@ -161,34 +166,34 @@ export declare class IndexedDBDriver implements DriverInterface {
     open(schema: readonly TableSchema_2[]): Promise<void>;
     close(): Promise<void>;
     read(table: string, key: Key): Promise<Row | undefined>;
-    write(table: string, key: Key, row: Row): Promise<void>;
-    delete(table: string, key: Key): Promise<boolean>;
+    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>;
     clear(table: string): Promise<void>;
-    records(table: string, criteria: Criteria_2): Promise<readonly Row[]>;
-    count(table: string, criteria: Criteria_2): Promise<number>;
-    stream(table: string, criteria: Criteria_2): AsyncIterable<Row>;
+    records(table: string, input: QueryInput_2): Promise<readonly Row[]>;
+    stream(table: string, input: QueryInput_2): AsyncIterable<Row>;
     snapshot(tables?: readonly string[]): Promise<() => Promise<void>>;
     /**
-     * Return the persisted {@link DriverMeta}, or `undefined` when the store has
+     * Return the persisted {@link DriverMetadata}, or `undefined` when the store has
      * never been stamped.
      *
      * @remarks
-     * Reads `'meta'` from the reserved {@link META_STORE}, narrowing the
-     * structured-clone value with the core {@link isDriverMeta} guard (never
-     * asserted, AGENTS §14) — a missing or malformed record returns `undefined`,
-     * exactly like a fresh, never-stamped store.
+     * Reads `'metadata'` from the reserved {@link METADATA_STORE} in one readonly
+     * transaction that distinguishes key absence from a present `undefined`
+     * value. Only absence returns `undefined`; present malformed state fails
+     * closed with a payload-safe `DRIVER` error.
      *
-     * @returns The last-stamped {@link DriverMeta}, or `undefined`
+     * @returns The last-stamped {@link DriverMetadata}, or `undefined`
      */
-    meta(): Promise<DriverMeta | undefined>;
+    metadata(): Promise<DriverMetadata | undefined>;
     /**
-     * Persist `meta` verbatim for a later `meta()` to return.
+     * Persist an owned metadata snapshot for a later `metadata()` to return.
      *
-     * @param meta - The {@link DriverMeta} to persist
+     * @param metadata - The {@link DriverMetadata} to persist
      */
-    stamp(meta: DriverMeta): Promise<void>;
+    stamp(metadata: DriverMetadata): Promise<void>;
     /**
      * Apply a {@link Migration} plan by reconnecting at a bumped version and
      * running the plan's steps inside the wrapper's `upgrade` hook.
@@ -196,7 +201,7 @@ export declare class IndexedDBDriver implements DriverInterface {
      * @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 META_STORE}) so nothing is lost,
+     * every currently-known store (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
@@ -209,13 +214,11 @@ export declare class IndexedDBDriver implements DriverInterface {
      * `open` tracks, so subsequent pushdown planning and a later `migrate` /
      * `open` see the new shape.
      *
-     * @param plan - The migration plan to apply
+     * @param input - The migration plan and optional metadata stamp to apply atomically
      */
-    migrate(plan: Migration): Promise<void>;
+    migrate(input: MigrationInput): Promise<void>;
 }
 
-export declare function isKey(value: unknown): value is string | number;
-
 /**
  * Map a backend {@link IndexedDBError} to the portable `DatabaseError` taxonomy
  * — the default mapping used everywhere except inside `migrate()`.
@@ -225,17 +228,17 @@ export declare function isKey(value: unknown): value is string | number;
  * `CONSTRAINT` (a unique-key violation) is a `CONFLICT` — the same code every
  * other backend uses for a duplicate key. `CLOSED`/`NOT_OPEN`/`INVALID` (the
  * connection is gone, never opened, or the native handle is stale) collapse to
- * `CLOSED`. `QUOTA` and `BLOCKED` are genuine infrastructure faults (`DRIVER`),
- * carrying a machine-readable `context.code` (`'QUOTA'` / `'BLOCKED'`) so a
- * caller can branch without parsing the message; `BLOCKED` additionally marks
- * `context.retryable: true` — a concurrent connection holding the database open
- * is a transient condition, not a permanent one. Every other code (`UPGRADE`
- * here — see {@link mapMigrationError} for the `migrate()`-only remapping to
- * `MIGRATION` — `ABORTED`, `NOT_FOUND`, `DATA`, `OPEN`, `INACTIVE`, `READONLY`,
- * `UNKNOWN`) is an unexpected infrastructure fault and maps to `DRIVER` — the
- * driver opens its own readwrite transactions, so a `READONLY` fault can only
- * mean the backend behaved unexpectedly. The original error is always
- * preserved as `context.cause` for diagnostics.
+ * `CLOSED`. `QUOTA` is a genuine infrastructure fault (`DRIVER`) carrying a
+ * machine-readable `context.code` so a caller can branch without parsing the
+ * message. A blocked open or versionchange is nonterminal in the backend and
+ * remains pending until the competing connection closes, so it never reaches
+ * this error mapper. Every other code (`UPGRADE` here — see
+ * {@link mapMigrationError} for the `migrate()`-only remapping to `MIGRATION` —
+ * `ABORTED`, `NOT_FOUND`, `DATA`, `OPEN`, `INACTIVE`, `READONLY`, `UNKNOWN`) is
+ * an unexpected infrastructure fault and maps to `DRIVER` — the driver opens
+ * its own readwrite transactions, so a `READONLY` fault can only mean the
+ * backend behaved unexpectedly. The original error is always preserved as
+ * `context.cause` for diagnostics.
  *
  * @param error - The backend error to translate
  * @returns The portable `DatabaseError`
@@ -260,20 +263,30 @@ export declare function mapIndexedDBError(error: IndexedDBError): DatabaseError;
  */
 export declare function mapMigrationError(error: IndexedDBError): DatabaseError;
 
-export declare const META_STORE = "__meta__";
+export declare const METADATA_STORE = "__metadata__";
 
 /**
- * A pushdown plan — which index (or the primary store, `null`) to read and the
- * `IDBKeyRange` to narrow by (`null` = full scan). Always a SUPERSET of the
- * matching rows; the core engine refines it to the exact result.
+ * 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.
  */
 export declare interface QueryPlan {
-    readonly index: string | null;
-    readonly range: IDBKeyRange | null;
+    readonly index?: string;
+    readonly range?: IDBKeyRange;
 }
 
 /**
- * Plan an IndexedDB read for a {@link Criteria} — pick the index (or the primary
+ * Project a table schema into the IndexedDB wrapper's store definition.
+ *
+ * @param schema - Portable table schema
+ * @returns Store definition with declared indexes
+ */
+export declare function schemaToStore(schema: TableSchema): StoreDefinition;
+
+/**
+ * Plan an IndexedDB read for a {@link QueryInput} — pick the index (or the primary
  * store) and {@link IDBKeyRange} to narrow by, falling back to a full scan.
  *
  * @remarks
@@ -283,9 +296,9 @@ export declare interface QueryPlan {
  * (a row can match through a later condition the range would exclude), so any `or`
  * forces a full scan. Otherwise it scans the conditions in order and selects the
  * **first** one that is provably range-exact and backed by a key: a comparison
- * operator (`conditionRange`) over a single, orderable (`text`/`integer`/`real`)
- * column that is either the table's primary key (read the store directly, `index:
- * null`) or has a single-column secondary index (named exactly the column — read
+ * operator (`conditionToRange`) over a single, orderable (`text`/`integer`/`real`)
+ * column that is either the table's primary key (read the store directly with
+ * `index` omitted) or has a single-column secondary index (named exactly the column — read
  * that index). A condition whose column is a nested {@link FieldPath} array
  * (descends a json value, not a key), is absent from the schema, is a non-orderable
  * type (`boolean`/`json`/`blob`), uses a non-comparison operator, or has a
@@ -311,19 +324,19 @@ export declare interface QueryPlan {
  * in the total order, so an absent/null-valued row can never satisfy them — the
  * index's silence on such a row is harmless (it was never going to match).
  * **Declared-type trust caveat:** this reasoning holds under the contract that
- * an {@link INDEXABLE_TYPES} column, once contract-validated at write time,
+ * an {@link INDEXABLE_STORAGE} column, once contract-validated at write time,
  * holds only `string | number | null` (or is absent) — never some other
  * runtime value that could rank differently; a driver bypassing the write
  * contract (writing raw rows directly to the store) could defeat this
  * argument, but that is out of scope for a planner reading validated schema
  * metadata.
  *
- * When no condition qualifies the plan is a full scan (`{ index: null, range:
- * null }`) and the engine does everything. The plan is always a SUPERSET of the
+ * When no condition qualifies the plan is a full scan (`{}`) and the engine
+ * 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.
  *
- * @param criteria - The read specification (its `conditions` drive the plan), or
+ * @param input - The read specification (its `conditions` drive the plan), or
  *   `undefined` for an unconditional read
  * @param schema - The table's schema — its `primary` key and column types
  * @param available - The secondary-index names that physically exist on the store
@@ -332,11 +345,11 @@ export declare interface QueryPlan {
  *
  * @example
  * ```ts
- * selectPlan({ conditions: [eq('id', 'u1')] }, schema, []) // { index: null, range: only('u1') }
+ * selectPlan({ conditions: [eq('id', 'u1')] }, schema, []) // { range: only('u1') }
  * selectPlan({ conditions: [from('age', 18)] }, schema, ['age']) // { index: 'age', range: from(18) }
- * selectPlan({ conditions: [contains('name', 'a')] }, schema, []) // { index: null, range: null }
+ * selectPlan({ conditions: [contains('name', 'a')] }, schema, []) // {}
  * ```
  */
-export declare function selectPlan(criteria: Criteria | undefined, schema: TableSchema, available: readonly string[]): QueryPlan;
+export declare function selectPlan(input: QueryInput | undefined, schema: TableSchema, available: readonly string[]): QueryPlan;
 
 export { }