@orkestrel/database 0.0.1 → 0.0.3

package/dist/src/browser/index.js

@@ -0,0 +1,686 @@
+import { DatabaseError, applyCriteria, compareValues, extractKey, isDriverMeta, matchesCriteria, migrateRows } from "../core/index.js";
+import { createIndexedDBDatabase, isIndexedDBError, range } from "@orkestrel/indexeddb";
+//#region src/browser/constants.ts
+var INDEXABLE_TYPES = /* @__PURE__ */ new Set([
+	"text",
+	"integer",
+	"real"
+]);
+var META_STORE = "__meta__";
+//#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 — 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
+*/
+function conditionRange(condition) {
+	const first = condition.values[0];
+	const second = condition.values[1];
+	switch (condition.operator) {
+		case "equals": return isKey(first) ? range.only(first) : null;
+		case "above": return isKey(first) ? range.above(first) : null;
+		case "below": return isKey(first) ? range.below(first) : null;
+		case "from": return isKey(first) ? range.from(first) : null;
+		case "to": return isKey(first) ? range.to(first) : null;
+		case "between": return isKey(first) && isKey(second) && compareValues(first, second) <= 0 ? range.between(first, second) : null;
+		case "not":
+		case "like":
+		case "glob":
+		case "starts":
+		case "ends":
+		case "any":
+		case "none":
+		case "absent":
+		case "present": return null;
+	}
+}
+function isKey(value) {
+	return typeof value === "string" || typeof value === "number";
+}
+/**
+* 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 }
+* ```
+*/
+function selectPlan(criteria, schema, available) {
+	const conditions = criteria?.conditions ?? [];
+	if (conditions.slice(1).some((condition) => condition.connector === "or")) return {
+		index: null,
+		range: null
+	};
+	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_TYPES.has(column.type)) continue;
+		const keyRange = conditionRange(condition);
+		if (keyRange === null) continue;
+		if (condition.column === schema.primary) return {
+			index: null,
+			range: keyRange
+		};
+		if (condition.operator === "below" || condition.operator === "to") continue;
+		if (available.includes(condition.column)) return {
+			index: condition.column,
+			range: keyRange
+		};
+	}
+	return {
+		index: null,
+		range: null
+	};
+}
+/**
+* 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`
+*/
+function mapIndexedDBError(error) {
+	switch (error.code) {
+		case "CONSTRAINT": return new DatabaseError("CONFLICT", error.message, { cause: error });
+		case "CLOSED":
+		case "NOT_OPEN":
+		case "INVALID": return new DatabaseError("CLOSED", error.message, { cause: error });
+		case "QUOTA": return new DatabaseError("DRIVER", error.message, {
+			cause: error,
+			code: "QUOTA"
+		});
+		case "BLOCKED": return new DatabaseError("DRIVER", error.message, {
+			cause: error,
+			code: "BLOCKED",
+			retryable: true
+		});
+		case "UPGRADE":
+		case "ABORTED":
+		case "NOT_FOUND":
+		case "DATA":
+		case "OPEN":
+		case "INACTIVE":
+		case "READONLY":
+		case "UNKNOWN": return new DatabaseError("DRIVER", error.message, { cause: error });
+	}
+}
+/**
+* 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`
+*/
+function mapMigrationError(error) {
+	if (error.code === "UPGRADE") return new DatabaseError("MIGRATION", error.message, { cause: error });
+	return mapIndexedDBError(error);
+}
+/**
+* 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'
+* ```
+*/
+function deriveIndexName(columns) {
+	if (columns.length === 1) return columns[0];
+	return `${columns.length}#${columns.map((column) => `${column.length}:${column}`).join("")}`;
+}
+//#endregion
+//#region src/browser/drivers/IndexedDBDriver.ts
+/**
+* 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.
+*/
+var IndexedDBDriver = class {
+	#name;
+	#schema = /* @__PURE__ */ new Map();
+	#database;
+	constructor(name) {
+		this.#name = name;
+	}
+	async open(schema) {
+		if (schema.some((table) => table.name === "__meta__")) throw new DatabaseError("VALIDATION", `open: table name '${META_STORE}' is reserved for driver metadata`, { table: META_STORE });
+		try {
+			this.#database?.close();
+			const map = /* @__PURE__ */ new Map();
+			for (const table of schema) map.set(table.name, table);
+			const database = createIndexedDBDatabase({
+				name: this.#name,
+				stores: this.#stores(map)
+			});
+			await database.connect();
+			this.#database = database;
+			this.#schema = map;
+		} catch (error) {
+			throw this.#wrap(error);
+		}
+	}
+	async close() {
+		this.#database?.close();
+		this.#database = void 0;
+	}
+	async read(table, key) {
+		try {
+			return await this.#store(table).get(key);
+		} catch (error) {
+			throw this.#wrap(error);
+		}
+	}
+	async write(table, key, row) {
+		try {
+			await this.#store(table).set(row, key);
+		} catch (error) {
+			throw this.#wrap(error);
+		}
+	}
+	async delete(table, key) {
+		try {
+			const store = this.#store(table);
+			const present = await store.has(key);
+			await store.remove(key);
+			return present;
+		} catch (error) {
+			throw this.#wrap(error);
+		}
+	}
+	async keys(table) {
+		try {
+			return (await this.#store(table).keys()).filter((key) => typeof key === "string" || typeof key === "number");
+		} catch (error) {
+			throw this.#wrap(error);
+		}
+	}
+	async *scan(table) {
+		try {
+			for (const row of await this.#store(table).records()) yield row;
+		} catch (error) {
+			throw this.#wrap(error);
+		}
+	}
+	async clear(table) {
+		try {
+			await this.#store(table).clear();
+		} catch (error) {
+			throw this.#wrap(error);
+		}
+	}
+	async records(table, criteria) {
+		try {
+			const schema = this.#table(table);
+			const store = this.#store(table);
+			const plan = selectPlan(criteria, schema, store.indexes);
+			return applyCriteria(await this.#candidates(store, schema, plan), criteria);
+		} catch (error) {
+			throw this.#wrap(error);
+		}
+	}
+	async count(table, criteria) {
+		try {
+			const schema = this.#table(table);
+			const store = this.#store(table);
+			const conditions = criteria.conditions ?? [];
+			if (conditions.length === 0) return await store.count();
+			const plan = selectPlan(criteria, schema, store.indexes);
+			if (conditions.length === 1 && plan.range !== null) return plan.index === null ? await store.count(plan.range) : await store.index(plan.index).count(plan.range);
+			return (plan.index === null ? await store.records(plan.range) : await store.index(plan.index).records(plan.range)).reduce((total, row) => matchesCriteria(row, conditions) ? total + 1 : total, 0);
+		} catch (error) {
+			throw this.#wrap(error);
+		}
+	}
+	async *stream(table, criteria) {
+		try {
+			const schema = this.#table(table);
+			const store = this.#store(table);
+			const plan = selectPlan(criteria, schema, store.indexes);
+			const conditions = criteria.conditions ?? [];
+			const offset = criteria.offset ?? 0;
+			const limit = criteria.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 (!matchesCriteria(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();
+			const names = tables ?? database.stores.filter((name) => name !== "__meta__");
+			const captured = /* @__PURE__ */ new Map();
+			if (names.length > 0) await database.read(names, async (transaction) => {
+				for (const name of names) {
+					const store = transaction.store(name);
+					captured.set(name, {
+						keys: await store.keys(),
+						rows: await store.records()
+					});
+				}
+			});
+			return async () => {
+				try {
+					const current = this.#require();
+					const restorable = names.filter((name) => current.stores.includes(name));
+					if (restorable.length === 0) return;
+					await current.write(restorable, async (transaction) => {
+						for (const name of restorable) {
+							const snapshot = captured.get(name);
+							if (snapshot === void 0) continue;
+							const store = transaction.store(name);
+							await store.clear();
+							for (let index = 0; index < snapshot.keys.length; index += 1) await store.set(snapshot.rows[index], snapshot.keys[index]);
+						}
+					});
+				} catch (error) {
+					throw this.#wrap(error);
+				}
+			};
+		} catch (error) {
+			throw this.#wrap(error);
+		}
+	}
+	/**
+	* 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`
+	*/
+	async meta() {
+		try {
+			const record = await this.#require().store(META_STORE).get("meta");
+			if (!isDriverMeta(record)) return void 0;
+			return record;
+		} catch (error) {
+			throw this.#wrap(error);
+		}
+	}
+	/**
+	* Persist `meta` verbatim for a later `meta()` to return.
+	*
+	* @param meta - The {@link DriverMeta} to persist
+	*/
+	async stamp(meta) {
+		try {
+			await this.#require().store(META_STORE).set({ ...meta }, "meta");
+		} catch (error) {
+			throw this.#wrap(error);
+		}
+	}
+	/**
+	* 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
+	*/
+	async migrate(plan) {
+		for (const step of plan.steps) if (step.operation !== "table.add" && !this.#schema.has(step.table)) throw new DatabaseError("MIGRATION", `migrate: unknown table '${step.table}'`, { table: step.table });
+		const current = this.#require();
+		const version = current.version;
+		const schema = new Map(this.#schema);
+		this.#applySteps(schema, plan.steps);
+		current.close();
+		try {
+			const database = createIndexedDBDatabase({
+				name: this.#name,
+				version: version + 1,
+				stores: this.#stores(schema),
+				upgrade: (context) => this.#upgrade(context, plan.steps)
+			});
+			await database.connect();
+			this.#database = database;
+			this.#schema = schema;
+		} catch (error) {
+			await this.#reopen();
+			throw isIndexedDBError(error) ? mapMigrationError(error) : error;
+		}
+	}
+	#require() {
+		if (this.#database === void 0) throw new DatabaseError("CLOSED", `IndexedDB database '${this.#name}' is not open`, { name: this.#name });
+		return this.#database;
+	}
+	#wrap(error) {
+		return isIndexedDBError(error) ? mapIndexedDBError(error) : error;
+	}
+	#store(table) {
+		return this.#require().store(table);
+	}
+	#stores(schema) {
+		const stores = { [META_STORE]: {} };
+		for (const table of schema.values()) stores[table.name] = { indexes: table.indexes.map((columns) => ({
+			name: deriveIndexName(columns),
+			path: columns.length === 1 ? columns[0] : [...columns]
+		})) };
+		return stores;
+	}
+	async #reopen() {
+		const database = createIndexedDBDatabase({
+			name: this.#name,
+			stores: this.#stores(this.#schema)
+		});
+		await database.connect();
+		this.#database = database;
+	}
+	async #candidates(store, schema, plan) {
+		if (plan.index === null) return store.records(plan.range);
+		const rows = [...await store.index(plan.index).records(plan.range)];
+		rows.sort((left, right) => compareValues(extractKey(left, schema.primary), extractKey(right, schema.primary)));
+		return rows;
+	}
+	#table(name) {
+		const schema = this.#schema.get(name);
+		if (schema === void 0) throw new DatabaseError("NOT_FOUND", `table '${name}' is not declared`, { table: name });
+		return schema;
+	}
+	#applySteps(schema, steps) {
+		const sameIndex = (left, right) => left.length === right.length && left.every((column, position) => column === right[position]);
+		for (const step of steps) switch (step.operation) {
+			case "table.add":
+				if (!schema.has(step.table.name)) schema.set(step.table.name, step.table);
+				break;
+			case "table.remove":
+				schema.delete(step.table);
+				break;
+			case "column.add": {
+				const table = schema.get(step.table);
+				if (table !== void 0 && !table.columns.some((column) => column.name === step.column.name)) schema.set(step.table, {
+					...table,
+					columns: [...table.columns, step.column]
+				});
+				break;
+			}
+			case "column.remove": {
+				const table = schema.get(step.table);
+				if (table !== void 0) schema.set(step.table, {
+					...table,
+					columns: table.columns.filter((column) => column.name !== step.column)
+				});
+				break;
+			}
+			case "index.add": {
+				const table = schema.get(step.table);
+				if (table !== void 0) schema.set(step.table, {
+					...table,
+					indexes: [...table.indexes, step.index]
+				});
+				break;
+			}
+			case "index.remove": {
+				const table = schema.get(step.table);
+				if (table !== void 0) schema.set(step.table, {
+					...table,
+					indexes: table.indexes.filter((index) => !sameIndex(index, step.index))
+				});
+				break;
+			}
+		}
+	}
+	async #upgrade(context, steps) {
+		for (const step of steps) switch (step.operation) {
+			case "table.remove":
+				context.drop(step.table);
+				break;
+			case "index.add": {
+				const name = deriveIndexName(step.index);
+				const path = step.index.length === 1 ? step.index[0] : [...step.index];
+				context.transaction.objectStore(step.table).createIndex(name, path);
+				break;
+			}
+			case "index.remove":
+				context.transaction.objectStore(step.table).deleteIndex(deriveIndexName(step.index));
+				break;
+			case "column.remove": {
+				let cursor = await context.store(step.table).cursor();
+				while (cursor !== null) {
+					const [migrated] = migrateRows([cursor.value], [step]);
+					await cursor.update(migrated);
+					cursor = await cursor.continue();
+				}
+				break;
+			}
+			case "table.add":
+			case "column.add": break;
+		}
+	}
+};
+//#endregion
+//#region src/browser/factories.ts
+/**
+* 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
+* ```
+*/
+function createIndexedDBDriver(name) {
+	return new IndexedDBDriver(name);
+}
+//#endregion
+export { INDEXABLE_TYPES, IndexedDBDriver, META_STORE, conditionRange, createIndexedDBDriver, deriveIndexName, isKey, mapIndexedDBError, mapMigrationError, selectPlan };
+
+//# sourceMappingURL=index.js.map