@asaidimu/utils-workspace 2.1.0 → 2.1.1

package/index.d.ts

@@ -1,5 +1,5 @@
 import { QueryFilter, PaginationOptions } from '@asaidimu/query';
-import { SchemaDefinition, SchemaChange, DataTransform } from '@asaidimu/anansi';
+import { IndexDefinition, SchemaDefinition, SchemaChange, DataTransform } from '@asaidimu/anansi';
 
 type UUID = string;
 type Timestamp = string;
@@ -539,14 +539,78 @@ interface TranscriptWindow {
     hasMore: boolean;
 }
 
+/**
+ * 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;
 }
 
 interface CursorCallbackResult<T> {
@@ -560,8 +624,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>>;
 /**
@@ -573,123 +638,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";
@@ -698,44 +740,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;
@@ -744,9 +823,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> = {
@@ -759,91 +839,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>;
 }
@@ -853,9 +891,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;
@@ -865,60 +900,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;
@@ -942,7 +934,7 @@ type TelemetryEvent = {
             document?: string;
         };
         result?: {
-            type: 'array' | string;
+            type: "array" | string;
             size?: number;
         };
         error: {