@asaidimu/utils-database 1.1.0 → 1.1.1

package/index.d.mts

@@ -1,16 +1,80 @@
 import { QueryFilter, PaginationOptions } from '@asaidimu/query';
-import { SchemaDefinition, SchemaChange, DataTransform, PredicateMap } from '@asaidimu/anansi';
+import { IndexDefinition, SchemaDefinition, SchemaChange, DataTransform, PredicateMap } from '@asaidimu/anansi';
 import { EventBus } from '@asaidimu/events';
 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 +94,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 +108,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.
+     * Executes a batch of write operations atomically within this store.
+     * All operations succeed or fail together.
      *
-     * All operations in the batch succeed or fail together. This is useful for
-     * maintaining consistency when multiple writes are required.
-     *
-     * @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 +210,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 +293,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 +309,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: <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).
      */
-    migrateCollection: (name: string, opts: CollectionMigrationOptions, batchSize?: number) => Promise<boolean>;
+    transaction: (callback: (tx: TransactionContext) => Promise<void>) => Promise<void>;
     /**
-     * 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.
+     * Subscribes to database-level events.
      */
-    subscribe: (event: DatabaseEventType | "telemetry", callback: (event: DatabaseEvent | TelemetryEvent) => void) => Promise<() => void>;
+    subscribe: (event: DatabaseEventType | "telemetry", callback: (event: DatabaseEvent | TelemetryEvent) => void) => () => void;
     /**
-     * Closes the connection to the database
+     * 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 +361,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 +370,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 +404,7 @@ type TelemetryEvent = {
             document?: string;
         };
         result?: {
-            type: 'array' | string;
+            type: "array" | string;
             size?: number;
         };
         error: {
@@ -423,22 +415,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 +506,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 +559,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").
+     */
+    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) => void): Promise<IDBDatabase>;
+    upgrade(upgradeLogic: (db: IDBDatabase, tx: IDBTransaction) => void): Promise<IDBDatabase>;
     /**
-     * Closes the active database connection and resets the internal initialization state.
+     * 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,30 +687,46 @@ 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>;
-
-declare function DatabaseConnection(config: Omit<DatabaseConfig, "keyPath">, createStore: <T extends Record<string, any>>(config: DatabaseConfig) => Store<T>): Promise<Database>;
+/**
+ * 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 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;
-}
+declare function DatabaseConnection(config: Omit<DatabaseConfig, "keyPath">, createStore: <T extends Record<string, any>>(config: StoreConfig, indexes: IndexDefinition[]) => Store<T>): Promise<Database>;
 
 interface MiddlewareContext {
     collection?: string;
@@ -599,6 +753,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 +765,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 +789,4 @@ 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 };
+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, 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 };