@orkestrel/indexeddb 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Orkestrel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+# @orkestrel/indexeddb
+
+A typed, Promise-based wrapper over browser IndexedDB — object stores,
+secondary indexes, native key ranges, promisified cursors, and versioned
+schema upgrades, over `await` instead of raw `IDBRequest` events. Part of the
+`@orkestrel` line.
+
+## Install
+
+```sh
+npm install @orkestrel/indexeddb
+```
+
+## Requirements
+
+- Node.js >= 24 (build/test tooling)
+- ESM-only (no CommonJS build)
+- A browser environment with `IndexedDB` (feature-detect with
+  `isIndexedDBSupported` before opening a database)
+
+## Status
+
+Pre-release. The public API is implemented and tested against a real
+Chromium instance; see the
+[guide](https://github.com/orkestrel/indexeddb/blob/main/guides/src/indexeddb.md)
+for the full surface, patterns, and invariants.
+
+## Package
+
+Published as a single, browser-only ESM entry point per the `exports` field
+in `package.json` — no server or Node-only build.
+
+## License
+
+MIT © [Orkestrel](https://github.com/orkestrel) — see [LICENSE](./LICENSE).

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

@@ -0,0 +1,28 @@
+import type { IndexedDBCursorInterface, Row } from './types.js';
+/**
+ * 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>;
+}

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

@@ -0,0 +1,27 @@
+import type { IndexedDBDatabaseInterface, IndexedDBDatabaseOptions, IndexedDBStoreInterface, IndexedDBTransactionInterface, StoresShape } from './types.js';
+/**
+ * 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>;
+}

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

@@ -0,0 +1,31 @@
+import type { CursorOptions, IndexDefinition, IndexedDBCursorInterface, IndexedDBIndexInterface, KeyPath, Row } from './types.js';
+/**
+ * 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>;
+}

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

@@ -0,0 +1,41 @@
+import type { CursorOptions, IndexedDBCursorInterface, IndexedDBIndexInterface, IndexedDBStoreInterface, KeyPath, Row, StoreDefinition } from './types.js';
+/**
+ * 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>;
+}

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

@@ -0,0 +1,24 @@
+import type { IndexedDBTransactionInterface, IndexedDBTransactionStoreInterface, StoresShape } from './types.js';
+/**
+ * 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;
+}

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

@@ -0,0 +1,34 @@
+import type { CursorOptions, IndexedDBCursorInterface, IndexedDBTransactionStoreInterface, Row } from './types.js';
+/**
+ * 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>;
+}

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

@@ -0,0 +1,10 @@
+import type { IndexedDBErrorCode } from './types.js';
+/**
+ * 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>>;

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

@@ -0,0 +1,30 @@
+import type { IndexedDBErrorCode } from './types.js';
+/**
+ * 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);
+}
+/**
+ * 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;

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

@@ -0,0 +1,30 @@
+import type { IndexedDBDatabaseInterface, IndexedDBDatabaseOptions, StoresShape } from './types.js';
+/**
+ * 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
+ * ```
+ */
+export declare function createIndexedDBDatabase<const Stores extends StoresShape>(options: IndexedDBDatabaseOptions<Stores>): IndexedDBDatabaseInterface<Stores>;

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

@@ -0,0 +1,130 @@
+import type { Row } from './types.js';
+import { IndexedDBError } from './errors.js';
+/**
+ * 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;
+/**
+ * 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>;
+/**
+ * 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;
+/**
+ * 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[]>;
+/**
+ * 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>;
+/**
+ * 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;
+};
+/**
+ * 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;

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

@@ -0,0 +1,11 @@
+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';