@asaidimu/utils-database 3.1.9 → 3.1.10

package/index.d.mts

@@ -1,989 +0,0 @@
-import { QueryFilter, PaginationOptions } from '@asaidimu/query';
-import { IndexDefinition, SchemaChange, DataTransform, PredicateMap, SchemaDefinition } from '@asaidimu/anansi';
-import { StandardSchemaV1 } from '@standard-schema/spec';
-
-/**
- * Buffers write operations across one or more stores and commits them atomically.
- *
- * ## How atomicity works
- *
- * ### IndexedDB stores (same database)
- * At commit time, TransactionContext collects the names of every IDB store that
- * received operations, then opens a **single** `IDBTransaction` spanning all of
- * them via `ConnectionManager.openTransaction`. Each store's `executeInTransaction`
- * receives that shared transaction object and performs its writes against it
- * without opening a new transaction of its own. IDB commits or aborts the
- * entire multi-store transaction as one unit.
- *
- * ### MemoryStore
- * MemoryStore's `executeInTransaction` receives `null` for the shared transaction.
- * It applies ops against an internal staging map and returns. If a later
- * participant fails, TransactionContext calls `rollbackMemory` on each
- * MemoryStore that already applied its staged ops. MemoryStore restores its
- * pre-transaction snapshot.
- *
- * ### Mixed (IDB + Memory in the same transaction)
- * All IDB stores are committed first as a single atomic IDB transaction, then
- * each MemoryStore is committed. If a MemoryStore fails after IDB has already
- * committed, the IDB side cannot be rolled back — this is an inherent limitation
- * of mixing two different storage engines. In practice the schema store is
- * always MemoryStore-or-IDB consistently, so mixed transactions should not arise
- * in normal usage.
- */
-declare class TransactionContext {
-    readonly id: string;
-    /**
-     * Flat list of every operation staged so far, in the order they were added.
-     * We keep the store reference alongside the op so commit() can group them.
-     */
-    private staged;
-    private done;
-    constructor();
-    /**
-     * Stages a single write operation against a store.
-     * Does NOT touch the store — no I/O happens until commit().
-     */
-    addOp<T extends Record<string, any>>(store: Store<T>, type: "put" | "delete" | "add", data: any): Promise<void>;
-    /**
-     * Commits all staged operations atomically.
-     *
-     * For IDB stores: opens one shared IDBTransaction across all participating
-     * stores, then dispatches ops to each store's executeInTransaction.
-     * For MemoryStores: dispatches sequentially; rolls back on failure.
-     */
-    commit(): Promise<void>;
-    /**
-     * Discards all staged operations. No I/O has occurred so there is nothing
-     * to undo — we simply clear the buffer.
-     */
-    rollback(): void;
-    /**
-     * Opens ONE IDBTransaction across all participating IDB stores and lets
-     * each store execute its ops against the shared transaction handle.
-     *
-     * We obtain the IDBDatabase from the first store (they all share the same
-     * ConnectionManager / database) and open the transaction ourselves so that
-     * the commit/abort lifecycle belongs entirely to this method.
-     */
-    private commitIDB;
-    /**
-     * Commits MemoryStore groups sequentially.
-     * Maintains a list of stores that have already applied their ops; if any
-     * store throws, all previously-applied stores are rolled back via the
-     * store-level `_rollbackMemory(snapshot)` escape hatch.
-     */
-    private commitMemory;
-    completed(): boolean;
-}
-
-declare const DEFAULT_KEYPATH = "$id";
-interface CursorPaginationOptions {
-    limit: number;
-    cursor?: any;
-    direction?: "forward" | "backward";
-}
-interface CursorCallbackResult<T> {
-    value: T | null;
-    done: boolean;
-    offset?: number;
-}
-/**
- * Callback function for cursor iteration over store records.
- *
- * @template T - The type of records stored.
- * @param value - The current record value (cloned, not a live reference).
- * @param key - The key (ID) of the current record.
- * @param cursor - The underlying cursor object (implementation-specific; may be `null` in memory adapters).
- * @returns A promise resolving to an object indicating whether iteration should stop,
- *          and an optional offset to advance.
- */
-type CursorCallback<T> = (value: T, key: string | number, cursor: any) => Promise<CursorCallbackResult<T>>;
-/**
- * A generic representation of a key range, replacing the browser-specific IDBKeyRange.
- */
-interface StoreKeyRange {
-    lower?: any;
-    upper?: any;
-    lowerOpen?: boolean;
-    upperOpen?: boolean;
-}
-/**
- * A single buffered operation staged inside a TransactionContext.
- * Kept intentionally minimal — the context only needs to know what to
- * replay against a store during commit.
- */
-type BufferedOperation<T> = {
-    type: "add" | "put";
-    data: T | T[];
-} | {
-    type: "delete";
-    data: string | number | (string | number)[];
-};
-/**
- * Storage adapter interface for a single object store (collection).
- *
- * Stores own their indexes. Index lifecycle (create, drop) and index-aware reads
- * (findByIndex) are part of this contract so that both MemoryStore and IndexedDBStore
- * implement them natively — MemoryStore via in-memory index maps, IndexedDB via its
- * native index mechanism.
- *
- * @template T - The type of objects stored. Must include the key path property.
- */
-interface Store<T extends Record<string, any> = Record<string, any>> {
-    /**
-     * Returns the name of this store (the IDB object store / collection name).
-     * Used by TransactionContext to group operations and open a correctly-scoped
-     * multi-store IDB transaction at commit time.
-     */
-    name(): string;
-    /**
-     * Opens the store, ensuring underlying storage structures exist.
-     */
-    open(): Promise<void>;
-    /**
-     * Adds one or more records to the store.
-     * If a record does not have a value for the store's key path, an automatic
-     * key may be assigned. Throws if a record with the same key already exists.
-     */
-    add(data: T | T[]): Promise<string | number | (string | number)[]>;
-    /**
-     * Removes all records from the store without destroying index structures.
-     */
-    clear(): Promise<void>;
-    /**
-     * Returns the total number of records in the store.
-     */
-    count(): Promise<number>;
-    /**
-     * Deletes one or more records by their keys.
-     */
-    delete(id: string | number | (string | number)[]): Promise<void>;
-    /**
-     * Retrieves a single record by its primary key.
-     */
-    getById(id: string | number): Promise<T | undefined>;
-    /**
-     * Retrieves the first record matching an exact index key (point lookup).
-     * Useful for unique indexes — returns the single matching record or undefined.
-     *
-     * @param indexName - The name of the index to query.
-     * @param key - The exact key value to look up.
-     */
-    getByIndex(indexName: string, key: any): Promise<T | undefined>;
-    /**
-     * Retrieves all records from a named index, optionally filtered by a key range.
-     * Use this for range scans over an index (e.g. all records where age >= 18).
-     *
-     * @param indexName - The name of the index to query.
-     * @param keyRange - Optional range to filter results.
-     */
-    getByKeyRange(indexName: string, keyRange?: StoreKeyRange): Promise<T[]>;
-    /**
-     * Retrieves all records from the store without index involvement.
-     */
-    getAll(): Promise<T[]>;
-    /**
-     * Inserts or replaces a record. Validates OCC if a record with the same key exists.
-     */
-    put(data: T): Promise<string | number>;
-    /**
-     * Iterates over records using a cursor, allowing early termination and skipping.
-     *
-     * @param callback - Invoked for each record; return `{ done: true }` to stop,
-     *                   `{ offset: n }` to skip ahead n records.
-     * @param direction - Iteration order.
-     * @param keyRange - Optional range to restrict iteration.
-     */
-    cursor(callback: CursorCallback<T>, direction?: "forward" | "backward", keyRange?: StoreKeyRange): Promise<T | null>;
-    /**
-     * Executes a batch of write operations atomically within this store.
-     * All operations succeed or fail together.
-     *
-     * Used for standalone (single-store) atomic writes. For cross-store atomicity,
-     * use executeInTransaction instead.
-     */
-    batch(operations: Array<{
-        type: "add" | "put";
-        data: T | T[];
-    } | {
-        type: "delete";
-        data: string | number | (string | number)[];
-    }>): Promise<void>;
-    /**
-     * Registers a new index on the store. Idempotent — no-op if the index already exists.
-     * For IndexedDB, this triggers a database version upgrade.
-     * For MemoryStore, this builds the index map from existing records.
-     *
-     * @param definition - The full index definition from the schema.
-     */
-    createIndex(definition: IndexDefinition): Promise<void>;
-    /**
-     * Removes a named index from the store.
-     * For IndexedDB, this triggers a database version upgrade.
-     * For MemoryStore, this drops the in-memory index map.
-     *
-     * @param name - The index name as declared in IndexDefinition.name.
-     */
-    dropIndex(name: string): Promise<void>;
-    /**
-     * Returns all records matching an exact index key.
-     * Unlike getByIndex (which returns only the first match), this returns all matches —
-     * essential for non-unique indexes where multiple records share the same indexed value.
-     *
-     * @param indexName - The name of the index to query.
-     * @param value - The exact value to look up.
-     */
-    findByIndex(indexName: string, value: any): Promise<T[]>;
-    /**
-     * Executes a set of buffered operations as part of a cross-store atomic transaction.
-     *
-     * For IndexedDBStore: `sharedTx` is the single IDBTransaction opened across all
-     * participating stores. Operations are applied directly to `sharedTx.objectStore(name)`
-     * without opening a new transaction — IDB commits or aborts the whole thing atomically.
-     *
-     * For MemoryStore: `sharedTx` is null. The store applies ops against its own staging
-     * area. The caller (TransactionContext) is responsible for coordinating rollback across
-     * all MemoryStores if any participant fails.
-     *
-     * This method must NOT open, commit, or abort any transaction itself.
-     *
-     * @param ops - The buffered operations to apply.
-     * @param sharedTx - The shared IDBTransaction (IndexedDB only), or null (MemoryStore).
-     */
-    executeInTransaction(ops: BufferedOperation<T>[], sharedTx: IDBTransaction | null): Promise<void>;
-}
-interface Collection<T> {
-    /**
-     * Finds a single document matching the query.
-     */
-    find: (query: QueryFilter<T>) => Promise<Document<T> | null>;
-    /**
-     * Lists documents with pagination. Returns an AsyncIterator so consumers can
-     * wrap it in their own iteration protocol (e.g. for-await-of via AsyncIterable).
-     */
-    list: (query: PaginationOptions) => Promise<AsyncIterator<Document<T>[]>>;
-    /**
-     * Filters all documents matching the query.
-     */
-    filter: (query: QueryFilter<T>) => Promise<Document<T>[]>;
-    /**
-     * Creates a new document in the collection.
-     *
-     * When a TransactionContext is provided the initial store.add is buffered into
-     * the transaction rather than written immediately. The document is returned in
-     * its fully initialised in-memory state regardless — callers can use it before
-     * the transaction commits.
-     *
-     * @param initial - The initial data for the document.
-     * @param tx - Optional transaction to buffer the write into.
-     */
-    create: (initial: T, tx?: TransactionContext) => Promise<Document<T>>;
-    /**
-     * Updates all documents matching the query with the provided partial data.
-     * Returns the number of documents updated.
-     */
-    update: (query: QueryFilter<T>, data: Partial<T>, tx?: TransactionContext) => Promise<number>;
-    /**
-     * Deletes all documents matching the query.
-     * Returns the number of documents deleted.
-     */
-    delete: (query: QueryFilter<T>, tx?: TransactionContext) => Promise<number>;
-    /**
-     * Subscribes to collection-level events.
-     */
-    subscribe: (event: CollectionEventType | TelemetryEventType, callback: (event: CollectionEvent<T> | TelemetryEvent) => void) => () => void;
-    /**
-     * Validates data against the collection's schema.
-     */
-    validate(data: Record<string, any>): Promise<{
-        value?: any;
-        issues: Array<{
-            message: string;
-            path: Array<string>;
-        }>;
-    }>;
-    invalidate(): void;
-}
-/**
- * Event payload for Collection events.
- */
-type CollectionEventType = "document:create" | "collection:read" | "migration:start" | "migration:end";
-type CollectionEvent<T> = {
-    type: CollectionEventType;
-    document?: T;
-    model?: string;
-    method?: keyof Collection<T>;
-    metadata?: Record<string, unknown>;
-    timestamp: number;
-};
-interface Database {
-    /**
-     * Opens an existing collection by name.
-     */
-    collection: <T>(schemaName: string) => Promise<Collection<T>>;
-    /**
-     * Creates a new collection from a schema definition.
-     */
-    createCollection: <T>(schema: SchemaDefinition) => Promise<Collection<T>>;
-    /**
-     * Deletes a collection and its schema record.
-     */
-    deleteCollection: (schemaName: string) => Promise<boolean>;
-    /**
-     * Updates an existing collection's schema record.
-     */
-    updateCollection: (schema: SchemaDefinition) => Promise<boolean>;
-    /**
-     * Migrates an existing collection's data and schema definition.
-     * Processes data in a streaming fashion to avoid loading the full collection
-     * into memory.
-     */
-    migrateCollection: <T>(name: string, opts: CollectionMigrationOptions, batchSize?: number) => Promise<Collection<T>>;
-    /**
-     * Executes a callback within a TransactionContext.
-     * Writes buffered inside the callback are flushed atomically on commit.
-     * If the callback throws, the buffer is discarded (no writes are flushed).
-     */
-    transaction: (callback: (tx: TransactionContext) => Promise<void>) => Promise<void>;
-    /**
-     * Subscribes to database-level events.
-     */
-    subscribe: (event: DatabaseEventType | "telemetry", callback: (event: DatabaseEvent | TelemetryEvent) => void) => () => void;
-    /**
-     * Releases in-memory references and event bus subscriptions.
-     * Does not delete any persisted data.
-     */
-    close: () => void;
-    clear: () => Promise<void>;
-    /**
-     * Ensures a collection exists; creates it if it doesn't. Idempotent.
-     */
-    ensureCollection: (schema: SchemaDefinition) => Promise<void>;
-    /**
-     * Ensures multiple collections exist; creates any that don't. Idempotent.
-     */
-    setupCollections: (schemas: SchemaDefinition[]) => Promise<void>;
-}
-type CollectionMigrationOptions = {
-    changes: SchemaChange<any>[];
-    description: string;
-    rollback?: SchemaChange<any>[];
-    transform?: string | DataTransform<any, any>;
-};
-type DatabaseEventType = "collection:create" | "collection:delete" | "collection:update" | "collection:read" | "migrate";
-type DatabaseEvent = {
-    type: DatabaseEventType;
-    schema?: SchemaDefinition | Partial<SchemaDefinition>;
-    timestamp: number;
-};
-type DocumentMetadata = {
-    $id?: string;
-    $created?: string | Date;
-    $updated?: string | Date;
-    $version?: number;
-};
-type Document<T> = {
-    readonly [K in keyof T]: T[K];
-} & DocumentMetadata & {
-    read: () => Promise<T>;
-    save: (tx?: TransactionContext) => Promise<boolean>;
-    update: (props: Partial<T>, tx?: TransactionContext) => Promise<boolean>;
-    delete: (tx?: TransactionContext) => Promise<boolean>;
-    subscribe: (event: DocumentEventType | TelemetryEventType, callback: (event: DocumentEvent<T> | TelemetryEvent) => void) => () => void;
-    state(): T;
-    $metadata(): DocumentMetadata;
-};
-type DocumentEventType = "document:create" | "document:write" | "document:update" | "document:delete" | "document:read";
-type DocumentEvent<T> = {
-    type: DocumentEventType;
-    data?: Partial<T>;
-    timestamp: number;
-};
-type TelemetryEventType = "telemetry";
-type TelemetryEvent = {
-    type: TelemetryEventType;
-    method: string;
-    timestamp: number;
-    source: any;
-    metadata: {
-        args: any[];
-        performance: {
-            durationMs: number;
-        };
-        source: {
-            level: "database" | "collection" | "document";
-            collection?: string;
-            document?: string;
-        };
-        result?: {
-            type: "array" | string;
-            size?: number;
-        };
-        error: {
-            message: string;
-            name: string;
-            stack?: string;
-        } | null;
-    };
-};
-interface DatabaseConfig {
-    database: string;
-    keyPath?: string;
-    schemasStoreName?: string;
-    enableTelemetry?: boolean;
-    predicates?: PredicateMap;
-    validate?: boolean;
-}
-type StoreConfig = DatabaseConfig & {
-    collection: string;
-};
-
-/**
- * Internal structure for a single maintained index.
- */
-interface IndexEntry {
-    definition: IndexDefinition;
-    /** Maps a composite/single index key → set of record primary keys ($id) */
-    map: Map<string, Set<string | number>>;
-}
-/**
- * Snapshot of the store's mutable state, used for cross-store transaction rollback.
- */
-interface MemoryStoreSnapshot {
-    data: Map<string | number, Readonly<Record<string, any>>>;
-    indexes: Map<string, IndexEntry>;
-    nextId: number;
-}
-declare class MemoryStore<T extends Record<string, any>> implements Store<T> {
-    private readonly storeName;
-    private readonly keyPath;
-    private data;
-    private indexes;
-    private nextId;
-    /**
-     * @param storeName - The logical name of this store (matches the collection name).
-     * @param keyPath - The primary key field name (default: "$id").
-     * @param indexDefs - Index definitions from the schema. The store will maintain
-     *                    these indexes on every write operation.
-     */
-    constructor(storeName: string, keyPath?: string, indexDefs?: IndexDefinition[]);
-    name(): string;
-    open(): Promise<void>;
-    /**
-     * Returns a deep snapshot of the store's mutable state.
-     * Called by TransactionContext immediately before executeInTransaction so
-     * that if a later store in the same transaction fails, this store can be
-     * fully restored via _rollbackMemory.
-     *
-     * Prefixed with underscore to signal it is an internal contract between
-     * MemoryStore and TransactionContext — not part of the public Store API.
-     */
-    _snapshotMemory(): MemoryStoreSnapshot;
-    /**
-     * Restores the store to a previously snapshotted state.
-     * Called by TransactionContext when a later participant in the same
-     * cross-store transaction fails, requiring all already-applied stores to
-     * be unwound.
-     */
-    _rollbackMemory(snapshot: MemoryStoreSnapshot): void;
-    /**
-     * Registers a new index. Idempotent — no-op if the name already exists.
-     * Immediately indexes all existing records so the index is consistent.
-     */
-    createIndex(definition: IndexDefinition): Promise<void>;
-    /**
-     * Removes a named index. No-op if the index does not exist.
-     */
-    dropIndex(name: string): Promise<void>;
-    /**
-     * Returns the first record whose indexed value exactly matches `value`.
-     * Intended for unique indexes — for non-unique indexes use findByIndex.
-     */
-    getByIndex(indexName: string, value: any): Promise<T | undefined>;
-    /**
-     * Returns all records whose indexed value exactly matches `value`.
-     * O(k) where k is the result set size — avoids a full table scan.
-     */
-    findByIndex(indexName: string, value: any): Promise<T[]>;
-    /**
-     * Returns all records from a named index within an optional key range.
-     */
-    getByKeyRange(indexName: string, keyRange?: StoreKeyRange): Promise<T[]>;
-    add(data: T | T[]): Promise<string | number | (string | number)[]>;
-    put(data: T): Promise<string | number>;
-    batch(operations: Array<{
-        type: "add" | "put";
-        data: T | T[];
-    } | {
-        type: "delete";
-        data: string | number | (string | number)[];
-    }>): Promise<void>;
-    delete(id: string | number | (string | number)[]): Promise<void>;
-    clear(): Promise<void>;
-    /**
-     * Applies buffered ops directly to the live data and index maps.
-     *
-     * `sharedTx` is always null for MemoryStore — there is no shared transaction
-     * object. Atomicity across multiple MemoryStores is managed by the caller
-     * (TransactionContext), which takes a snapshot via _snapshotMemory() before
-     * calling this method and calls _rollbackMemory(snapshot) if a later store
-     * in the same transaction fails.
-     *
-     * This method applies ops eagerly (no staging) because the snapshot already
-     * guards against partial failure at the cross-store level.
-     */
-    executeInTransaction(ops: BufferedOperation<T>[], sharedTx: IDBTransaction | null): Promise<void>;
-    getById(id: string | number): Promise<T | undefined>;
-    getAll(): Promise<T[]>;
-    count(): Promise<number>;
-    cursor(callback: CursorCallback<T>, direction?: "forward" | "backward", keyRange?: StoreKeyRange): Promise<T | null>;
-    private getKey;
-    private clone;
-    /**
-     * Adds a document to all index maps. Skips indexes where the document
-     * does not satisfy partial conditions or is missing indexed fields.
-     */
-    private indexDocument;
-    private indexOne;
-    /**
-     * Removes a document from all index maps.
-     */
-    private unindexDocument;
-    /**
-     * Enforces unique index constraints before a write.
-     * Throws CONFLICT if another record (other than `existing`) already holds the
-     * same indexed value for any unique index.
-     *
-     * @param incoming - The record about to be written.
-     * @param existing - The record currently stored at this key (undefined for new records).
-     */
-    private enforceUniqueIndexes;
-    private isInKeyRange;
-}
-
-declare function createEphemeralStore<T extends Record<string, any>>(config: DatabaseConfig): MemoryStore<T>;
-
-/**
- * Manages the lifecycle and state of an IndexedDB connection, ensuring
- * schema stores and collections are created and upgraded safely.
- */
-declare class ConnectionManager {
-    private readonly config;
-    private connectionInitializer;
-    private readonly schemasStoreName;
-    constructor(config: DatabaseConfig);
-    private openDatabase;
-    /**
-     * Bumps the database version and runs the provided upgrade callback.
-     * The callback receives both the IDBDatabase and the active IDBTransaction
-     * so callers can access existing object stores via tx.objectStore(name).
-     *
-     * Note: IDB only allows structural changes (createObjectStore, createIndex,
-     * deleteIndex) inside an onupgradeneeded handler. This method is the single
-     * entry point for all such changes.
-     */
-    private upgradeDatabase;
-    /**
-     * Ensures a collection object store exists, creating it (and its indexes) if absent.
-     * Triggers an upgrade only when the store does not yet exist; if it already exists,
-     * this is a fast no-op.
-     *
-     * @param collection - Name of the IDB object store.
-     * @param keyPath - Primary key field (default: "$id").
-     * @param indexes - Index definitions to create alongside the store.
-     *                  These are only applied during the initial store creation.
-     *                  Use createStoreIndex / dropStoreIndex for post-creation changes.
-     */
-    ensureStore(collection: string, keyPath?: string, indexes?: IndexDefinition[]): Promise<void>;
-    /**
-     * Adds a named index to an existing object store.
-     * Triggers a database version upgrade.
-     *
-     * @param collection - The object store to add the index to.
-     * @param definition - The index definition.
-     */
-    createStoreIndex(collection: string, definition: IndexDefinition): Promise<void>;
-    /**
-     * Removes a named index from an existing object store.
-     * Triggers a database version upgrade.
-     *
-     * @param storeName - The object store to remove the index from.
-     * @param indexName - The name of the index to remove.
-     */
-    dropStoreIndex(storeName: string, indexName: string): Promise<void>;
-    /**
-     * Retrieves or opens the active database connection.
-     */
-    getConnection: () => Promise<IDBDatabase>;
-    /**
-     * Opens a readwrite IDBTransaction spanning the given store names.
-     *
-     * This is the entry point for all cross-store atomic writes. The returned
-     * transaction is NOT managed here — the caller (TransactionContext) owns the
-     * commit/abort lifecycle by wiring oncomplete / onerror / onabort handlers.
-     *
-     * All named stores must already exist (i.e. ensureStore must have been called
-     * for each before this point). Requesting a store that doesn't exist will cause
-     * IDB to throw a DOMException synchronously when the transaction is opened.
-     *
-     * @param storeNames - Object store names to include in the transaction.
-     * @param mode - IDB transaction mode (default: "readwrite").
-     */
-    openTransaction(storeNames: string[], mode?: IDBTransactionMode): Promise<IDBTransaction>;
-    /**
-     * Performs a version upgrade. Resets the internal initialiser so concurrent
-     * callers wait for the upgraded connection rather than using the stale one.
-     *
-     * The callback receives both `db` (for creating new stores) and `tx`
-     * (for accessing existing stores to add/remove indexes).
-     */
-    upgrade(upgradeLogic: (db: IDBDatabase, tx: IDBTransaction) => void): Promise<IDBDatabase>;
-    /**
-     * Closes the active connection and resets the initialiser.
-     * Does not delete any persisted data.
-     */
-    close(): void;
-}
-
-declare class IndexedDBStore<T extends Record<string, any>> implements Store<T> {
-    private readonly connectionManager;
-    private readonly collection;
-    private readonly keyPath;
-    private readonly indexes;
-    constructor(connectionManager: ConnectionManager, collection: string, keyPath?: string, indexes?: IndexDefinition[]);
-    name(): string;
-    /**
-     * Internal escape hatch used by TransactionContext to obtain the shared
-     * IDBDatabase so it can open a single multi-store IDBTransaction.
-     *
-     * Prefixed with underscore to signal that nothing outside of
-     * TransactionContext should call this directly.
-     */
-    _getIDBConnection(): Promise<IDBDatabase>;
-    /**
-     * Ensures the underlying IDB object store (and its declared indexes) exist.
-     * Safe to call multiple times — no-op if the store is already present.
-     */
-    open(): Promise<void>;
-    /**
-     * Adds a new index to the IDB object store. Triggers a database version upgrade.
-     * Idempotent — no-op if the index already exists.
-     */
-    createIndex(definition: IndexDefinition): Promise<void>;
-    /**
-     * Removes a named index from the IDB object store. Triggers a version upgrade.
-     * No-op if the index does not exist.
-     */
-    dropIndex(name: string): Promise<void>;
-    /**
-     * Returns the first record matching an exact index key.
-     * Use for unique index point lookups.
-     */
-    getByIndex(indexName: string, key: any): Promise<T | undefined>;
-    /**
-     * Returns all records from a named index within an optional key range.
-     */
-    getByKeyRange(indexName: string, keyRange?: StoreKeyRange): Promise<T[]>;
-    /**
-     * Returns all records whose indexed value exactly matches `value`.
-     * Unlike getByIndex, this uses index.getAll(IDBKeyRange.only(value)) so it
-     * correctly returns multiple records for non-unique indexes.
-     */
-    findByIndex(indexName: string, value: any): Promise<T[]>;
-    put(data: T): Promise<string | number>;
-    add(data: T | T[]): Promise<string | number | (string | number)[]>;
-    batch(operations: Array<{
-        type: "add" | "put";
-        data: T | T[];
-    } | {
-        type: "delete";
-        data: string | number | (string | number)[];
-    }>): Promise<void>;
-    delete(id: string | number | (string | number)[]): Promise<void>;
-    clear(): Promise<void>;
-    /**
-     * Executes buffered ops against a shared IDBTransaction opened by
-     * TransactionContext. This method MUST NOT open, commit, or abort a
-     * transaction — the caller owns the transaction lifecycle entirely.
-     *
-     * @param ops - Operations to apply.
-     * @param sharedTx - The IDBTransaction shared across all participating stores.
-     *                   Never null for IndexedDBStore.
-     */
-    executeInTransaction(ops: BufferedOperation<T>[], sharedTx: IDBTransaction | null): Promise<void>;
-    getById(id: string | number): Promise<T | undefined>;
-    getAll(): Promise<T[]>;
-    count(): Promise<number>;
-    cursor(callback: CursorCallback<T>, direction?: "forward" | "backward", keyRange?: StoreKeyRange): Promise<T | null>;
-    private mapError;
-    /**
-     * Opens a fresh single-store IDB transaction for standalone (non-atomic)
-     * operations. Not used by executeInTransaction — that receives an externally
-     * managed shared transaction.
-     */
-    private withTx;
-    private requestToPromise;
-}
-
-/**
- * Retrieves or creates an IndexedDB store instance.
- * * This function utilizes a synchronous execution path to retrieve the
- * ConnectionManager. If the connection is currently being initialized
- * asynchronously, or if the lock is contended, it throws a DatabaseError.
- *
- * @template T - The schema type for the collection.
- * @param config - The database and collection configuration.
- * @returns A functional Store instance.
- * @throws {DatabaseError} CONNECTION_FAILED if the manager is busy or fails to init.
- */
-declare const createIndexedDbStore: <T extends Record<string, any>>(config: StoreConfig) => Store<T>;
-
-type StoreFactory = <T extends Record<string, any>>(config: StoreConfig, indexes: IndexDefinition[]) => Store<T>;
-declare function DatabaseConnection(config: Omit<DatabaseConfig, "keyPath">, createStore: StoreFactory): Promise<Database>;
-
-interface MutexOptions {
-    /**
-     * Maximum number of pending requests allowed in the queue.
-     * If exceeded, tryLock/lock will fail.
-     * @default Infinity
-     */
-    capacity?: number;
-    /**
-     * Controls how lock handoff is scheduled when a waiter is unblocked.
-     *
-     * - `"macrotask"` (default): Uses setTimeout(fn, 0) to yield to the event
-     *   loop between handoffs. Prevents microtask starvation under heavy
-     *   contention — I/O, rendering, and other macrotasks can run between
-     *   lock acquisitions. Use for Serializer and other coarse-grained
-     *   serializers.
-     *
-     * - `"microtask"`: Uses queueMicrotask(fn) for handoff. Near-zero latency
-     *   between acquisitions — no macrotask delay. Safe when you need
-     *   back-to-back operations to complete as fast as possible and starvation
-     *   is not a concern (e.g. Once, Semaphore where builds are infrequent
-     *   and latency matters more than fairness).
-     */
-    yieldMode?: "macrotask" | "microtask";
-}
-/**
- * A mutual exclusion lock.
- * Allows only one execution context to access a resource at a time.
- *
- * Yield mode is configurable per instance:
- * - "macrotask" (default): yields between handoffs, preventing microtask starvation.
- * - "microtask": zero-delay handoff for latency-sensitive paths.
- */
-declare class Mutex {
-    private _locked;
-    private _capacity;
-    private _yieldMode;
-    private waiters;
-    constructor(options?: MutexOptions);
-    /**
-     * Acquires the lock. If already held, waits until released or timeout reached.
-     *
-     * @param timeout - Optional maximum wait time in milliseconds.
-     * @throws {TimeoutError} If the lock cannot be acquired within the timeout.
-     * @throws {Error} If the wait queue is full (backpressure).
-     */
-    lock(timeout?: number): Promise<void>;
-    /**
-     * Attempts to acquire the lock without waiting.
-     * @returns `true` if the lock was acquired, `false` otherwise.
-     */
-    tryLock(): boolean;
-    /**
-     * Releases the lock, scheduling the next waiter according to yieldMode.
-     *
-     * When a waiter exists, `_locked` intentionally remains `true` — ownership
-     * transfers directly to the next waiter without ever clearing the flag.
-     * Only when the queue is empty is `_locked` set to false.
-     *
-     * @throws {Error} If the mutex is not currently locked.
-     */
-    unlock(): void;
-    /** Returns true if the mutex is currently locked. */
-    locked(): boolean;
-    /** Returns the number of operations waiting for the lock. */
-    pending(): number;
-}
-
-/**
- * Interface defining the shape of the EventBus.
- * @template TEventMap - A record mapping event names to their respective payload types.
- */
-interface EventBus<TEventMap extends Record<string, any>> {
-    /**
-     * Subscribes to a specific event by name.
-     * @param eventName - The name of the event to subscribe to.
-     * @param callback - The function to call when the event is emitted.
-     * @param options -  Extra options to determine the behaviour of the
-     * subscription
-     * @returns A function to unsubscribe from the event.
-     */
-    subscribe<TEventName extends keyof TEventMap | "*">(eventName: TEventName, callback: TEventName extends "*" ? (payload: TEventMap[keyof TEventMap], event: keyof TEventMap) => void : (payload: TEventMap[TEventName]) => void, options?: SubscribeOptions): () => void;
-    /**
-     * Subscribes to an event and automatically unsubscribes after it fires once.
-     * @param eventName - The name of the event to subscribe to.
-     * @param callback - The function to call when the event is emitted.
-     * @returns A function to cancel the one-shot subscription before it fires.
-     */
-    once<TEventName extends keyof TEventMap | "*">(eventName: TEventName, callback: TEventName extends "*" ? (payload: TEventMap[keyof TEventMap], event: keyof TEventMap) => void : (payload: TEventMap[TEventName]) => void, options?: SubscribeOptions): () => void;
-    /**
-     * Emits an event with a payload to all subscribed listeners.
-     * @param event - An object containing the event name and payload.
-     */
-    emit: <TEventName extends keyof TEventMap>(event: {
-        name: TEventName;
-        payload: TEventMap[TEventName];
-    }) => void;
-    /**
-     * Retrieves metrics about event bus usage.
-     * @returns An object containing various metrics.
-     */
-    metrics: () => EventMetrics;
-    /**
-     * Clears all subscriptions and resets metrics.
-     *
-     * After calling `clear()`, the bus is fully reset and can be reused
-     * cross-tab communication is re-established if it was previously enabled.
-     *
-     * @param options - Optional configuration object.
-     * @param options.permanent - If `true`, the bus becomes permanently unusable after clearing.
-     *                            Defaults to `false`.
-     * @returns {void}
-     */
-    clear: (options?: {
-        permanent?: boolean;
-    }) => void;
-}
-/**
- * Interface defining the metrics tracked by the EventBus.
- */
-interface EventMetrics {
-    /** Total number of events emitted (both sync and deferred paths). */
-    totalEvents: number;
-    /** Number of active subscriptions across all event names. */
-    activeSubscriptions: number;
-    /** Map of event names to their emission counts. */
-    eventCounts: Map<string, number>;
-    /** Average duration of event dispatch in milliseconds. */
-    averageEmitDuration: number;
-}
-interface SubscribeOptions {
-    /**
-     * Debounce delay in milliseconds. When multiple events arrive in quick
-     * succession, the callback runs only after the quiet period ends, using the
-     * latest payload. Default = no debouncing.
-     */
-    debounce?: number;
-}
-
-interface MiddlewareContext {
-    collection?: string;
-    documentId?: string;
-    operation: string;
-    args: any[];
-    eventBus?: EventBus<any>;
-}
-type MaybePromise<T> = T | Promise<T>;
-type MiddlewareNext = () => MaybePromise<any>;
-type Middleware = (ctx: MiddlewareContext, next: MiddlewareNext) => MaybePromise<any>;
-declare class Pipeline {
-    private middlewares;
-    use(middleware: Middleware): void;
-    execute(ctx: MiddlewareContext, finalOperation: () => MaybePromise<any>): MaybePromise<any>;
-    wrap<T extends object>(target: T, baseContext: Partial<MiddlewareContext>): T;
-}
-
-interface DocumentOptions<T extends Record<string, any>> {
-    /**
-     * The already-persisted initial state of the document.
-     * createDocument does NOT call store.add — the caller is responsible
-     * for having written this record before constructing the document proxy.
-     */
-    initial: Partial<T>;
-    collection: string;
-    schema: SchemaDefinition;
-    validator?: StandardSchemaV1;
-    store: Store<T>;
-    bus: EventBus<Record<DocumentEventType | TelemetryEventType, DocumentEvent<T> | TelemetryEvent>>;
-    pipeline: Pipeline;
-    lockManager: Mutex;
-}
-/**
- * Constructs an in-memory Document proxy around an already-persisted record.
- *
- * Responsibility split:
- *   - createDocument: validates, initialises in-memory state, wires operations. NO I/O.
- *   - openCollection.create: owns the initial store.add (or tx.addOp for transactional creates).
- *
- * This separation ensures that transactional creates are correctly buffered:
- * the document object is available immediately in-memory, while the actual
- * store write is deferred until transaction commit.
- */
-declare function createDocument<T extends Record<string, any>>(opts: DocumentOptions<T>): Promise<Document<T & {
-    $id: string | number;
-}>>;
-declare function openCollection<T extends Record<string, any>>({ collection: schemaName, validator, bus, store, pipeline, validate, schema: schemaDefinition, }: {
-    store: Store<T>;
-    collection: string;
-    validator: StandardSchemaV1;
-    bus: EventBus<any>;
-    pipeline: Pipeline;
-    validate: boolean;
-    schema: SchemaDefinition;
-}): Promise<Collection<T>>;
-
-/**
- * Error types for Database operations.
- */
-declare enum DatabaseErrorType {
-    /** The schema does not exist. */
-    SCHEMA_NOT_FOUND = "SCHEMA_NOT_FOUND",
-    /** The schema already exists. */
-    SCHEMA_ALREADY_EXISTS = "SCHEMA_ALREADY_EXISTS",
-    /** The schema name is invalid. */
-    INVALID_SCHEMA_NAME = "INVALID_SCHEMA_NAME",
-    /** The schema definition is invalid. */
-    INVALID_SCHEMA_DEFINITION = "INVALID_SCHEMA_DEFINITION",
-    /** The database subscription failed. */
-    SUBSCRIPTION_FAILED = "SUBSCRIPTION_FAILED",
-    /** The database operation failed due to an internal error. */
-    INTERNAL_ERROR = "INTERNAL_ERROR",
-    /** Data being entered into a collection does not satisfy its schema definition. */
-    INVALID_DATA = "INVALID_DATA",
-    /** Optimistic Concurrency Control version mismatches */
-    CONFLICT = "CONFLICT",
-    /** For retryable store locks */
-    TRANSIENT_ERROR = "TRANSIENT_ERROR",
-    TRANSACTION_FAILED = "TRANSACTION_FAILED",
-    CONNECTION_FAILED = "CONNECTION_FAILED",
-    INVALID_OPERATION = "INVALID_OPERATION"
-}
-/**
- * Error class for Database operations.
- */
-declare class DatabaseError extends Error {
-    /**
-     * The type of error that occurred.
-     */
-    type: DatabaseErrorType;
-    /**
-     * The schema associated with the error, if applicable.
-     */
-    schema?: SchemaDefinition;
-    /**
-     * Issues associated with the error
-     */
-    issues?: any[];
-    /**
-     * Constructs a new DatabaseErrorClass instance.
-     * @param type - The type of error that occurred.
-     * @param message - A human-readable message describing the error.
-     * @param schema - The schema associated with the error, if applicable.
-     */
-    constructor(type: DatabaseErrorType, message: string, schema?: SchemaDefinition, cause?: unknown, issues?: any);
-}
-
-export { type BufferedOperation, type Collection, type CollectionEvent, type CollectionEventType, type CollectionMigrationOptions, ConnectionManager, type CursorCallback, type CursorCallbackResult, type CursorPaginationOptions, DEFAULT_KEYPATH, type Database, type DatabaseConfig, DatabaseConnection, DatabaseError, DatabaseErrorType, type DatabaseEvent, type DatabaseEventType, type Document, type DocumentEvent, type DocumentEventType, type DocumentMetadata, IndexedDBStore, type Store, type StoreConfig, type StoreFactory, type StoreKeyRange, type TelemetryEvent, type TelemetryEventType, createDocument, createEphemeralStore, createIndexedDbStore, openCollection };