@orkestrel/database 0.0.12 → 0.0.14

package/dist/src/browser/index.js

@@ -1,31 +1,52 @@
-import { DatabaseError, applyQuery, bindRowKey, checkAbort, cloneDriverMetadata, cloneMigrationInput, compareValues, equalsValue, extractKey, isDatabaseError, isKey, matchesQuery, migrateRows, normalizeDriverSchema, planMigration, projectMigrationSchema, validatePage } from "../core/index.js";
-import { createIndexedDBDatabase, isIndexedDBError, rangeAboveKey, rangeBelowKey, rangeBetweenKeys, rangeExactKey, rangeFromKey, rangeToKey } from "@orkestrel/indexeddb";
+import { DatabaseError, applyQuery, bindRowKey, checkAbort, cloneDriverMetadata, cloneMigrationInput, compareValues, equalsValue, extractKey, findColumn, isDatabaseError, isKey, matchesQuery, migrateRows, normalizeDriverSchema, planMigration, projectMigrationSchema, validatePage } from "../core/index.js";
+import { createIndexedDBDatabase, isIndexedDBError, rangeAboveKey, rangeBelowKey, rangeFromKey, rangeToKey } from "@orkestrel/indexeddb";
 //#region src/browser/constants.ts
-var INDEXABLE_STORAGE = /* @__PURE__ */ new Set([
+/**
+* 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.
+*/
+var INDEXABLE_STORAGE = Object.freeze([
 	"text",
 	"integer",
 	"real"
 ]);
+/**
+* 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`.
+*/
 var METADATA_STORE = "__metadata__";
 //#endregion
 //#region src/browser/helpers.ts
 /**
-* 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
@@ -42,12 +63,12 @@ function conditionToRange(condition) {
 	const first = condition.values[0];
 	const second = condition.values[1];
 	switch (condition.operator) {
-		case "equals": return isKey(first) ? rangeExactKey(first) : void 0;
+		case "equals": return isKey(first) ? IDBKeyRange.only(first) : void 0;
 		case "above": return isKey(first) ? rangeAboveKey(first) : void 0;
 		case "below": return isKey(first) ? rangeBelowKey(first) : void 0;
 		case "from": return isKey(first) ? rangeFromKey(first) : void 0;
 		case "to": return isKey(first) ? rangeToKey(first) : void 0;
-		case "between": return isKey(first) && isKey(second) && compareValues(first, second) <= 0 ? rangeBetweenKeys(first, second) : void 0;
+		case "between": return isKey(first) && isKey(second) && compareValues(first, second) <= 0 ? IDBKeyRange.bound(first, second) : void 0;
 		case "not":
 		case "like":
 		case "glob":
@@ -60,11 +81,11 @@ function conditionToRange(condition) {
 	}
 }
 /**
-* 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`
@@ -78,21 +99,21 @@ function conditionToRange(condition) {
 * 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.**
+* 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
+* `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
@@ -106,7 +127,7 @@ function conditionToRange(condition) {
 * 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.
 *
@@ -129,8 +150,8 @@ function selectPlan(input, schema, available) {
 	if (conditions.slice(1).some((condition) => condition.connector === "or")) return {};
 	for (const condition of conditions) {
 		if (typeof condition.column !== "string") continue;
-		const column = schema.columns.find((candidate) => candidate.name === condition.column);
-		if (column === void 0 || !INDEXABLE_STORAGE.has(column.storage)) continue;
+		const column = findColumn(condition.column, schema);
+		if (column === void 0 || !INDEXABLE_STORAGE.includes(column.storage)) continue;
 		const range = conditionToRange(condition);
 		if (range === void 0) continue;
 		if (condition.column === schema.primary) return { range };
@@ -143,7 +164,7 @@ function selectPlan(input, schema, available) {
 	return {};
 }
 /**
-* 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
@@ -187,8 +208,8 @@ function mapIndexedDBError(error) {
 	}
 }
 /**
-* 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
@@ -207,20 +228,20 @@ function mapMigrationError(error) {
 	return mapIndexedDBError(error);
 }
 /**
-* 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.
@@ -240,7 +261,12 @@ function deriveIndexedDBIndexName(columns) {
 	return `${columns.length}#${columns.map((part) => `${part.length}:${part}`).join("")}`;
 }
 /**
-* 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
@@ -257,8 +283,8 @@ function schemaToStore(schema) {
 //#endregion
 //#region src/browser/drivers/IndexedDBDriver.ts
 /**
-* 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
@@ -274,12 +300,12 @@ function schemaToStore(schema) {
 * 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.
 *
@@ -291,22 +317,23 @@ function schemaToStore(schema) {
 * {@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.
 */
 var IndexedDBDriver = class {
 	#name;
@@ -434,30 +461,6 @@ var IndexedDBDriver = class {
 		validatePage(input);
 		return this.#stream(table, input);
 	}
-	async *#stream(table, input) {
-		try {
-			const schema = this.#table(table);
-			const store = this.#store(table);
-			const plan = selectPlan(input, schema, store.indexes);
-			const conditions = input.conditions ?? [];
-			const offset = input.offset ?? 0;
-			const limit = input.limit;
-			let skipped = 0;
-			let yielded = 0;
-			for (const row of await this.#candidates(store, schema, plan)) {
-				if (limit !== void 0 && yielded >= limit) break;
-				if (!matchesQuery(row, conditions)) continue;
-				if (skipped < offset) {
-					skipped += 1;
-					continue;
-				}
-				yielded += 1;
-				yield row;
-			}
-		} catch (error) {
-			throw this.#wrap(error);
-		}
-	}
 	async snapshot(tables) {
 		try {
 			const database = this.#require();
@@ -529,7 +532,7 @@ var IndexedDBDriver = class {
 		}
 	}
 	/**
-	* 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
@@ -548,7 +551,7 @@ var IndexedDBDriver = class {
 		}
 	}
 	/**
-	* 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
 	*/
@@ -565,16 +568,16 @@ var IndexedDBDriver = class {
 		}
 	}
 	/**
-	* 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
@@ -647,6 +650,30 @@ var IndexedDBDriver = class {
 			throw cause;
 		}
 	}
+	async *#stream(table, input) {
+		try {
+			const schema = this.#table(table);
+			const store = this.#store(table);
+			const plan = selectPlan(input, schema, store.indexes);
+			const conditions = input.conditions ?? [];
+			const offset = input.offset ?? 0;
+			const limit = input.limit;
+			let skipped = 0;
+			let yielded = 0;
+			for (const row of await this.#candidates(store, schema, plan)) {
+				if (limit !== void 0 && yielded >= limit) break;
+				if (!matchesQuery(row, conditions)) continue;
+				if (skipped < offset) {
+					skipped += 1;
+					continue;
+				}
+				yielded += 1;
+				yield row;
+			}
+		} catch (error) {
+			throw this.#wrap(error);
+		}
+	}
 	async #mutate(table, options, scope) {
 		const signal = options?.signal;
 		checkAbort(signal);
@@ -759,31 +786,33 @@ var IndexedDBDriver = class {
 		return schema;
 	}
 	async #upgrade(input, added, context) {
-		for (const name of added) if (name !== "__metadata__" && context.stores.includes(name)) context.drop(name);
+		for (const name of added) if (name !== "__metadata__" && context.stores.names.includes(name)) context.stores.drop(name);
 		for (const step of input.plan.steps) switch (step.operation) {
 			case "table.add":
-				context.create(step.table.name, schemaToStore(step.table));
+				context.stores.create(step.table.name, schemaToStore(step.table));
 				break;
 			case "table.remove":
-				context.drop(step.table);
+				context.stores.drop(step.table);
 				break;
 			case "index.add": {
 				const name = deriveIndexedDBIndexName(step.index);
 				const [column] = step.index;
 				const path = step.index.length === 1 && column !== void 0 ? column : [...step.index];
-				context.index(step.table, {
+				context.indexes.create(step.table, {
 					name,
 					path
 				});
 				break;
 			}
 			case "index.remove":
-				context.deindex(step.table, deriveIndexedDBIndexName(step.index));
+				context.indexes.drop(step.table, deriveIndexedDBIndexName(step.index));
 				break;
 			case "column.remove": {
-				let cursor = await context.store(step.table).cursor();
+				let cursor = await context.stores.store(step.table).cursor();
 				while (cursor !== null) {
-					const [migrated] = migrateRows([cursor.value], [step]);
+					const row = cursor.value;
+					if (row === void 0) throw new DatabaseError("MIGRATION", "migrate: stored value is not a record", { table: step.table });
+					const [migrated] = migrateRows([row], [step]);
 					if (migrated === void 0) throw new DatabaseError("MIGRATION", "migrate: transformed row is missing", { table: step.table });
 					await cursor.update(migrated);
 					cursor = await cursor.continue();
@@ -791,7 +820,7 @@ var IndexedDBDriver = class {
 				break;
 			}
 		}
-		if (input.metadata !== void 0) await context.store(METADATA_STORE).set({
+		if (input.metadata !== void 0) await context.stores.store(METADATA_STORE).set({
 			version: input.metadata.version,
 			schema: input.metadata.schema
 		}, "metadata");
@@ -800,7 +829,7 @@ var IndexedDBDriver = class {
 //#endregion
 //#region src/browser/factories.ts
 /**
-* 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