@orkestrel/indexeddb 0.0.1 → 0.0.2

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

@@ -1,11 +1,753 @@
-export type * from './types.js';
-export * from './constants.js';
-export * from './errors.js';
-export * from './helpers.js';
-export * from './factories.js';
-export * from './IndexedDBDatabase.js';
-export * from './IndexedDBStore.js';
-export * from './IndexedDBIndex.js';
-export * from './IndexedDBCursor.js';
-export * from './IndexedDBTransaction.js';
-export * from './IndexedDBTransactionStore.js';
+/**
+ * Create a secondary index on a store from its {@link IndexDefinition}.
+ *
+ * @remarks
+ * The shared index-DDL leaf used both by the built-in create-missing-stores pass
+ * (`IndexedDBDatabase`'s internal store creation) and by an upgrade's
+ * `context.index`: translate the definition's `path` to a native key path and
+ * `unique` / `multiple` to `unique` / `multiEntry`, then issue `createIndex`.
+ * Versionchange-only — `store` must be inside an active upgrade transaction.
+ *
+ * @param store - The object store to add the index to
+ * @param definition - The index to create
+ */
+export declare function createIndex(store: IDBObjectStore, definition: IndexDefinition): void;
+
+/**
+ * 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 '@orkestrel/indexeddb'
+ *
+ * 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
+ * ```
+ */
+export declare function createIndexedDBDatabase<const Stores extends StoresShape>(options: IndexedDBDatabaseOptions<Stores>): IndexedDBDatabaseInterface<Stores>;
+
+/**
+ * Options for opening a cursor.
+ *
+ * @remarks
+ * `query` restricts iteration to a key range (or a single key); `direction` sets
+ * the traversal order (`next` / `prev` / their `unique` variants).
+ */
+export declare interface CursorOptions {
+    readonly query?: IDBKeyRange | IDBValidKey | null;
+    readonly direction?: IDBCursorDirection;
+}
+
+/**
+ * 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).
+ */
+export declare const ERROR_CODES: Readonly<Record<string, IndexedDBErrorCode>>;
+
+/**
+ * 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
+ */
+export declare function guardSync<T>(action: () => T): T;
+
+/**
+ * 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
+ */
+export declare function hasKey(source: IDBObjectStore | IDBIndex, key: IDBValidKey): Promise<boolean>;
+
+/**
+ * A secondary index on a store.
+ *
+ * @remarks
+ * `name` identifies the index for `store.index(name)`; `path` is the field(s) it
+ * indexes; `unique` enforces one record per indexed value; `multiple` (IndexedDB's
+ * `multiEntry`) indexes each element of an array value separately.
+ */
+export declare interface IndexDefinition {
+    readonly name: string;
+    readonly path: KeyPath;
+    readonly unique?: boolean;
+    readonly multiple?: boolean;
+}
+
+/**
+ * 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.
+ */
+export declare class IndexedDBCursor implements IndexedDBCursorInterface {
+    #private;
+    constructor(cursor: IDBCursorWithValue, request: IDBRequest<IDBCursorWithValue | null>);
+    get cursor(): IDBCursorWithValue;
+    get source(): IDBObjectStore | IDBIndex;
+    get key(): IDBValidKey;
+    get primary(): IDBValidKey;
+    get value(): Row;
+    get direction(): IDBCursorDirection;
+    continue(key?: IDBValidKey): Promise<IndexedDBCursorInterface | null>;
+    seek(key: IDBValidKey, primary: IDBValidKey): Promise<IndexedDBCursorInterface | null>;
+    advance(count: number): Promise<IndexedDBCursorInterface | null>;
+    update(value: Row): Promise<IDBValidKey>;
+    delete(): Promise<void>;
+}
+
+/**
+ * A promisified value cursor for streaming and in-place mutation.
+ *
+ * @remarks
+ * Wraps `IDBCursorWithValue`. `key` / `primary` / `value` snapshot the current
+ * position (IndexedDB reuses the live cursor object on advance, so they are read
+ * eagerly). `continue` / `seek` / `advance` resolve to the next cursor or `null`
+ * at the end; `update` / `delete` mutate the record at the current position. The
+ * owning transaction stays alive only while you drive the cursor promptly — do no
+ * unrelated `await` between steps, or it auto-commits.
+ */
+export declare interface IndexedDBCursorInterface {
+    readonly cursor: IDBCursorWithValue;
+    readonly source: IDBObjectStore | IDBIndex;
+    readonly key: IDBValidKey;
+    readonly primary: IDBValidKey;
+    readonly value: Row;
+    readonly direction: IDBCursorDirection;
+    continue(key?: IDBValidKey): Promise<IndexedDBCursorInterface | null>;
+    seek(key: IDBValidKey, primary: IDBValidKey): Promise<IndexedDBCursorInterface | null>;
+    advance(count: number): Promise<IndexedDBCursorInterface | null>;
+    update(value: Row): Promise<IDBValidKey>;
+    delete(): Promise<void>;
+}
+
+/**
+ * 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.
+ */
+export declare class IndexedDBDatabase<Stores extends StoresShape = StoresShape> implements IndexedDBDatabaseInterface<Stores> {
+    #private;
+    constructor(options: IndexedDBDatabaseOptions<Stores>);
+    get database(): IDBDatabase;
+    get name(): string;
+    get version(): number;
+    get stores(): readonly string[];
+    get open(): boolean;
+    connect(): Promise<IDBDatabase>;
+    store<K extends keyof Stores & string>(name: K): IndexedDBStoreInterface;
+    read(stores: (keyof Stores & string) | readonly (keyof Stores & string)[], scope: (tx: IndexedDBTransactionInterface<Stores>) => void | Promise<void>): Promise<void>;
+    write(stores: (keyof Stores & string) | readonly (keyof Stores & string)[], scope: (tx: IndexedDBTransactionInterface<Stores>) => void | Promise<void>): Promise<void>;
+    close(): void;
+    drop(): Promise<void>;
+}
+
+/**
+ * A browser-native IndexedDB database.
+ *
+ * @remarks
+ * A typed, Promise-based handle over `IDBDatabase`. It connects lazily on first
+ * use (`connect`, also awaited by every store operation); `store` reaches a typed
+ * store; `read` / `write` run an atomic scope over one or more stores; `close`
+ * releases the connection and `drop` deletes the database. `stores` lists the
+ * declared (or, once open, the live) store names; `open` reports whether a live
+ * connection is held.
+ */
+export declare interface IndexedDBDatabaseInterface<Stores extends StoresShape = StoresShape> {
+    readonly database: IDBDatabase;
+    readonly name: string;
+    readonly version: number;
+    readonly stores: readonly string[];
+    readonly open: boolean;
+    connect(): Promise<IDBDatabase>;
+    store<K extends keyof Stores & string>(name: K): IndexedDBStoreInterface;
+    read(stores: (keyof Stores & string) | readonly (keyof Stores & string)[], scope: (tx: IndexedDBTransactionInterface<Stores>) => void | Promise<void>): Promise<void>;
+    write(stores: (keyof Stores & string) | readonly (keyof Stores & string)[], scope: (tx: IndexedDBTransactionInterface<Stores>) => void | Promise<void>): Promise<void>;
+    close(): void;
+    drop(): Promise<void>;
+}
+
+/**
+ * Options for `createIndexedDBDatabase`.
+ *
+ * @remarks
+ * `name` is passed to `indexedDB.open`. `version` is optional: give it to pin an
+ * explicit schema version (a higher number than the stored one triggers an upgrade
+ * that creates any missing `stores`); omit it for **auto-managed** mode, where the
+ * database opens at its current version and bumps once to create any declared store
+ * the stored schema is missing — so adding a store never needs a manual version
+ * bump. `upgrade` runs after the built-in create-missing-stores pass, inside the
+ * same versionchange transaction — use it to drop a store, add or remove an index
+ * on any store with `context.index` / `context.deindex`, or migrate data with
+ * `context.store(name)`. It may return `void` or a `Promise<void>` — an async
+ * `upgrade` may `await` the IDB requests it issues through `context.store(...)`
+ * (see the auto-commit rule on {@link IndexedDBUpgradeContext}); a rejection
+ * aborts the versionchange transaction and rejects the pending `connect()` with
+ * an `IndexedDBError` (code `UPGRADE`) instead of an unhandled rejection.
+ */
+export declare interface IndexedDBDatabaseOptions<Stores extends StoresShape = StoresShape> {
+    readonly name: string;
+    readonly version?: number;
+    readonly stores: Stores;
+    readonly upgrade?: (context: IndexedDBUpgradeContext) => void | Promise<void>;
+}
+
+/**
+ * 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)
+ * }
+ * ```
+ */
+export declare class IndexedDBError extends Error {
+    readonly code: IndexedDBErrorCode;
+    constructor(code: IndexedDBErrorCode, message: string, cause?: unknown);
+}
+
+/**
+ * A machine-readable {@link IndexedDBError} code.
+ *
+ * @remarks
+ * Each maps from a native `DOMException.name` or a wrapper-lifecycle fault:
+ * `NOT_OPEN` (used before `connect`), `CLOSED` (used after `close`), `NOT_FOUND`
+ * (a `resolve` miss), `CONSTRAINT` (a unique-key violation), `QUOTA` (storage
+ * full), `ABORTED` (a transaction rolled back), `BLOCKED` (an open held up by
+ * another live connection), `DATA` (an invalid key or an un-clonable value —
+ * native `DataError` and `DataCloneError` both map here), `OPEN` /
+ * `UPGRADE` (a failed open or schema upgrade), `INACTIVE` (the transaction went
+ * inactive — IndexedDB's auto-commit fault, raised when an operation runs after
+ * a non-IDB `await` deactivated its transaction — reachable through
+ * `IndexedDBTransactionStoreInterface`, and when `IndexedDBTransactionInterface`'s
+ * `abort` / `commit` are called on an already-finished transaction), `READONLY`
+ * (native `ReadOnlyError` — a write attempted on a `readonly` transaction, e.g.
+ * mutating through a cursor opened in a `read` scope), `INVALID` (native
+ * `InvalidStateError` — a defensive mapping for a deleted store/index or
+ * similarly invalid native handle; not cleanly reachable through this
+ * wrapper's public API, which always opens a fresh transaction or routes
+ * through the auto-commit-guarded transaction store above), and `UNKNOWN` (any
+ * unmapped fault).
+ */
+export declare type IndexedDBErrorCode = 'NOT_OPEN' | 'CLOSED' | 'NOT_FOUND' | 'CONSTRAINT' | 'QUOTA' | 'ABORTED' | 'BLOCKED' | 'DATA' | 'OPEN' | 'UPGRADE' | 'INACTIVE' | 'READONLY' | 'INVALID' | 'UNKNOWN';
+
+/**
+ * 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).
+ */
+export declare class IndexedDBIndex implements IndexedDBIndexInterface {
+    #private;
+    constructor(store: string, name: string, definition: IndexDefinition, connect: () => Promise<IDBDatabase>);
+    get name(): string;
+    get path(): KeyPath;
+    get unique(): boolean;
+    get multiple(): boolean;
+    get(keys: readonly IDBValidKey[]): Promise<readonly (Row | undefined)[]>;
+    get(key: IDBValidKey): Promise<Row | undefined>;
+    resolve(keys: readonly IDBValidKey[]): Promise<readonly Row[]>;
+    resolve(key: IDBValidKey): Promise<Row>;
+    records(query?: IDBKeyRange | IDBValidKey | null, count?: number): Promise<readonly Row[]>;
+    keys(query?: IDBKeyRange | IDBValidKey | null, count?: number): Promise<readonly IDBValidKey[]>;
+    primary(key: IDBValidKey): Promise<IDBValidKey | undefined>;
+    has(keys: readonly IDBValidKey[]): Promise<readonly boolean[]>;
+    has(key: IDBValidKey): Promise<boolean>;
+    count(query?: IDBKeyRange | IDBValidKey | null): Promise<number>;
+    cursor(options?: CursorOptions): Promise<IndexedDBCursorInterface | null>;
+}
+
+/**
+ * A secondary index — read access by an indexed key path.
+ *
+ * @remarks
+ * Indexes are read-only views over a store. `get` / `resolve` fetch the first
+ * record for an index key (`resolve` throws `NOT_FOUND` on a miss); `records` /
+ * `keys` read many (the matching records, and their **primary** keys); `primary`
+ * maps an index key to one primary key; `count` / `has` test presence; `cursor`
+ * streams matches. A read of several keys is the array overload of the same verb
+ * (AGENTS §9.2).
+ */
+export declare interface IndexedDBIndexInterface {
+    readonly name: string;
+    readonly path: KeyPath;
+    readonly unique: boolean;
+    readonly multiple: boolean;
+    get(keys: readonly IDBValidKey[]): Promise<readonly (Row | undefined)[]>;
+    get(key: IDBValidKey): Promise<Row | undefined>;
+    resolve(keys: readonly IDBValidKey[]): Promise<readonly Row[]>;
+    resolve(key: IDBValidKey): Promise<Row>;
+    records(query?: IDBKeyRange | IDBValidKey | null, count?: number): Promise<readonly Row[]>;
+    keys(query?: IDBKeyRange | IDBValidKey | null, count?: number): Promise<readonly IDBValidKey[]>;
+    primary(key: IDBValidKey): Promise<IDBValidKey | undefined>;
+    has(keys: readonly IDBValidKey[]): Promise<readonly boolean[]>;
+    has(key: IDBValidKey): Promise<boolean>;
+    count(query?: IDBKeyRange | IDBValidKey | null): Promise<number>;
+    cursor(options?: CursorOptions): Promise<IndexedDBCursorInterface | null>;
+}
+
+/**
+ * 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.
+ */
+export declare class IndexedDBStore implements IndexedDBStoreInterface {
+    #private;
+    constructor(name: string, definition: StoreDefinition, connect: () => Promise<IDBDatabase>);
+    get name(): string;
+    get path(): KeyPath | null;
+    get indexes(): readonly string[];
+    get increment(): boolean;
+    get(keys: readonly IDBValidKey[]): Promise<readonly (Row | undefined)[]>;
+    get(key: IDBValidKey): Promise<Row | undefined>;
+    resolve(keys: readonly IDBValidKey[]): Promise<readonly Row[]>;
+    resolve(key: IDBValidKey): Promise<Row>;
+    records(query?: IDBKeyRange | IDBValidKey | null, count?: number): Promise<readonly Row[]>;
+    keys(query?: IDBKeyRange | IDBValidKey | null, count?: number): Promise<readonly IDBValidKey[]>;
+    has(keys: readonly IDBValidKey[]): Promise<readonly boolean[]>;
+    has(key: IDBValidKey): Promise<boolean>;
+    count(query?: IDBKeyRange | IDBValidKey | null): Promise<number>;
+    set(values: readonly Row[]): Promise<readonly IDBValidKey[]>;
+    set(value: Row, key?: IDBValidKey): Promise<IDBValidKey>;
+    add(values: readonly Row[]): Promise<readonly IDBValidKey[]>;
+    add(value: Row, key?: IDBValidKey): Promise<IDBValidKey>;
+    remove(keys: readonly IDBValidKey[]): Promise<void>;
+    remove(key: IDBValidKey): Promise<void>;
+    clear(): Promise<void>;
+    index(name: string): IndexedDBIndexInterface;
+    cursor(options?: CursorOptions): Promise<IndexedDBCursorInterface | null>;
+}
+
+/**
+ * An object store — the full keyed CRUD surface, plus index, count, and cursor
+ * access.
+ *
+ * @remarks
+ * Each call runs in its own implicit transaction; for atomic multi-operation work
+ * use the database's `read` / `write`. `get` / `resolve` read by key (`resolve`
+ * throws `NOT_FOUND`); `records` / `keys` read many over an optional key range;
+ * `set` upserts and `add` inserts (throwing `CONSTRAINT` on a duplicate);
+ * `remove` deletes; `clear` empties the store. The keyed verbs batch by their
+ * array overload — listed first, since an array is itself a valid record and a
+ * compound `IDBValidKey`, so the array signature must win (AGENTS §9.2). To act on
+ * a single **compound** key, pass `range.only([…])` to `records` / `count`.
+ */
+export declare interface IndexedDBStoreInterface {
+    readonly name: string;
+    readonly path: KeyPath | null;
+    readonly indexes: readonly string[];
+    readonly increment: boolean;
+    get(keys: readonly IDBValidKey[]): Promise<readonly (Row | undefined)[]>;
+    get(key: IDBValidKey): Promise<Row | undefined>;
+    resolve(keys: readonly IDBValidKey[]): Promise<readonly Row[]>;
+    resolve(key: IDBValidKey): Promise<Row>;
+    records(query?: IDBKeyRange | IDBValidKey | null, count?: number): Promise<readonly Row[]>;
+    keys(query?: IDBKeyRange | IDBValidKey | null, count?: number): Promise<readonly IDBValidKey[]>;
+    has(keys: readonly IDBValidKey[]): Promise<readonly boolean[]>;
+    has(key: IDBValidKey): Promise<boolean>;
+    count(query?: IDBKeyRange | IDBValidKey | null): Promise<number>;
+    set(values: readonly Row[]): Promise<readonly IDBValidKey[]>;
+    set(value: Row, key?: IDBValidKey): Promise<IDBValidKey>;
+    add(values: readonly Row[]): Promise<readonly IDBValidKey[]>;
+    add(value: Row, key?: IDBValidKey): Promise<IDBValidKey>;
+    remove(keys: readonly IDBValidKey[]): Promise<void>;
+    remove(key: IDBValidKey): Promise<void>;
+    clear(): Promise<void>;
+    index(name: string): IndexedDBIndexInterface;
+    cursor(options?: CursorOptions): Promise<IndexedDBCursorInterface | null>;
+}
+
+/**
+ * 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.
+ */
+export declare class IndexedDBTransaction<Stores extends StoresShape = StoresShape> implements IndexedDBTransactionInterface<Stores> {
+    #private;
+    constructor(transaction: IDBTransaction);
+    get transaction(): IDBTransaction;
+    get mode(): IDBTransactionMode;
+    get stores(): readonly string[];
+    get active(): boolean;
+    get finished(): boolean;
+    get error(): DOMException | null;
+    store<K extends keyof Stores & string>(name: K): IndexedDBTransactionStoreInterface;
+    abort(): void;
+    commit(): void;
+}
+
+/**
+ * An explicit transaction over one or more stores.
+ *
+ * @remarks
+ * Obtained through the `scope` callback of the database's `read` / `write`. `store`
+ * reaches a typed, transaction-bound store; the transaction commits automatically
+ * when the scope resolves, or rolls back if it throws or `abort` is called.
+ * `active` is true while it still accepts operations; `finished` is true after
+ * commit or abort.
+ */
+export declare interface IndexedDBTransactionInterface<Stores extends StoresShape = StoresShape> {
+    readonly transaction: IDBTransaction;
+    readonly mode: IDBTransactionMode;
+    readonly stores: readonly string[];
+    readonly active: boolean;
+    readonly finished: boolean;
+    readonly error: DOMException | null;
+    store<K extends keyof Stores & string>(name: K): IndexedDBTransactionStoreInterface;
+    abort(): void;
+    commit(): void;
+}
+
+/**
+ * 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.
+ */
+export declare class IndexedDBTransactionStore implements IndexedDBTransactionStoreInterface {
+    #private;
+    constructor(store: IDBObjectStore);
+    get store(): IDBObjectStore;
+    get(keys: readonly IDBValidKey[]): Promise<readonly (Row | undefined)[]>;
+    get(key: IDBValidKey): Promise<Row | undefined>;
+    resolve(keys: readonly IDBValidKey[]): Promise<readonly Row[]>;
+    resolve(key: IDBValidKey): Promise<Row>;
+    records(query?: IDBKeyRange | IDBValidKey | null, count?: number): Promise<readonly Row[]>;
+    keys(query?: IDBKeyRange | IDBValidKey | null, count?: number): Promise<readonly IDBValidKey[]>;
+    has(keys: readonly IDBValidKey[]): Promise<readonly boolean[]>;
+    has(key: IDBValidKey): Promise<boolean>;
+    count(query?: IDBKeyRange | IDBValidKey | null): Promise<number>;
+    set(values: readonly Row[]): Promise<readonly IDBValidKey[]>;
+    set(value: Row, key?: IDBValidKey): Promise<IDBValidKey>;
+    add(values: readonly Row[]): Promise<readonly IDBValidKey[]>;
+    add(value: Row, key?: IDBValidKey): Promise<IDBValidKey>;
+    remove(keys: readonly IDBValidKey[]): Promise<void>;
+    remove(key: IDBValidKey): Promise<void>;
+    clear(): Promise<void>;
+    cursor(options?: CursorOptions): Promise<IndexedDBCursorInterface | null>;
+}
+
+/**
+ * An object store bound to an explicit transaction.
+ *
+ * @remarks
+ * The same CRUD surface as {@link IndexedDBStoreInterface}, 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 is atomic. It drops `index` and the
+ * standalone implicit-transaction conveniences; reach the live `store` for those.
+ */
+export declare interface IndexedDBTransactionStoreInterface {
+    readonly store: IDBObjectStore;
+    get(keys: readonly IDBValidKey[]): Promise<readonly (Row | undefined)[]>;
+    get(key: IDBValidKey): Promise<Row | undefined>;
+    resolve(keys: readonly IDBValidKey[]): Promise<readonly Row[]>;
+    resolve(key: IDBValidKey): Promise<Row>;
+    records(query?: IDBKeyRange | IDBValidKey | null, count?: number): Promise<readonly Row[]>;
+    keys(query?: IDBKeyRange | IDBValidKey | null, count?: number): Promise<readonly IDBValidKey[]>;
+    has(keys: readonly IDBValidKey[]): Promise<readonly boolean[]>;
+    has(key: IDBValidKey): Promise<boolean>;
+    count(query?: IDBKeyRange | IDBValidKey | null): Promise<number>;
+    set(values: readonly Row[]): Promise<readonly IDBValidKey[]>;
+    set(value: Row, key?: IDBValidKey): Promise<IDBValidKey>;
+    add(values: readonly Row[]): Promise<readonly IDBValidKey[]>;
+    add(value: Row, key?: IDBValidKey): Promise<IDBValidKey>;
+    remove(keys: readonly IDBValidKey[]): Promise<void>;
+    remove(key: IDBValidKey): Promise<void>;
+    clear(): Promise<void>;
+    cursor(options?: CursorOptions): Promise<IndexedDBCursorInterface | null>;
+}
+
+/**
+ * The escape hatch into a version-change upgrade, passed to
+ * `IndexedDBDatabaseOptions.upgrade`.
+ *
+ * @remarks
+ * Runs INSIDE `onupgradeneeded`, after the built-in create-missing-stores pass —
+ * so `stores` already reflects any store just created from the declared schema.
+ * `transaction` is the raw versionchange `IDBTransaction`, the escape hatch for
+ * anything the raw API offers that this wrapper does not model directly; `old` /
+ * `version` are the prior and target database versions (`old` is `0` on first
+ * create); `create` / `drop` add or remove a whole store; `index` / `deindex` add
+ * or remove a secondary index on a store; `store` reaches a transaction-bound
+ * store for data migration. Everything invoked here must stay within the
+ * versionchange transaction — no non-IDB `await`, or it auto-commits and the
+ * upgrade fails.
+ */
+export declare interface IndexedDBUpgradeContext {
+    readonly transaction: IDBTransaction;
+    readonly old: number;
+    readonly version: number;
+    readonly stores: readonly string[];
+    create(name: string, definition: StoreDefinition): void;
+    drop(name: string): void;
+    store(name: string): IndexedDBTransactionStoreInterface;
+    /**
+     * Create a secondary index on `store`.
+     *
+     * @param store - Name of an existing store, or one just created in this same upgrade via `create`.
+     * @param definition - The index to add — {@link IndexDefinition}.
+     * @remarks
+     * Versionchange-only: `store` must already exist within the current upgrade
+     * transaction (either declared in the schema, created earlier in the same
+     * upgrade, or already present from a prior version). Mirrors the index
+     * translation the built-in schema pass applies to a store's declared
+     * `indexes`.
+     * @example
+     * ```ts
+     * upgrade(context) {
+     *   context.index('books', { name: 'byAuthor', path: 'author' })
+     * }
+     * ```
+     */
+    index(store: string, definition: IndexDefinition): void;
+    /**
+     * Remove a named index from `store`.
+     *
+     * @param store - Name of an existing store within the current upgrade transaction.
+     * @param name - The index name to remove.
+     * @remarks
+     * Versionchange-only, same constraint as `index`.
+     * @example
+     * ```ts
+     * upgrade(context) {
+     *   context.deindex('books', 'byAuthor')
+     * }
+     * ```
+     */
+    deindex(store: string, name: string): void;
+}
+
+/**
+ * Whether a value is an {@link IndexedDBError}.
+ *
+ * @param value - The value to test
+ * @returns `true` when `value` is an `IndexedDBError`
+ */
+export declare function isIndexedDBError(value: unknown): value is IndexedDBError;
+
+/**
+ * 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
+ */
+export declare function isIndexedDBSupported(): boolean;
+
+/**
+ * A key path — one field, or several for a compound key.
+ *
+ * @remarks
+ * A single string addresses one field; an array addresses a compound key over
+ * several fields, in order.
+ */
+export declare type KeyPath = string | readonly string[];
+
+/**
+ * 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
+ */
+export declare function promisifyRequest<T>(request: IDBRequest<T>): Promise<T>;
+
+/**
+ * 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
+ */
+export declare function promisifyTransaction(transaction: IDBTransaction): Promise<void>;
+
+/**
+ * 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).
+ */
+export declare const range: {
+    only(value: IDBValidKey): IDBKeyRange;
+    above(value: IDBValidKey): IDBKeyRange;
+    from(value: IDBValidKey): IDBKeyRange;
+    below(value: IDBValidKey): IDBKeyRange;
+    to(value: IDBValidKey): IDBKeyRange;
+    between(lower: IDBValidKey, upper: IDBValidKey, options?: {
+        readonly lowerOpen?: boolean;
+        readonly upperOpen?: boolean;
+    }): IDBKeyRange;
+    prefix(value: string): IDBKeyRange;
+};
+
+/**
+ * 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
+ */
+export declare function readRecord(source: IDBObjectStore | IDBIndex, key: IDBValidKey): Promise<Row | undefined>;
+
+/**
+ * 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
+ */
+export declare function readRecords(source: IDBObjectStore | IDBIndex, query?: IDBKeyRange | IDBValidKey | null, count?: number): Promise<readonly Row[]>;
+
+/**
+ * A record stored in, and read from, an object store.
+ *
+ * @remarks
+ * The value shape every store / index / transaction-store CRUD method reads and
+ * writes. A structured-clone value narrowed with `isRecord` at the read
+ * boundary (see `helpers.ts`), never an unchecked cast.
+ */
+export declare type Row = Record<string, unknown>;
+
+/**
+ * A store's schema.
+ *
+ * @remarks
+ * `path` is the in-line key path (omit it for an **out-of-line** store, where the
+ * key is passed explicitly to `set` / `add`); `increment` auto-generates numeric
+ * keys; `indexes` declares secondary indexes.
+ * Stores are created from these definitions inside `onupgradeneeded`.
+ */
+export declare interface StoreDefinition {
+    readonly path?: KeyPath;
+    readonly increment?: boolean;
+    readonly indexes?: readonly IndexDefinition[];
+}
+
+/** A database's stores — a map of store name to its {@link StoreDefinition}. */
+export declare type StoresShape = Readonly<Record<string, StoreDefinition>>;
+
+/**
+ * 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
+ */
+export declare function wrapError(error: DOMException | null): IndexedDBError;
+
+export { }