@asaidimu/utils-database 1.1.0 → 2.0.0

package/index.d.mts

@@ -1,16 +1,79 @@
 import { QueryFilter, PaginationOptions } from '@asaidimu/query';
-import { SchemaDefinition, SchemaChange, DataTransform, PredicateMap } from '@asaidimu/anansi';
-import { EventBus } from '@asaidimu/events';
+import { IndexDefinition, SchemaDefinition, SchemaChange, DataTransform, PredicateMap } 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;
-    private buffer;
-    private committed;
+    /**
+     * 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();
-    addOp(store: Store<any>, type: "put" | "delete", data: any): void;
+    /**
+     * 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";
@@ -30,8 +93,9 @@ interface CursorCallbackResult<T> {
  * @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 that resolves to an object indicating whether iteration should stop, and an optional offset to advance.
+ * @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>>;
 /**
@@ -43,123 +107,100 @@ interface StoreKeyRange {
     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).
  *
- * This interface abstracts all low‑level persistence operations, allowing
- * different backends (IndexedDB, memory, remote, etc.) to be used interchangeably.
- * All methods return promises and operate on clones of data to prevent
- * unintended mutations.
+ * 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 in this store. Must include the key path property.
+ * @template T - The type of objects stored. Must include the key path property.
  */
-interface Store<T = any> {
+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 (e.g., auto‑incremented number) may be assigned. The store's key path
-     * property is then updated on the added record(s).
-     *
-     * @param data - A single record or an array of records to add.
-     * @returns A promise that resolves to:
-     *   - the key(s) of the added record(s) – a single key if `data` was a single record,
-     *     or an array of keys if `data` was an array.
-     * @throws {Error} If any record lacks the key path property and auto‑keying is not supported,
-     *                 or if a record with the same key already exists.
+     * 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.
-     *
-     * @returns A promise that resolves when the store is cleared.
-     * @throws {Error} If the operation fails (e.g., store is closed).
+     * Removes all records from the store without destroying index structures.
      */
     clear(): Promise<void>;
     /**
      * Returns the total number of records in the store.
-     *
-     * @returns A promise that resolves to the record count.
-     * @throws {Error} If the operation fails.
      */
     count(): Promise<number>;
     /**
      * Deletes one or more records by their keys.
-     *
-     * @param id - A single key or an array of keys to delete.
-     * @returns A promise that resolves when the records are deleted.
-     * @throws {Error} If any key is `undefined` or the operation fails.
      */
     delete(id: string | number | (string | number)[]): Promise<void>;
     /**
      * Retrieves a single record by its primary key.
-     *
-     * @param id - The key of the record to retrieve.
-     * @returns A promise that resolves to the record (cloned) if found, otherwise `undefined`.
-     * @throws {Error} If the key is `undefined` or the operation fails.
      */
     getById(id: string | number): Promise<T | undefined>;
     /**
-     * Retrieves a single record by an index and index key.
+     * Retrieves the first record matching an exact index key (point lookup).
+     * Useful for unique indexes — returns the single matching record or undefined.
      *
-     * @param index - The name of the index to query.
-     * @param key - The exact key value to look up in the index.
-     * @returns A promise that resolves to the first matching record (cloned), or `undefined` if none.
-     * @throws {Error} If the index does not exist, the key is `undefined`, or the operation fails.
+     * @param indexName - The name of the index to query.
+     * @param key - The exact key value to look up.
      */
-    getByIndex(index: string, key: any): Promise<T | undefined>;
+    getByIndex(indexName: string, key: any): Promise<T | undefined>;
     /**
-     * Retrieves multiple records from an index, optionally within a key range.
+     * 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 index - The name of the index to query.
-     * @param keyRange - Optional `StoreKeyRange` to filter results. If omitted, all records are returned.
-     * @returns A promise that resolves to an array of matching records (each cloned).
-     * @throws {Error} If the index does not exist or the operation fails.
+     * @param indexName - The name of the index to query.
+     * @param keyRange - Optional range to filter results.
      */
-    getByKeyRange(index: string, keyRange?: StoreKeyRange): Promise<T[]>;
+    getByKeyRange(indexName: string, keyRange?: StoreKeyRange): Promise<T[]>;
     /**
-     * Retrieves all records from the store.
-     *
-     * @returns A promise that resolves to an array of all records (each cloned).
-     * @throws {Error} If the operation fails.
+     * Retrieves all records from the store without index involvement.
      */
     getAll(): Promise<T[]>;
     /**
-     * Inserts or replaces a record.
-     *
-     * If a record with the same key already exists, it is replaced.
-     * The record must contain the store's key path property.
-     *
-     * @param data - The record to store.
-     * @returns A promise that resolves to the key of the stored record.
-     * @throws {Error} If the record lacks the key path property or the operation fails.
+     * 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.
      *
-     * The callback is invoked for each record in iteration order. The callback
-     * can control the iteration by returning `{ done: true }` to stop, or
-     * `{ offset: n }` to skip ahead `n` records.
-     *
-     * @param callback - Function called for each record.
-     * @param direction - Iteration direction: `"forward"` (ascending keys) or `"backward"` (descending keys).
-     * @param keyRange - An optional StoreKeyRange to start from specific points.
-     * @returns A promise that resolves to the last record processed (or `null` if none).
-     * @throws {Error} If the callback throws or the operation fails.
+     * @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.
-     *
-     * All operations in the batch succeed or fail together. This is useful for
-     * maintaining consistency when multiple writes are required.
+     * Executes a batch of write operations atomically within this store.
+     * All operations succeed or fail together.
      *
-     * @param operations - An array of operations. Each operation can be:
-     *   - `{ type: "add" | "put", data: T | T[] }`
-     *   - `{ type: "delete", data: string | number | (string | number)[] }`
-     * @returns A promise that resolves when the batch is committed.
-     * @throws {Error} If any operation fails or the batch cannot be completed.
+     * Used for standalone (single-store) atomic writes. For cross-store atomicity,
+     * use executeInTransaction instead.
      */
     batch(operations: Array<{
         type: "add" | "put";
@@ -168,44 +209,81 @@ interface Store<T = any> {
         type: "delete";
         data: string | number | (string | number)[];
     }>): Promise<void>;
-    open(): 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.
-     * @param query - The query to execute.
-     * @returns A promise resolving to the matching document or `null` if not found.
      */
     find: (query: QueryFilter<T>) => Promise<Document<T> | null>;
     /**
-     * Lists documents based on the provided query.
-     * @param query - The query to list documents (supports pagination and sorting).
-     * @returns A promise resolving to an array of documents.
+     * 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 documents based on the provided query.
-     * @param query - The query to filter documents.
-     * @returns A promise resolving to an array of matching documents.
+     * Filters all documents matching the query.
      */
     filter: (query: QueryFilter<T>) => Promise<Document<T>[]>;
     /**
-     * Creates a new document in the schema.
+     * 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.
-     * @returns A promise resolving to the created document.
+     * @param tx - Optional transaction to buffer the write into.
      */
-    create: (initial: T) => Promise<Document<T>>;
+    create: (initial: T, tx?: TransactionContext) => Promise<Document<T>>;
     /**
-     * Subscribes to schema-level events (e.g., "create", "update", "delete", "access").
-     * @param event - The event type to subscribe to.
-     * @param callback - The function to call when the event occurs.
-     * @returns A promise resolving to an unsubscribe function.
+     * Subscribes to collection-level events.
      */
-    subscribe: (event: CollectionEventType | TelemetryEventType, callback: (event: CollectionEvent<T> | TelemetryEvent) => void) => Promise<() => void>;
+    subscribe: (event: CollectionEventType | TelemetryEventType, callback: (event: CollectionEvent<T> | TelemetryEvent) => void) => () => void;
     /**
-     * Validate data
-     * @param data - The data to validate
-     * @returns An object containing validation results
+     * Validates data against the collection's schema.
      */
     validate(data: Record<string, any>): Promise<{
         value?: any;
@@ -214,9 +292,10 @@ interface Collection<T> {
             path: Array<string>;
         }>;
     }>;
+    invalidate(): void;
 }
 /**
- * Event payload for DocumentCursor events.
+ * Event payload for Collection events.
  */
 type CollectionEventType = "document:create" | "collection:read" | "migration:start" | "migration:end";
 type CollectionEvent<T> = {
@@ -229,91 +308,49 @@ type CollectionEvent<T> = {
 };
 interface Database {
     /**
-     * Accesses a schema model by name.
-     * @param schemaName - The name of the schema to access.
-     * @returns A promise resolving to the schema's DocumentCursor.
-     * @throws DatabaseError
+     * Opens an existing collection by name.
      */
     collection: <T>(schemaName: string) => Promise<Collection<T>>;
     /**
-     * Creates a new schema model.
-     * @param schema - The schema definition.
-     * @returns A promise resolving to the created schema's DocumentCursor.
-     * @throws DatabaseError
+     * Creates a new collection from a schema definition.
      */
     createCollection: <T>(schema: SchemaDefinition) => Promise<Collection<T>>;
     /**
-     * Deletes a schema by name.
-     * @param schemaName - The name of the schema to delete.
-     * @returns A promise resolving to `true` if successful, or `false` if an error occurs.
-     * @throws DatabaseError
+     * Deletes a collection and its schema record.
      */
     deleteCollection: (schemaName: string) => Promise<boolean>;
     /**
-     * Updates an existing schema.
-     * @param schema - The updated schema definition.
-     * @returns A promise resolving to `true` if successful, or `false` if an error occurs.
-     * @throws DatabaseError
+     * Updates an existing collection's schema record.
      */
     updateCollection: (schema: SchemaDefinition) => Promise<boolean>;
     /**
-     * Migrates an existing collection's data and updates its schema definition metadata.
-     * This function processes data in a streaming fashion to prevent loading
-     * the entire collection into memory.
-     *
-     * It will:
-     * 1. Verify the target collection exists.
-     * 2. Retrieve the collection's current schema definition from a metadata store ($index).
-     * 3. Initialize a `MigrationEngine` with this schema.
-     * 4. Allow a callback to define specific data transformations using the `MigrationEngine`.
-     * 5. **Crucially, it uses `migrationEngine.dryRun()` to get the `newSchema` that results**
-     * **from the transformations defined in the callback.**
-     * 6. Execute these transformations by streaming data from the collection,
-     * through the `MigrationEngine`, and back into the same collection.
-     * 7. Finally, update the schema definition for the collection in the `$index` metadata store
-     * to reflect this `newSchema`.
-     * All these steps for data and metadata updates happen within a single atomic IndexedDB transaction.
-     *
-     * Note: This function focuses solely on *data transformation* and *metadata updates*.
-     * It does NOT handle structural IndexedDB changes like adding/removing physical indexes or object stores,
-     * which still require an `onupgradeneeded` event (i.e., a database version upgrade).
-     *
-     * @param name - The name of the collection (IndexedDB object store) to migrate.
-     * @param {Object} opts - Options for the new migration
-     * @param {SchemaChange<any>[]} opts.changes - Array of schema changes
-     * @param {string} opts.description - Description of the migration
-     * @param {SchemaChange<any>[]} [opts.rollback] - Optional rollback changes
-     * @param {DataTransform<any, any>} [opts.transform] - Optional data transform
-     * @returns A Promise resolving to `true` if the migration completes successfully,
-     * @throws {DatabaseError} If the collection does not exist, its schema metadata is missing,
-     * or any IndexedDB operation/streaming fails critically.
+     * Migrates an existing collection's data and schema definition.
+     * Processes data in a streaming fashion to avoid loading the full collection
+     * into memory.
      */
-    migrateCollection: (name: string, opts: CollectionMigrationOptions, batchSize?: number) => Promise<boolean>;
+    migrateCollection: <T>(name: string, opts: CollectionMigrationOptions, batchSize?: number) => Promise<Collection<T>>;
     /**
-     * Subscribes to database-level events (e.g., "schemaAdded", "schemaDeleted", "schemaAccessed", "migrate").
-     * @param event - The event type to subscribe to.
-     * @param callback - The function to call when the event occurs.
-     * @returns A promise resolving to an unsubscribe function.
+     * 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).
      */
-    subscribe: (event: DatabaseEventType | "telemetry", callback: (event: DatabaseEvent | TelemetryEvent) => void) => Promise<() => void>;
+    transaction: (callback: (tx: TransactionContext) => Promise<void>) => Promise<void>;
     /**
-     * Closes the connection to the database
+     * 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 – safe to call multiple times.
-      * @param schema - The schema definition for the collection.
-      * @returns A promise that resolves when the collection exists.
-      * @throws {DatabaseError} If validation fails or an unexpected error occurs.
-      */
+     * 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 – safe to call multiple times.
-     * @param schemas - An array of schema definitions.
-     * @returns A promise that resolves when all collections exist.
-     * @throws {DatabaseError} If any schema validation fails or an unexpected error occurs.
+     * Ensures multiple collections exist; creates any that don't. Idempotent.
      */
     setupCollections: (schemas: SchemaDefinition[]) => Promise<void>;
 }
@@ -323,9 +360,6 @@ type CollectionMigrationOptions = {
     rollback?: SchemaChange<any>[];
     transform?: string | DataTransform<any, any>;
 };
-/**
- * Event payload for Database events.
- */
 type DatabaseEventType = "collection:create" | "collection:delete" | "collection:update" | "collection:read" | "migrate";
 type DatabaseEvent = {
     type: DatabaseEventType;
@@ -335,60 +369,17 @@ type DatabaseEvent = {
 type Document<T> = {
     readonly [K in keyof T]: T[K];
 } & {
-    /**
-     * Unique identifier for the document (assigned automatically if not provided).
-     */
     $id?: string;
-    /**
-     * Timestamp of document creation (ISO string or Date).
-     */
     $created?: string | Date;
-    /**
-     * Timestamp of last document update (ISO string or Date).
-     */
     $updated?: string | Date;
-    /**
-     * Version number incremented on each change (used for optimistic concurrency control).
-     */
     $version?: number;
-    /**
-     * Fetches the latest data from the database and updates the document instance.
-     * @returns A promise resolving to `true` if successful, or `false` if an error occurs.
-     */
     read: () => Promise<boolean>;
-    /**
-    * Saves the current document state to the database.
-    * Normally called automatically by `update()` or `delete()`, but can be used manually.
-    * @returns A promise resolving to `true` if successful, or `false` if an error occurs.
-    */
     save: (tx?: TransactionContext) => Promise<boolean>;
-    /**
-     * Updates the document with the provided properties.
-     * @param props - Partial object containing the fields to update.
-     * @returns A promise resolving to `true` if successful, or `false` if an error occurs.
-     */
-    update: (props: Partial<T>) => Promise<boolean>;
-    /**
-     * Deletes the document from the database.
-     * @returns A promise resolving to `true` if successful, or `false` if an error occurs.
-     */
-    delete: () => Promise<boolean>;
-    /**
-     * Subscribes to document events (e.g., "update", "delete", "access").
-     * @param event - The event type to subscribe to.
-     * @param callback - The function to call when the event occurs.
-     * @returns An unsubscribe function.
-     */
+    update: (props: Partial<T>, tx?: TransactionContext) => Promise<boolean>;
+    delete: (tx?: TransactionContext) => Promise<boolean>;
     subscribe: (event: DocumentEventType | TelemetryEventType, callback: (event: DocumentEvent<T> | TelemetryEvent) => void) => () => void;
-    /**
-     * Returns a plain object containing only the user-defined data (without system fields like $id, $version, etc.).
-     * @returns The current user data.
-     */
     state(): T;
 };
-/**
- * Event payload for DocumentModel events.
- */
 type DocumentEventType = "document:create" | "document:write" | "document:update" | "document:delete" | "document:read";
 type DocumentEvent<T> = {
     type: DocumentEventType;
@@ -412,7 +403,7 @@ type TelemetryEvent = {
             document?: string;
         };
         result?: {
-            type: 'array' | string;
+            type: "array" | string;
             size?: number;
         };
         error: {
@@ -423,22 +414,88 @@ type TelemetryEvent = {
     };
 };
 interface DatabaseConfig {
-    name: string;
+    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;
-    constructor(keyPath?: string);
+    /**
+     * @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>;
-    private getKey;
-    private clone;
+    /**
+     * 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<{
@@ -448,15 +505,47 @@ declare class MemoryStore<T extends Record<string, any>> implements Store<T> {
         type: "delete";
         data: string | number | (string | number)[];
     }>): Promise<void>;
-    getById(id: string | number): Promise<T | undefined>;
     delete(id: string | number | (string | number)[]): Promise<void>;
     clear(): Promise<void>;
-    count(): Promise<number>;
-    getByIndex(index: string, key: any): Promise<T | undefined>;
-    getByKeyRange(indexName: string, keyRange?: StoreKeyRange): Promise<T[]>;
-    private isInKeyRange;
+    /**
+     * 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>;
@@ -469,77 +558,125 @@ declare class ConnectionManager {
     private readonly config;
     private connectionInitializer;
     private readonly schemasStoreName;
+    constructor(config: DatabaseConfig);
+    private openDatabase;
     /**
-     * Initializes a new ConnectionManager.
+     * 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).
      *
-     * @param config - The database configuration options.
+     * Note: IDB only allows structural changes (createObjectStore, createIndex,
+     * deleteIndex) inside an onupgradeneeded handler. This method is the single
+     * entry point for all such changes.
      */
-    constructor(config: DatabaseConfig);
+    private upgradeDatabase;
     /**
-     * Opens the database and ensures the base schemas store exists.
+     * 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.
      *
-     * @returns A promise that resolves to the opened IDBDatabase instance.
-     * @throws {Error} If the database fails to open.
+     * @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.
      */
-    private openDatabase;
+    ensureStore(collection: string, keyPath?: string, indexes?: IndexDefinition[]): Promise<void>;
     /**
-     * Upgrades the database version and executes the provided upgrade logic.
+     * Adds a named index to an existing object store.
+     * Triggers a database version upgrade.
      *
-     * @param currentConnection - The existing active IndexedDB connection to be closed.
-     * @param upgradeCallback - A callback function containing the structural changes to apply during the upgrade.
-     * @returns A promise that resolves to the newly upgraded IDBDatabase instance.
-     * @throws {Error} If the database upgrade fails.
+     * @param collection - The object store to add the index to.
+     * @param definition - The index definition.
      */
-    private upgradeDatabase;
+    createStoreIndex(collection: string, definition: IndexDefinition): Promise<void>;
     /**
-     * Ensures a collection object store exists within the database.
-     * Triggers an upgrade if the specified store is missing.
+     * Removes a named index from an existing object store.
+     * Triggers a database version upgrade.
      *
-     * @param collectionName - The name of the collection store to ensure.
-     * @param keyPath - The primary key path for the collection (defaults to "$id").
-     * @returns A promise that resolves when the store is confirmed to exist.
+     * @param storeName - The object store to remove the index from.
+     * @param indexName - The name of the index to remove.
      */
-    ensureStore(collectionName: string, keyPath?: string): Promise<void>;
+    dropStoreIndex(storeName: string, indexName: string): Promise<void>;
     /**
      * Retrieves or opens the active database connection.
-     * Handles connection loss and version changes automatically.
-     *
-     * @returns A promise resolving to the active IDBDatabase connection.
-     * @throws {DatabaseError} If the connection initialization fails.
      */
     getConnection: () => Promise<IDBDatabase>;
     /**
-     * Performs a version upgrade using custom structural logic.
-     * Resets the internal initialization state so subsequent callers wait for the new version.
+     * Opens a readwrite IDBTransaction spanning the given store names.
      *
-     * @param upgradeLogic - A callback executed during the IndexedDB upgradeneeded event.
-     * @returns A promise resolving to the upgraded IDBDatabase connection.
-     * @throws {DatabaseError} If the internal upgrade procedure fails.
+     * 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").
      */
-    upgrade(upgradeLogic: (db: IDBDatabase) => void): Promise<IDBDatabase>;
+    openTransaction(storeNames: string[], mode?: IDBTransactionMode): Promise<IDBTransaction>;
     /**
-     * Closes the active database connection and resets the internal initialization state.
+     * 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 getConnection;
-    private readonly storeName;
+    private readonly connectionManager;
+    private readonly collection;
     private readonly keyPath;
-    private readonly onOpen;
-    constructor(getConnection: () => Promise<IDBDatabase>, storeName: string, keyPath: string | undefined, onOpen: () => Promise<void>);
+    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>;
     /**
-     * Map native DOMExceptions to internal DatabaseErrors.
+     * Adds a new index to the IDB object store. Triggers a database version upgrade.
+     * Idempotent — no-op if the index already exists.
      */
-    private mapError;
+    createIndex(definition: IndexDefinition): Promise<void>;
     /**
-     * Core wrapper for transaction safety. It converts IDB request callbacks
-     * into a single Promise while preserving transaction activity.
+     * Removes a named index from the IDB object store. Triggers a version upgrade.
+     * No-op if the index does not exist.
      */
-    private withTx;
-    private requestToPromise;
+    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<{
@@ -549,29 +686,98 @@ declare class IndexedDBStore<T extends Record<string, any>> implements Store<T>
         type: "delete";
         data: string | number | (string | number)[];
     }>): Promise<void>;
-    getById(id: string | number): Promise<T | undefined>;
     delete(id: string | number | (string | number)[]): Promise<void>;
     clear(): Promise<void>;
-    count(): Promise<number>;
-    getByIndex(indexName: string, key: any): Promise<T | undefined>;
-    getByKeyRange(indexName: string, keyRange?: StoreKeyRange): Promise<T[]>;
+    /**
+     * 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;
 }
 
-declare const createIndexedDbStore: <T extends Record<string, any>>(config: DatabaseConfig) => Store<T>;
+/**
+ * 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>;
 
-declare function DatabaseConnection(config: Omit<DatabaseConfig, "keyPath">, createStore: <T extends Record<string, any>>(config: DatabaseConfig) => Store<T>): Promise<Database>;
+declare function DatabaseConnection(config: Omit<DatabaseConfig, "keyPath">, createStore: <T extends Record<string, any>>(config: StoreConfig, indexes: IndexDefinition[]) => Store<T>): Promise<Database>;
 
-declare class IndexManager<T extends Record<string, any>> {
-    private indexes;
-    createIndex(field: string): void;
-    removeIndex(field: string): void;
-    hasIndex(field: string): boolean;
-    indexDocument(doc: T): void;
-    removeDocument(doc: T): void;
-    lookup(field: string, value: any): Set<string | number> | undefined;
-    clear(): void;
+/**
+ * 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.
+     * @returns A function to unsubscribe from the event.
+     */
+    subscribe: <TEventName extends keyof TEventMap>(eventName: TEventName, callback: (payload: TEventMap[TEventName]) => void) => () => 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: (payload: TEventMap[TEventName]) => void) => () => 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.
+     */
+    clear: () => 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 MiddlewareContext {
@@ -599,6 +805,11 @@ declare class Mutex {
 }
 
 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;
     validator?: StandardSchemaV1;
@@ -606,8 +817,18 @@ interface DocumentOptions<T extends Record<string, any>> {
     bus: EventBus<Record<DocumentEventType | TelemetryEventType, DocumentEvent<T> | TelemetryEvent>>;
     pipeline: Pipeline;
     lockManager: Mutex;
-    indexManager: IndexManager<T>;
 }
+/**
+ * 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;
 }>>;
@@ -620,4 +841,51 @@ declare function openCollection<T extends Record<string, any>>({ collection: sch
     validate: boolean;
 }): Promise<Collection<T>>;
 
-export { type Collection, type CollectionEvent, type CollectionEventType, type CollectionMigrationOptions, ConnectionManager, type CursorCallback, type CursorCallbackResult, type CursorPaginationOptions, DEFAULT_KEYPATH, type Database, type DatabaseConfig, DatabaseConnection, type DatabaseEvent, type DatabaseEventType, type Document, type DocumentEvent, type DocumentEventType, IndexedDBStore, type Store, type StoreKeyRange, type TelemetryEvent, type TelemetryEventType, createDocument, createEphemeralStore, createIndexedDbStore, openCollection };
+/**
+ * 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;
+    /**
+     * 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);
+}
+
+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, IndexedDBStore, type Store, type StoreConfig, type StoreKeyRange, type TelemetryEvent, type TelemetryEventType, createDocument, createEphemeralStore, createIndexedDbStore, openCollection };