@orkestrel/database 0.0.1 → 0.0.3

package/README.md

@@ -14,22 +14,55 @@ npm install @orkestrel/database
 
 ## Requirements
 
-- Node.js >= 24
-- Core is ESM; the `./server` subpath ships a CommonJS build
+- Node.js >= 24 (`node:sqlite`, used by the `./server` SQLite driver, emits an
+  `ExperimentalWarning` on Node's current stable line)
+- Core is ESM; the `./server` subpath ships dual ESM+CJS builds; `./browser`
+  is ESM-only
 
 ## Status
 
-Pre-release (`0.0.1`): the core engine and the memory and JSON file drivers
-are 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 surface.
+Pre-release (`0.0.2`): 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
+surface.
 
 ## Package
 
-Published as two environment-scoped entry points per the `exports` field in
-`package.json`: a shared core (with the in-memory driver) and `./server` (the
-JSON file driver). IndexedDB and SQLite drivers are planned once their
-backing packages exist.
+Published as three environment-scoped entry points per the `exports` field
+in `package.json`: `.` (the shared, environment-agnostic core engine plus
+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.
 
 ## License
 

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

@@ -0,0 +1,342 @@
+import { ColumnType } from '../core/index.js';
+import { Condition } from '../core/index.js';
+import { Criteria } from '../core/index.js';
+import { Criteria as Criteria_2 } from '../core/index.js';
+import { DatabaseError } from '../core/index.js';
+import { DriverInterface } from '../core/index.js';
+import { DriverInterface as DriverInterface_2 } from '../core/index.js';
+import { DriverMeta } from '../core/index.js';
+import { IndexedDBError } from '@orkestrel/indexeddb';
+import { Key } from '../core/index.js';
+import { Migration } from '../core/index.js';
+import { Row } from '../core/index.js';
+import { TableSchema } from '../core/index.js';
+import { TableSchema as TableSchema_2 } from '../core/index.js';
+
+/**
+ * The `IDBKeyRange` a single {@link Condition} maps to, when its operator is one
+ * of the six exact key comparisons over scalar operands — else `null`.
+ *
+ * @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
+ * 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
+ * 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
+ * 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.
+ * The switch is exhaustive over every {@link ConditionOperator}, so a new
+ * operator forces a deliberate decision here rather than silently defaulting
+ * to a (possibly lossy) range.
+ *
+ * @param condition - The condition to translate
+ * @returns Its exact key range, or `null` when the operator/operands cannot push
+ */
+export declare function conditionRange(condition: Condition): IDBKeyRange | null;
+
+/**
+ * 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
+ * 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
+ * {@link IndexedDBDriver} `@remarks`).
+ *
+ * @param name - The IndexedDB database name to open or create
+ * @returns A {@link DriverInterface} backed by IndexedDB
+ *
+ * @example
+ * ```ts
+ * import { createDatabase } from '@orkestrel/database'
+ * import { stringShape } from '@orkestrel/contract'
+ * import { createIndexedDBDriver } from '@orkestrel/database/browser'
+ *
+ * const db = createDatabase({
+ * 	driver: createIndexedDBDriver('app'),
+ * 	tables: { users: { id: stringShape(), name: stringShape() } },
+ * })
+ * await db.table('users').set({ id: 'u1', name: 'Ada' }) // persisted to IndexedDB
+ * ```
+ */
+export declare function createIndexedDBDriver(name: string): DriverInterface_2;
+
+/**
+ * Derive 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'` — 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
+ * 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
+ * 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.
+ *
+ * @param columns - The index's column group, in declared order
+ * @returns The index name to pass to `createIndex` / read back from `indexNames`
+ *
+ * @example
+ * ```ts
+ * deriveIndexName(['age']) // 'age'
+ * deriveIndexName(['a', 'b']) // '2#1:a1:b'
+ * ```
+ */
+export declare function deriveIndexName(columns: readonly string[]): string;
+
+export declare const INDEXABLE_TYPES: ReadonlySet<ColumnType>;
+
+/**
+ * The IndexedDB {@link DriverInterface} — the persistent browser backend, built on
+ * the published `@orkestrel/indexeddb` wrapper.
+ *
+ * @remarks
+ * A thin adapter: it implements the storage primitives the core database layer
+ * needs (`open` / `close` / `read` / `write` / `delete` / `keys` / `scan` / `clear`
+ * / `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.
+ *
+ * It also implements the optional native `records` / `count` / `stream` hooks
+ * (AGENTS §21): `selectPlan` ({@link selectPlan}) turns the {@link Criteria} 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
+ * 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`
+ * 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
+ * transaction (`onupgradeneeded`), so `migrate` closes the current connection
+ * 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
+ * (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
+ * `MIGRATION` `DatabaseError` never wastes a version bump.
+ *
+ * @remarks
+ * 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
+ * (`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>;
+    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>;
+    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>;
+    snapshot(tables?: readonly string[]): Promise<() => Promise<void>>;
+    /**
+     * Return the persisted {@link DriverMeta}, 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.
+     *
+     * @returns The last-stamped {@link DriverMeta}, or `undefined`
+     */
+    meta(): Promise<DriverMeta | undefined>;
+    /**
+     * Persist `meta` verbatim for a later `meta()` to return.
+     *
+     * @param meta - The {@link DriverMeta} to persist
+     */
+    stamp(meta: DriverMeta): 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.
+     *
+     * @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,
+     * 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
+     * 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
+     * definition is already in the declared `stores`), and this driver stores
+     * whatever a row carries — there is nothing to backfill for a new column.
+     * `#schema` bookkeeping is updated to match the applied plan, mirroring what
+     * `open` tracks, so subsequent pushdown planning and a later `migrate` /
+     * `open` see the new shape.
+     *
+     * @param plan - The migration plan to apply
+     */
+    migrate(plan: Migration): 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()`.
+ *
+ * @remarks
+ * No backend fault may leak through `DriverInterface` as a raw `IndexedDBError`.
+ * `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.
+ *
+ * @param error - The backend error to translate
+ * @returns The portable `DatabaseError`
+ */
+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
+ * migration itself failed, not a generic driver fault.
+ *
+ * @remarks
+ * `migrate()` reconnects at a bumped version inside `onupgradeneeded`; a
+ * rejection there (an inapplicable step, a native `ConstraintError` from a
+ * duplicate index, …) surfaces as `IndexedDBError` `UPGRADE` and must become a
+ * `MIGRATION` `DatabaseError` so a caller can distinguish "this migration plan
+ * failed" from "the driver hit an unrelated infrastructure fault". Every other
+ * code defers to {@link mapIndexedDBError} unchanged.
+ *
+ * @param error - The backend error to translate
+ * @returns The portable `DatabaseError`
+ */
+export declare function mapMigrationError(error: IndexedDBError): DatabaseError;
+
+export declare const META_STORE = "__meta__";
+
+/**
+ * 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.
+ */
+export declare interface QueryPlan {
+    readonly index: string | null;
+    readonly range: IDBKeyRange | null;
+}
+
+/**
+ * Plan an IndexedDB read for a {@link Criteria} — pick 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
+ * 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`
+ * 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
+ * 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
+ * non-scalar operand cannot push and is skipped.
+ *
+ * **`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
+ * 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
+ * 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
+ * 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:
+ * 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
+ * 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,
+ * 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
+ * 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
+ *   `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
+ *   (`store.indexes`); a single-column index is named exactly its column
+ * @returns The index + range to read, narrowing to a superset (never lossy)
+ *
+ * @example
+ * ```ts
+ * selectPlan({ conditions: [eq('id', 'u1')] }, schema, []) // { index: null, 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 }
+ * ```
+ */
+export declare function selectPlan(criteria: Criteria | undefined, schema: TableSchema, available: readonly string[]): QueryPlan;
+
+export { }