@orkestrel/indexeddb 0.0.1

package/dist/src/browser/index.js

@@ -0,0 +1,939 @@
+//#region src/browser/constants.ts
+/**
+* Native `DOMException.name` → our {@link IndexedDBErrorCode}.
+*
+* @remarks
+* The mapping the request boundary's `wrapError` reads to translate a raw
+* IndexedDB fault into a typed {@link IndexedDBError} code; an unmapped name
+* falls back to `UNKNOWN`. Frozen plain data (AGENTS §5).
+*/
+var ERROR_CODES = Object.freeze({
+	ConstraintError: "CONSTRAINT",
+	QuotaExceededError: "QUOTA",
+	AbortError: "ABORTED",
+	NotFoundError: "NOT_FOUND",
+	DataError: "DATA",
+	VersionError: "UPGRADE",
+	TransactionInactiveError: "INACTIVE",
+	InvalidStateError: "INVALID"
+});
+//#endregion
+//#region src/browser/errors.ts
+/**
+* An error thrown by the IndexedDB wrapper.
+*
+* @remarks
+* Carries an {@link IndexedDBErrorCode} and the originating native error as the
+* standard `cause`. Construct it directly for wrapper-lifecycle faults; the
+* internal `wrapError` maps a native `DOMException` to the right code at the
+* request boundary. Narrow a caught value with `instanceof IndexedDBError`.
+*
+* @example
+* ```ts
+* try {
+* 	await store.add(row)
+* } catch (error) {
+* 	if (error instanceof IndexedDBError && error.code === 'CONSTRAINT') await store.set(row)
+* }
+* ```
+*/
+var IndexedDBError = class extends Error {
+	code;
+	constructor(code, message, cause) {
+		super(message, { cause });
+		this.name = "IndexedDBError";
+		this.code = code;
+	}
+};
+/**
+* Whether a value is an {@link IndexedDBError}.
+*
+* @param value - The value to test
+* @returns `true` when `value` is an `IndexedDBError`
+*/
+function isIndexedDBError(value) {
+	return value instanceof IndexedDBError;
+}
+Object.freeze([
+	"null",
+	"boolean",
+	"object",
+	"array",
+	"number",
+	"integer",
+	"string"
+]);
+/**
+* Determine whether a value is a non-null object.
+*
+* @remarks
+* `true` for arrays, class instances, plain objects, `Map`, `Set`, etc. — use
+* {@link isRecord} when you need a plain-record check.
+*/
+function isObject(value) {
+	return typeof value === "object" && value !== null;
+}
+/**
+* Determine whether a value is a plain record (object literal or null-prototype),
+* not an array or class instance.
+*
+* @remarks
+* Use instead of {@link isObject} to distinguish a plain `{}` /
+* `Object.create(null)` from arrays, `Date`, `Map`, etc. The prototype-chain
+* test is realm-agnostic: rather than comparing against the current realm's
+* `Object.prototype` (which a plain object from another `vm.Context`, iframe,
+* or worker would fail), it accepts any value whose prototype is `null`, OR
+* whose prototype's own prototype is `null` — the shape every plain object
+* has in every realm, since `Object.prototype` itself always sits one step
+* above `null`. Arrays and class instances are still rejected: an array's
+* prototype chain runs through `Array.prototype` before `null`, and a class
+* instance's runs through the class's own prototype. The whole body runs
+* inside `attempt` (AGENTS §14) so a revoked `Proxy` or a hostile
+* `getPrototypeOf` trap cannot escape as a thrown error.
+*/
+function isRecord(value) {
+	const outcome = attempt(() => {
+		if (!isObject(value) || isArray(value)) return false;
+		const prototype = Object.getPrototypeOf(value);
+		return prototype === null || Object.getPrototypeOf(prototype) === null;
+	});
+	return outcome.success && outcome.value;
+}
+/** Determine whether a value is an array. */
+function isArray(value) {
+	return Array.isArray(value);
+}
+/**
+* Invoke a callback and capture its outcome as a {@link Result}, never letting
+* a throw escape.
+*
+* @remarks
+* The single sanctioned never-throw boundary for the guards (AGENTS §14). The
+* `whereOf`, `lazyOf`, and `transformOf` combinators invoke caller-supplied
+* callbacks *inside* a guard body, yet a guard must NEVER throw — it returns a
+* `boolean`. This converts a throwing callback into a `Failure` so the
+* surrounding guard can treat it as a non-match instead of propagating the
+* exception, written once and shared rather than copy-pasted as ad-hoc
+* `try`/`catch`.
+*
+* @param callback - The callback to invoke with no arguments
+* @returns A `Success` carrying the return value, or a `Failure` carrying the
+*          thrown reason normalised to an `Error`
+*
+* @example
+* ```ts
+* const outcome = attempt(() => predicate(value))
+* return outcome.success && outcome.value
+* ```
+*/
+function attempt(callback) {
+	try {
+		return {
+			success: true,
+			value: callback()
+		};
+	} catch (reason) {
+		if (reason instanceof Error) return {
+			success: false,
+			error: reason
+		};
+		let message = "Unknown thrown value";
+		try {
+			message = String(reason);
+		} catch {}
+		return {
+			success: false,
+			error: new Error(message)
+		};
+	}
+}
+//#endregion
+//#region src/browser/helpers.ts
+/**
+* Whether IndexedDB is available in this environment.
+*
+* @remarks
+* Gate IndexedDB code with this and fall back to another storage strategy where
+* it is absent (a non-browser runtime, a privacy mode that disables storage).
+* The entry probe, checked before reaching for the rest of this module.
+*
+* @returns `true` when `globalThis.indexedDB` exists
+*/
+function isIndexedDBSupported() {
+	return typeof globalThis.indexedDB !== "undefined";
+}
+/**
+* Resolve an `IDBRequest` to its result, rejecting with an {@link IndexedDBError}.
+*
+* @remarks
+* The single bridge from IndexedDB's event-based requests to Promises. Issue the
+* request, then `await` this — within an implicit transaction, issue every request
+* for that transaction before the first `await`, so they share it.
+*
+* @param request - The pending request
+* @returns Its `result` on success
+*/
+function promisifyRequest(request) {
+	return new Promise((resolve, reject) => {
+		request.onsuccess = () => resolve(request.result);
+		request.onerror = () => reject(wrapError(request.error));
+	});
+}
+/**
+* Resolve once an `IDBTransaction` commits, rejecting if it errors or aborts.
+*
+* @remarks
+* Await this after issuing the writes of a `readwrite` transaction to guarantee
+* they are durable before continuing.
+*
+* @param transaction - The transaction to await
+*/
+function promisifyTransaction(transaction) {
+	return new Promise((resolve, reject) => {
+		transaction.addEventListener("complete", () => resolve());
+		transaction.addEventListener("error", () => reject(wrapError(transaction.error)));
+		transaction.addEventListener("abort", () => reject(wrapError(transaction.error)));
+	});
+}
+/**
+* Run a synchronous native IndexedDB call, wrapping a thrown `DOMException`
+* into a typed {@link IndexedDBError}.
+*
+* @remarks
+* Native IndexedDB throws SYNCHRONOUSLY (not through a request's `onerror`)
+* from calls like `database.transaction(...)` or an inactive/closed store's
+* `get` / `put` / `openCursor` — `TransactionInactiveError` /
+* `InvalidStateError` never reach {@link promisifyRequest}'s `onerror`
+* bridge. Every request-issuing call site wraps its native invocation in this
+* so those faults surface as the same typed `IndexedDBError` as an
+* asynchronous one.
+*
+* @param action - The synchronous native call to run
+* @returns Its return value
+*/
+function guardSync(action) {
+	try {
+		return action();
+	} catch (error) {
+		if (error instanceof DOMException) throw wrapError(error);
+		throw error;
+	}
+}
+/**
+* Read one record by key from a store or index, narrowing it to a {@link Row}.
+*
+* @remarks
+* The shared point-read of every store-like class (`IndexedDBStore`,
+* `IndexedDBIndex`, `IndexedDBTransactionStore`): issue the native `get`, then
+* narrow the structured clone with `isRecord` — a non-record (or a miss) reads as
+* `undefined`, never an unchecked cast. On an index, `source.get` returns the
+* first record for the index key.
+*
+* @param source - The object store or index to read from
+* @param key - The key (a primary key for a store, an index key for an index)
+* @returns The record, or `undefined` on a miss
+*/
+async function readRecord(source, key) {
+	const value = await promisifyRequest(guardSync(() => source.get(key)));
+	return isRecord(value) ? value : void 0;
+}
+/**
+* Read many records from a store or index over an optional key range.
+*
+* @remarks
+* The shared bulk read of every store-like class: issue the native `getAll` over
+* an optional `query` (a key range or a single key) and `count` cap, then keep
+* only the records with `isRecord` — the same boundary narrowing as
+* {@link readRecord}, applied across the batch.
+*
+* @param source - The object store or index to read from
+* @param query - A key range or single key to restrict the read, or `null` for all
+* @param count - The maximum number of records to read
+* @returns The matching records
+*/
+async function readRecords(source, query, count) {
+	return (await promisifyRequest(guardSync(() => source.getAll(query ?? void 0, count)))).filter(isRecord);
+}
+/**
+* Whether a key is present in a store or index.
+*
+* @remarks
+* The shared presence test of every store-like class: a native `count` of the
+* key, true when at least one record matches — cheaper than reading the record
+* when only existence matters.
+*
+* @param source - The object store or index to test
+* @param key - The key to look for
+* @returns `true` when at least one record has the key
+*/
+async function hasKey(source, key) {
+	return await promisifyRequest(guardSync(() => source.count(key))) > 0;
+}
+/**
+* Key-range builders — the wrapper's filter vocabulary.
+*
+* @remarks
+* Each returns an `IDBKeyRange` to pass to `records` / `keys` / `count` / `cursor`,
+* so a read is index-backed (O(log n)) rather than a full scan. `only` (exact),
+* `above` / `from` (greater than, exclusive / inclusive), `below` / `to` (less
+* than, exclusive / inclusive), `between` (bounded), and `prefix` (string
+* starts-with).
+*/
+var range = {
+	only(value) {
+		return IDBKeyRange.only(value);
+	},
+	above(value) {
+		return IDBKeyRange.lowerBound(value, true);
+	},
+	from(value) {
+		return IDBKeyRange.lowerBound(value, false);
+	},
+	below(value) {
+		return IDBKeyRange.upperBound(value, true);
+	},
+	to(value) {
+		return IDBKeyRange.upperBound(value, false);
+	},
+	between(lower, upper, options) {
+		return IDBKeyRange.bound(lower, upper, options?.lowerOpen ?? false, options?.upperOpen ?? false);
+	},
+	prefix(value) {
+		return IDBKeyRange.bound(value, value + "￿", false, false);
+	}
+};
+/**
+* Map a native IndexedDB `DOMException` to a typed {@link IndexedDBError}.
+*
+* @remarks
+* The boundary the two Promise bridges ({@link promisifyRequest} /
+* {@link promisifyTransaction}) share: it reads {@link ERROR_CODES} to pick the
+* machine-readable code for the native `name`, falling back to `UNKNOWN` for an
+* unmapped name or a `null` error.
+*
+* @param error - The native error, or `null` when none is attached
+* @returns The wrapped, typed error
+*/
+function wrapError(error) {
+	if (error === null) return new IndexedDBError("UNKNOWN", "Unknown IndexedDB error");
+	return new IndexedDBError(ERROR_CODES[error.name] ?? "UNKNOWN", error.message || `IndexedDB error: ${error.name}`, error);
+}
+//#endregion
+//#region src/browser/IndexedDBCursor.ts
+/**
+* A promisified value cursor over an object store or index.
+*
+* @remarks
+* Wraps `IDBCursorWithValue` and the request that drives it. The position
+* (`key` / `primary` / `value`) is snapshot at construction because IndexedDB
+* mutates the live cursor object in place on each advance. `continue` / `seek` /
+* `advance` re-arm the shared request and resolve to the next position (a fresh
+* `IndexedDBCursor`) or `null` at the end. `update` / `delete` act on the current
+* record — they require the cursor's transaction to be `readwrite` (a `store`
+* cursor), so they reject on an `index` cursor's read-only transaction.
+*/
+var IndexedDBCursor = class IndexedDBCursor {
+	#cursor;
+	#request;
+	#key;
+	#primary;
+	#value;
+	#direction;
+	constructor(cursor, request) {
+		this.#cursor = cursor;
+		this.#request = request;
+		this.#key = cursor.key;
+		this.#primary = cursor.primaryKey;
+		this.#value = isRecord(cursor.value) ? cursor.value : {};
+		this.#direction = cursor.direction;
+	}
+	get cursor() {
+		return this.#cursor;
+	}
+	get source() {
+		return this.#cursor.source;
+	}
+	get key() {
+		return this.#key;
+	}
+	get primary() {
+		return this.#primary;
+	}
+	get value() {
+		return this.#value;
+	}
+	get direction() {
+		return this.#direction;
+	}
+	async continue(key) {
+		guardSync(() => {
+			if (key === void 0) this.#cursor.continue();
+			else this.#cursor.continue(key);
+		});
+		return this.#advance();
+	}
+	async seek(key, primary) {
+		guardSync(() => this.#cursor.continuePrimaryKey(key, primary));
+		return this.#advance();
+	}
+	async advance(count) {
+		guardSync(() => this.#cursor.advance(count));
+		return this.#advance();
+	}
+	async update(value) {
+		const key = await promisifyRequest(guardSync(() => this.#cursor.update(value)));
+		this.#value = value;
+		return key;
+	}
+	async delete() {
+		await promisifyRequest(guardSync(() => this.#cursor.delete()));
+	}
+	async #advance() {
+		const next = await promisifyRequest(this.#request);
+		return next ? new IndexedDBCursor(next, this.#request) : null;
+	}
+};
+//#endregion
+//#region src/browser/IndexedDBIndex.ts
+/**
+* A secondary index on a store — a read-only view keyed by an indexed path.
+*
+* @remarks
+* Reached through `store.index(name)`. Each call opens its own `readonly`
+* transaction. `get` / `resolve` fetch the first record for an index key
+* (`resolve` throws `NOT_FOUND`); `records` reads the matching records and `keys`
+* their **primary** keys; `primary` maps an index key to one primary key; `count`
+* / `has` test presence; `cursor` streams matches. Reads batch by their array
+* overload (AGENTS §9.2).
+*/
+var IndexedDBIndex = class {
+	#store;
+	#name;
+	#definition;
+	#connect;
+	constructor(store, name, definition, connect) {
+		this.#store = store;
+		this.#name = name;
+		this.#definition = definition;
+		this.#connect = connect;
+	}
+	get name() {
+		return this.#name;
+	}
+	get path() {
+		return this.#definition.path;
+	}
+	get unique() {
+		return this.#definition.unique ?? false;
+	}
+	get multiple() {
+		return this.#definition.multiple ?? false;
+	}
+	async get(keyOrKeys) {
+		const index = await this.#index();
+		if (isArray(keyOrKeys)) return Promise.all(keyOrKeys.map((key) => readRecord(index, key)));
+		return readRecord(index, keyOrKeys);
+	}
+	async resolve(keyOrKeys) {
+		const index = await this.#index();
+		if (isArray(keyOrKeys)) return Promise.all(keyOrKeys.map((key) => this.#resolve(index, key)));
+		return this.#resolve(index, keyOrKeys);
+	}
+	async records(query, count) {
+		return readRecords(await this.#index(), query, count);
+	}
+	async keys(query, count) {
+		const index = await this.#index();
+		return promisifyRequest(guardSync(() => index.getAllKeys(query ?? void 0, count)));
+	}
+	async primary(key) {
+		const index = await this.#index();
+		return promisifyRequest(guardSync(() => index.getKey(key)));
+	}
+	async has(keyOrKeys) {
+		const index = await this.#index();
+		if (isArray(keyOrKeys)) return Promise.all(keyOrKeys.map((key) => hasKey(index, key)));
+		return hasKey(index, keyOrKeys);
+	}
+	async count(query) {
+		const index = await this.#index();
+		return promisifyRequest(guardSync(() => index.count(query ?? void 0)));
+	}
+	async cursor(options) {
+		const index = await this.#index();
+		const request = guardSync(() => index.openCursor(options?.query ?? null, options?.direction ?? "next"));
+		const cursor = await promisifyRequest(request);
+		return cursor ? new IndexedDBCursor(cursor, request) : null;
+	}
+	async #index() {
+		const database = await this.#connect();
+		return guardSync(() => database.transaction([this.#store], "readonly").objectStore(this.#store).index(this.#name));
+	}
+	async #resolve(index, key) {
+		const value = await readRecord(index, key);
+		if (value === void 0) throw new IndexedDBError("NOT_FOUND", `No record in index '${this.#name}' of store '${this.#store}' for key ${String(key)}`);
+		return value;
+	}
+};
+//#endregion
+//#region src/browser/IndexedDBStore.ts
+/**
+* An object store — the full keyed CRUD surface plus index, count, and cursor
+* access.
+*
+* @remarks
+* Reached through `database.store(name)`. Each call runs in its own implicit
+* transaction (`readonly` for reads, `readwrite` for writes), awaiting completion
+* so writes are durable on return; for atomic multi-operation work use the
+* database's `read` / `write`. The keyed verbs batch by their array overload — and
+* those overloads are declared first, because an array is itself both a record and
+* a compound `IDBValidKey`, so the array signature must take precedence to read as
+* a batch (AGENTS §9.2). Pass `range.only([…])` to `records` / `count` to act on a
+* single compound key.
+*/
+var IndexedDBStore = class {
+	#name;
+	#definition;
+	#connect;
+	constructor(name, definition, connect) {
+		this.#name = name;
+		this.#definition = definition;
+		this.#connect = connect;
+	}
+	get name() {
+		return this.#name;
+	}
+	get path() {
+		return this.#definition.path ?? null;
+	}
+	get indexes() {
+		return (this.#definition.indexes ?? []).map((index) => index.name);
+	}
+	get increment() {
+		return this.#definition.increment ?? false;
+	}
+	async get(keyOrKeys) {
+		const store = await this.#store("readonly");
+		if (isArray(keyOrKeys)) return Promise.all(keyOrKeys.map((key) => readRecord(store, key)));
+		return readRecord(store, keyOrKeys);
+	}
+	async resolve(keyOrKeys) {
+		const store = await this.#store("readonly");
+		if (isArray(keyOrKeys)) return Promise.all(keyOrKeys.map((key) => this.#resolve(store, key)));
+		return this.#resolve(store, keyOrKeys);
+	}
+	async records(query, count) {
+		return readRecords(await this.#store("readonly"), query, count);
+	}
+	async keys(query, count) {
+		const store = await this.#store("readonly");
+		return promisifyRequest(guardSync(() => store.getAllKeys(query ?? void 0, count)));
+	}
+	async has(keyOrKeys) {
+		const store = await this.#store("readonly");
+		if (isArray(keyOrKeys)) return Promise.all(keyOrKeys.map((key) => hasKey(store, key)));
+		return hasKey(store, keyOrKeys);
+	}
+	async count(query) {
+		const store = await this.#store("readonly");
+		return promisifyRequest(guardSync(() => store.count(query ?? void 0)));
+	}
+	async set(valueOrValues, key) {
+		const store = await this.#store("readwrite");
+		if (isArray(valueOrValues)) {
+			const keys = await Promise.all(valueOrValues.map((value) => promisifyRequest(guardSync(() => store.put(value)))));
+			await promisifyTransaction(store.transaction);
+			return keys;
+		}
+		const written = await promisifyRequest(guardSync(() => key === void 0 ? store.put(valueOrValues) : store.put(valueOrValues, key)));
+		await promisifyTransaction(store.transaction);
+		return written;
+	}
+	async add(valueOrValues, key) {
+		const store = await this.#store("readwrite");
+		if (isArray(valueOrValues)) {
+			const keys = await Promise.all(valueOrValues.map((value) => promisifyRequest(guardSync(() => store.add(value)))));
+			await promisifyTransaction(store.transaction);
+			return keys;
+		}
+		const written = await promisifyRequest(guardSync(() => key === void 0 ? store.add(valueOrValues) : store.add(valueOrValues, key)));
+		await promisifyTransaction(store.transaction);
+		return written;
+	}
+	async remove(keyOrKeys) {
+		const store = await this.#store("readwrite");
+		if (isArray(keyOrKeys)) await Promise.all(keyOrKeys.map((key) => promisifyRequest(guardSync(() => store.delete(key)))));
+		else await promisifyRequest(guardSync(() => store.delete(keyOrKeys)));
+		await promisifyTransaction(store.transaction);
+	}
+	async clear() {
+		const store = await this.#store("readwrite");
+		await promisifyRequest(guardSync(() => store.clear()));
+		await promisifyTransaction(store.transaction);
+	}
+	index(name) {
+		const definition = (this.#definition.indexes ?? []).find((index) => index.name === name);
+		if (definition === void 0) throw new IndexedDBError("NOT_FOUND", `Index '${name}' is not declared on store '${this.#name}'`);
+		return new IndexedDBIndex(this.#name, name, definition, this.#connect);
+	}
+	async cursor(options) {
+		const store = await this.#store("readwrite");
+		const request = guardSync(() => store.openCursor(options?.query ?? null, options?.direction ?? "next"));
+		const cursor = await promisifyRequest(request);
+		return cursor ? new IndexedDBCursor(cursor, request) : null;
+	}
+	async #store(mode) {
+		const database = await this.#connect();
+		return guardSync(() => database.transaction([this.#name], mode).objectStore(this.#name));
+	}
+	async #resolve(store, key) {
+		const value = await readRecord(store, key);
+		if (value === void 0) throw new IndexedDBError("NOT_FOUND", `No record in store '${this.#name}' for key ${String(key)}`);
+		return value;
+	}
+};
+//#endregion
+//#region src/browser/IndexedDBTransactionStore.ts
+/**
+* An object store bound to an explicit transaction.
+*
+* @remarks
+* The same CRUD surface as a standalone store, but every call runs in the owning
+* transaction (opened by the database's `read` / `write`) rather than its own — so
+* a sequence of reads and writes commits atomically when the scope resolves. It
+* does not await transaction completion per call (the scope does that once) and
+* omits `index`; keep your awaited operations on IndexedDB requests only, so the
+* transaction stays active across them.
+*/
+var IndexedDBTransactionStore = class {
+	#store;
+	#name;
+	constructor(store) {
+		this.#store = store;
+		this.#name = store.name;
+	}
+	get store() {
+		return this.#store;
+	}
+	async get(keyOrKeys) {
+		if (isArray(keyOrKeys)) return Promise.all(keyOrKeys.map((key) => readRecord(this.#store, key)));
+		return readRecord(this.#store, keyOrKeys);
+	}
+	async resolve(keyOrKeys) {
+		if (isArray(keyOrKeys)) return Promise.all(keyOrKeys.map((key) => this.#resolve(key)));
+		return this.#resolve(keyOrKeys);
+	}
+	async records(query, count) {
+		return readRecords(this.#store, query, count);
+	}
+	async keys(query, count) {
+		return promisifyRequest(guardSync(() => this.#store.getAllKeys(query ?? void 0, count)));
+	}
+	async has(keyOrKeys) {
+		if (isArray(keyOrKeys)) return Promise.all(keyOrKeys.map((key) => hasKey(this.#store, key)));
+		return hasKey(this.#store, keyOrKeys);
+	}
+	async count(query) {
+		return promisifyRequest(guardSync(() => this.#store.count(query ?? void 0)));
+	}
+	async set(valueOrValues, key) {
+		if (isArray(valueOrValues)) return Promise.all(valueOrValues.map((value) => promisifyRequest(guardSync(() => this.#store.put(value)))));
+		return promisifyRequest(guardSync(() => key === void 0 ? this.#store.put(valueOrValues) : this.#store.put(valueOrValues, key)));
+	}
+	async add(valueOrValues, key) {
+		if (isArray(valueOrValues)) return Promise.all(valueOrValues.map((value) => promisifyRequest(guardSync(() => this.#store.add(value)))));
+		return promisifyRequest(guardSync(() => key === void 0 ? this.#store.add(valueOrValues) : this.#store.add(valueOrValues, key)));
+	}
+	async remove(keyOrKeys) {
+		if (isArray(keyOrKeys)) {
+			await Promise.all(keyOrKeys.map((key) => promisifyRequest(guardSync(() => this.#store.delete(key)))));
+			return;
+		}
+		await promisifyRequest(guardSync(() => this.#store.delete(keyOrKeys)));
+	}
+	async clear() {
+		await promisifyRequest(guardSync(() => this.#store.clear()));
+	}
+	async cursor(options) {
+		const request = guardSync(() => this.#store.openCursor(options?.query ?? null, options?.direction ?? "next"));
+		const cursor = await promisifyRequest(request);
+		return cursor ? new IndexedDBCursor(cursor, request) : null;
+	}
+	async #resolve(key) {
+		const value = await readRecord(this.#store, key);
+		if (value === void 0) throw new IndexedDBError("NOT_FOUND", `No record in store '${this.#name}' for key ${String(key)}`);
+		return value;
+	}
+};
+//#endregion
+//#region src/browser/IndexedDBTransaction.ts
+/**
+* An explicit transaction over one or more stores.
+*
+* @remarks
+* Wraps `IDBTransaction` with state tracking and typed, scope-bound store access.
+* Constructed by the database's `read` / `write`, which await its completion (or
+* roll it back on a throw). `store` reaches a store within the transaction's scope;
+* `abort` rolls back; `commit` flushes early (the scope's completion commits
+* otherwise). `active` is true until commit or abort; `finished` is its complement.
+*/
+var IndexedDBTransaction = class {
+	#transaction;
+	#stores;
+	#active = true;
+	#finished = false;
+	constructor(transaction) {
+		this.#transaction = transaction;
+		this.#stores = Array.from(transaction.objectStoreNames);
+		const settle = () => {
+			this.#active = false;
+			this.#finished = true;
+		};
+		transaction.addEventListener("complete", settle);
+		transaction.addEventListener("abort", settle);
+		transaction.addEventListener("error", settle);
+	}
+	get transaction() {
+		return this.#transaction;
+	}
+	get mode() {
+		return this.#transaction.mode;
+	}
+	get stores() {
+		return this.#stores;
+	}
+	get active() {
+		return this.#active;
+	}
+	get finished() {
+		return this.#finished;
+	}
+	get error() {
+		return this.#transaction.error;
+	}
+	store(name) {
+		if (!this.#stores.includes(name)) throw new IndexedDBError("NOT_FOUND", `Store '${name}' is outside this transaction's scope (${this.#stores.join(", ")})`);
+		if (!this.#active) throw new IndexedDBError("ABORTED", `Transaction over ${this.#stores.join(", ")} is no longer active`);
+		return new IndexedDBTransactionStore(this.#transaction.objectStore(name));
+	}
+	abort() {
+		if (this.#finished) throw new IndexedDBError("ABORTED", "Cannot abort an already-finished transaction");
+		this.#transaction.abort();
+		this.#active = false;
+		this.#finished = true;
+	}
+	commit() {
+		if (this.#finished) throw new IndexedDBError("ABORTED", "Cannot commit an already-finished transaction");
+		this.#transaction.commit();
+	}
+};
+//#endregion
+//#region src/browser/IndexedDBDatabase.ts
+/**
+* A browser-native IndexedDB database — a typed, Promise-based handle.
+*
+* @remarks
+* Connects lazily on first use (`connect`, also awaited internally by every store
+* operation), creating any missing stores from their definitions inside
+* `onupgradeneeded`. `store` reaches a typed store; `read` / `write` run an atomic
+* scope over one or more stores, committing on resolve and rolling back on a throw;
+* `close` releases the connection and `drop` deletes the database. Schema changes
+* beyond creating new stores (dropping stores, altering indexes) are deferred.
+*/
+var IndexedDBDatabase = class {
+	#name;
+	#version;
+	#stores;
+	#upgrade;
+	#database;
+	#opening;
+	#closed = false;
+	constructor(options) {
+		if (options.name.length === 0) throw new IndexedDBError("OPEN", "Database name must be a non-empty string");
+		if (options.version !== void 0 && (!Number.isInteger(options.version) || options.version < 1)) throw new IndexedDBError("OPEN", `Database version must be a positive integer, got ${String(options.version)}`);
+		this.#name = options.name;
+		this.#version = options.version;
+		this.#stores = options.stores;
+		this.#upgrade = options.upgrade;
+	}
+	get database() {
+		if (this.#database === void 0) throw new IndexedDBError("NOT_OPEN", `Database '${this.#name}' is not open — call connect() first`);
+		return this.#database;
+	}
+	get name() {
+		return this.#name;
+	}
+	get version() {
+		return this.#database?.version ?? this.#version ?? 0;
+	}
+	get stores() {
+		if (this.#database !== void 0) return Array.from(this.#database.objectStoreNames);
+		return Object.keys(this.#stores);
+	}
+	get open() {
+		return this.#database !== void 0 && !this.#closed;
+	}
+	connect() {
+		if (this.#closed) throw new IndexedDBError("CLOSED", `Database '${this.#name}' has been closed`);
+		if (this.#database !== void 0) return Promise.resolve(this.#database);
+		if (this.#opening !== void 0) return this.#opening;
+		this.#opening = this.#open().catch((error) => {
+			this.#opening = void 0;
+			throw error;
+		});
+		return this.#opening;
+	}
+	store(name) {
+		const definition = this.#stores[name];
+		if (definition === void 0) throw new IndexedDBError("NOT_FOUND", `Store '${name}' is not declared on database '${this.#name}'`);
+		return new IndexedDBStore(name, definition, () => this.connect());
+	}
+	read(stores, scope) {
+		return this.#run("readonly", stores, scope);
+	}
+	write(stores, scope) {
+		return this.#run("readwrite", stores, scope);
+	}
+	close() {
+		this.#database?.close();
+		this.#database = void 0;
+		this.#opening = void 0;
+		this.#closed = true;
+	}
+	async drop() {
+		this.close();
+		return new Promise((resolve, reject) => {
+			const request = globalThis.indexedDB.deleteDatabase(this.#name);
+			request.onsuccess = () => resolve();
+			request.onerror = () => reject(new IndexedDBError("UNKNOWN", `Failed to delete database '${this.#name}'`, request.error));
+			request.onblocked = () => reject(new IndexedDBError("BLOCKED", `Deletion of '${this.#name}' is blocked by another connection`));
+		});
+	}
+	async #run(mode, stores, scope) {
+		const database = await this.connect();
+		const names = isArray(stores) ? [...stores] : [stores];
+		const native = guardSync(() => database.transaction(names, mode));
+		const tx = new IndexedDBTransaction(native);
+		try {
+			await scope(tx);
+			await promisifyTransaction(native);
+		} catch (error) {
+			if (tx.active) try {
+				tx.abort();
+			} catch {}
+			throw error;
+		}
+	}
+	async #open() {
+		let database = await this.#request(this.#version);
+		if (this.#version === void 0) {
+			if (this.#missing(database).length > 0) {
+				const next = database.version + 1;
+				database.close();
+				database = await this.#request(next);
+			}
+		}
+		database.onclose = () => {
+			this.#database = void 0;
+		};
+		database.onversionchange = () => {
+			database.close();
+			this.#database = void 0;
+			this.#opening = void 0;
+		};
+		this.#database = database;
+		return database;
+	}
+	#request(version) {
+		return new Promise((resolve, reject) => {
+			let upgradeError;
+			const request = version === void 0 ? globalThis.indexedDB.open(this.#name) : globalThis.indexedDB.open(this.#name, version);
+			request.onupgradeneeded = (event) => {
+				const database = request.result;
+				for (const [name, definition] of Object.entries(this.#stores)) if (!database.objectStoreNames.contains(name)) this.#createStore(database, name, definition);
+				if (this.#upgrade !== void 0) {
+					const transaction = request.transaction;
+					if (transaction !== null) {
+						const result = this.#upgrade(this.#context(database, transaction, event));
+						if (result !== void 0) result.catch((error) => {
+							upgradeError = error;
+							try {
+								transaction.abort();
+							} catch {}
+						});
+					}
+				}
+			};
+			request.onsuccess = () => resolve(request.result);
+			request.onerror = () => reject(upgradeError !== void 0 ? new IndexedDBError("UPGRADE", `Upgrade of '${this.#name}' failed`, upgradeError) : new IndexedDBError("OPEN", `Failed to open database '${this.#name}'`, request.error));
+			request.onblocked = () => reject(new IndexedDBError("BLOCKED", `Open of '${this.#name}' is blocked by another connection`));
+		});
+	}
+	#missing(database) {
+		return Object.keys(this.#stores).filter((name) => !database.objectStoreNames.contains(name));
+	}
+	#context(database, transaction, event) {
+		return {
+			transaction,
+			old: event.oldVersion,
+			version: event.newVersion ?? database.version,
+			stores: Array.from(database.objectStoreNames),
+			create: (name, definition) => {
+				this.#createStore(database, name, definition);
+			},
+			drop: (name) => {
+				database.deleteObjectStore(name);
+			},
+			store: (name) => new IndexedDBTransactionStore(transaction.objectStore(name))
+		};
+	}
+	#createStore(database, name, definition) {
+		const options = { autoIncrement: definition.increment ?? false };
+		if (definition.path !== void 0) options.keyPath = typeof definition.path === "string" ? definition.path : [...definition.path];
+		const store = database.createObjectStore(name, options);
+		for (const index of definition.indexes ?? []) {
+			const keyPath = typeof index.path === "string" ? index.path : [...index.path];
+			store.createIndex(index.name, keyPath, {
+				unique: index.unique ?? false,
+				multiEntry: index.multiple ?? false
+			});
+		}
+	}
+};
+//#endregion
+//#region src/browser/factories.ts
+/**
+* Create a browser-native IndexedDB database over a store schema.
+*
+* @remarks
+* The `const` type parameter captures the literal store names, so `db.store(name)`
+* and `db.read` / `db.write` are checked against the declared stores. Stores are
+* created from their definitions the first time the database opens at a new
+* `version`; omit `version` for auto-managed mode, where the database bumps its
+* own version once to create any declared store the stored schema is missing.
+*
+* @param options - The database `name`, `version`, and `stores` schema
+* @returns A typed {@link IndexedDBDatabaseInterface}
+*
+* @example
+* ```ts
+* import { createIndexedDBDatabase, range } from '@src/browser'
+*
+* const db = createIndexedDBDatabase({
+* 	name: 'app',
+* 	version: 1,
+* 	stores: {
+* 		users: { path: 'id', indexes: [{ name: 'byAge', path: 'age' }] },
+* 	},
+* })
+* await db.store('users').set({ id: 'u1', name: 'Ada', age: 36 })
+* await db.store('users').index('byAge').records(range.from(18)) // adults, index-backed
+* ```
+*/
+function createIndexedDBDatabase(options) {
+	return new IndexedDBDatabase(options);
+}
+//#endregion
+export { ERROR_CODES, IndexedDBCursor, IndexedDBDatabase, IndexedDBError, IndexedDBIndex, IndexedDBStore, IndexedDBTransaction, IndexedDBTransactionStore, createIndexedDBDatabase, guardSync, hasKey, isIndexedDBError, isIndexedDBSupported, promisifyRequest, promisifyTransaction, range, readRecord, readRecords, wrapError };
+
+//# sourceMappingURL=index.js.map