@abloatai/ablo 0.25.0 → 0.27.0

package/dist/Database.d.ts

@@ -1,11 +1,14 @@
 /**
- * Database - Simplified persistence layer
- * Fixed bootstrap triggering and data flow
+ * The local persistence layer for synced models. It stores rows in the
+ * browser's IndexedDB (or in-memory maps when run headlessly), applies inbound
+ * deltas to that store, and fetches the bootstrap snapshot from your sync
+ * server. {@link BaseSyncedStore} drives it, and {@link InstanceCache} holds the
+ * in-memory mirror of what this class persists.
  */
 import { type DatabaseInfo, type WorkspaceMetadata } from './core/DatabaseManager.js';
 import { ModelRegistry } from './ModelRegistry.js';
 import { LoadStrategy } from './types/index.js';
-import type { BootstrapHelper, BootstrapData } from './sync/BootstrapHelper.js';
+import type { BootstrapFetcher, BootstrapData } from './sync/BootstrapFetcher.js';
 import { InMemoryObjectStore } from './adapters/inMemoryStorage.js';
 /** Generic record type for model data */
 type ModelData = Record<string, unknown>;
@@ -43,19 +46,17 @@ interface PersistedTransaction {
     [key: string]: unknown;
 }
 /**
- * Bootstrap strategies (aligned with Linear's architecture):
+ * How a session establishes its baseline state at startup.
  *
- * 'full' - Full bootstrap from server
- *   - Fetch complete snapshot from server
- *   - Clear IndexedDB
- *   - Load snapshot data
- *   - Use snapshot's lastSyncId
+ * 'full' — Fetch a complete snapshot from the server, clear the local store,
+ *   load the snapshot, and adopt its `lastSyncId`.
  *
- * 'local' - Local-only bootstrap (skip server fetch)
- *   - Use existing IndexedDB data
- *   - Hydrate ObjectPool from IndexedDB
- *   - Connect WebSocket with stored lastSyncId
- *   - Receive deltas from lastSyncId+1 onwards
+ * 'partial' — Fetch only the deltas since the stored `lastSyncId` and apply
+ *   them on top of the existing local data.
+ *
+ * 'local' — Skip the server entirely: hydrate the {@link InstanceCache} from the
+ *   local store, connect the WebSocket with the stored `lastSyncId`, and
+ *   receive deltas from there onward. Used when offline with valid local data.
  */
 export type BootstrapType = 'full' | 'partial' | 'local';
 export interface BootstrapRequirements {
@@ -67,7 +68,7 @@ export interface BootstrapRequirements {
 export interface BootstrapResult {
     modelsLoaded: number;
     modelsStored: number;
-    /** The raw bootstrap response — callers can apply models directly to ObjectPool */
+    /** The raw bootstrap response — callers can apply models directly to InstanceCache */
     bootstrapData: BootstrapData;
     /**
      * Results of applying partial-bootstrap deltas to IDB. Present only when
@@ -77,12 +78,12 @@ export interface BootstrapResult {
      * was disconnected — without this, DELETE deltas persist to IDB but
      * ghost entities linger in the pool until a full reload.
      */
-    deltaResults?: Array<{
+    deltaResults?: {
         action: 'add' | 'update' | 'remove' | 'archive' | 'verify';
         modelName: string;
         modelId: string;
         data?: ModelData | null;
-    }>;
+    }[];
 }
 export declare class Database {
     private databaseManager;
@@ -90,13 +91,13 @@ export declare class Database {
     private modelRegistry;
     private bootstrapHelper;
     /** The pre-configured query helper for lazy-loading data from the sync server. */
-    get helper(): BootstrapHelper;
+    get helper(): BootstrapFetcher;
     /**
-     * PURE scoped snapshot fetch for hydrate-on-enter (P4). Returns the FULL
-     * current rows of the given sync groups, with NO side effects — unlike
+     * Fetch the current rows of the given sync groups as a side-effect-free
+     * snapshot, used to hydrate a scope as the user enters it. Unlike
      * {@link bootstrapFromServer}, it does not persist to IndexedDB and does not
-     * touch the connection's `subscribedSyncGroups` (which the shrinkage check
-     * owns). The caller applies the result to the pool via the SCOPED apply path.
+     * change the connection's subscribed sync groups. The caller applies the
+     * result to the pool through the scoped apply path.
      */
     fetchScopedBootstrapData(syncGroups: readonly string[]): Promise<BootstrapData>;
     private currentDbInfo;
@@ -128,7 +129,7 @@ export declare class Database {
     private inMemoryStores;
     /** In-memory workspace metadata when inMemory=true. */
     private inMemoryMetadata;
-    constructor(modelRegistry: ModelRegistry, bootstrapHelper: BootstrapHelper, options?: {
+    constructor(modelRegistry: ModelRegistry, bootstrapHelper: BootstrapFetcher, options?: {
         inMemory?: boolean;
     });
     /**
@@ -150,17 +151,14 @@ export declare class Database {
     private logPreservedFields;
     open(userId: string, organizationId: string, version?: number): Promise<void>;
     /**
-     * Compact a record before persisting to IndexedDB
-     * - Removes null/undefined fields
-     * - Removes empty arrays and empty objects
-     * - Drops redundant fields: __typename, __class, clientId, syncStatus
-     *
-     * ARCHITECTURE: By design, this method receives plain objects, not MobX observables:
-     * - WebSocket deltas: Already JSON-parsed (SyncedStore.ts:889)
-     * - Optimistic updates: Models call toJSON() which uses toJS() (SlideLayer.ts:224)
-     * - Bootstrap data: Plain JSON from server
+     * Shrink a record before persisting it. Drops `undefined` fields, empty
+     * arrays, empty objects, and the redundant markers `__typename`, `__class`,
+     * `clientId`, and `syncStatus`. Explicit `null` values are preserved, since
+     * a null is a meaningful "clear this field" in a nullable column.
      *
-     * Note: We do NOT drop required defaults; server provides them.
+     * By design this receives plain objects, never live observables: WebSocket
+     * deltas arrive already parsed, optimistic updates come through `toJSON()`,
+     * and bootstrap data is plain JSON from the server.
      */
     private compactRecord;
     /**
@@ -174,7 +172,9 @@ export declare class Database {
      */
     requiredBootstrap(): Promise<BootstrapRequirements>;
     /**
-     * Bootstrap database with data from Go server
+     * Fetch a bootstrap snapshot (or delta batch) from the sync server and load
+     * it into the local store, then return a {@link BootstrapResult} the caller
+     * applies to the {@link InstanceCache}.
      */
     bootstrapFromServer(requirements: BootstrapRequirements, 
     /** Full sync-group subscription list — what the WS subscribes to
@@ -183,17 +183,16 @@ export declare class Database {
      *  team-derived groups. */
     syncGroups: readonly string[], onProgress?: (loaded: number) => void): Promise<BootstrapResult>;
     /**
-     * Process incoming delta from WebSocket - simplified
+     * Apply a single inbound delta from the WebSocket to the local store.
      *
-     * ⚠️ PERFORMANCE NOTE: This method is called for each individual delta.
-     * For batch processing, use processDeltaBatch() instead to avoid
-     * transaction overhead (2x transactions per delta = major bottleneck).
+     * This handles one delta at a time. To apply several, prefer
+     * {@link processDeltaBatch}, which commits them in one IndexedDB transaction
+     * rather than two transactions per delta.
      *
-     * 📝 PARTIAL DELTA PATTERN:
-     * - Server sends only changed fields: {id, position: {...}, updatedAt}
-     * - UPDATE deltas are MERGED with existing records: {...existing, ...delta}
-     * - This preserves fields not included in the delta (e.g., deckId, title)
-     * - Explicit null values ARE preserved: {position: null} clears the field
+     * Update deltas carry only the changed fields, so they are merged onto the
+     * existing record rather than replacing it. That preserves fields the delta
+     * omits (such as deckId or title), and an explicit null is kept as a value,
+     * clearing that field.
      */
     processDelta(delta: {
         syncId?: number;
@@ -214,29 +213,22 @@ export declare class Database {
         data?: ModelData | null;
     }>;
     /**
-     * ✅ PERFORMANCE FIX: Process multiple deltas in a single IndexedDB transaction
-     *
-     * This method dramatically improves sync performance by:
-     * 1. Batch-reading all existing records for UPDATEs (outside transaction for speed)
-     * 2. Opening a single transaction per store for all writes
-     * 3. Merging UPDATE deltas with existing data to preserve unmodified fields
-     * 4. Updating metadata only once at the end with highest syncId
-     *
-     * Performance impact: 186 deltas goes from ~372 transactions to just 1 transaction
+     * Apply many deltas to the local store in as few IndexedDB transactions as
+     * possible. Deltas are grouped by store, and each store's writes commit in a
+     * single transaction, so a batch of 186 deltas becomes roughly one
+     * transaction per store instead of two per delta.
      *
-     * 📝 PARTIAL DELTA MERGE PATTERN:
-     * - UPDATE deltas contain only changed fields
-     * - We merge with existing: {...existing, ...delta}
-     * - Preserves deckId, title, settings etc. when updating just position
-     * - Handles explicit null: {field: null} clears the field correctly
+     * The method reads the existing records for update deltas up front, then
+     * merges each update onto its existing record so fields the delta omits are
+     * preserved and an explicit null still clears its field. It advances the
+     * persisted sync cursor once, to the highest committed sync id.
      *
-     * 🔄 LINEAR-STYLE CONFLICT RESOLUTION:
-     * - Builds a map of DELETE deltas with their syncIds
-     * - Before processing UPDATE/INSERT, checks for DELETE with higher syncId
-     * - Skips stale updates for entities that will be/were deleted
-     * - Prevents 404 errors from fetching already-deleted entities
+     * Conflict resolution follows a delete-wins rule: it first indexes the
+     * delete deltas by entity, then skips any insert or update whose sync id is
+     * at or below a delete for the same entity. This avoids resurrecting a
+     * deleted entity and avoids fetching one that no longer exists.
      */
-    processDeltaBatch(deltas: Array<{
+    processDeltaBatch(deltas: {
         syncId?: number;
         /**
          * Includes 'G' and 'S' defensively — they're routed upstream and
@@ -257,18 +249,18 @@ export declare class Database {
          * have a client transaction.
          */
         transactionId?: string;
-    }>): Promise<{
-        results: Array<{
+    }[]): Promise<{
+        results: {
             action: 'add' | 'update' | 'remove' | 'archive' | 'verify';
             modelName: string;
             modelId: string;
             data?: ModelData | null;
             transactionId?: string;
-        }>;
+        }[];
         /**
          * Highest syncId whose IDB store transaction actually committed in this
          * batch. The runtime delta cursor (WS `lastSyncId`, server-side
-         * `lastAckedSyncId`) must only advance to THIS value — not the input
+         * `lastAckedSyncId`) must only advance to this value — not the input
          * batch's range max — or it diverges from the persisted view and the
          * next catch-up request skips the un-persisted gap forever. Mirrors
          * the metadata-cursor invariant at `updateWorkspaceMetadata` below.
@@ -283,16 +275,9 @@ export declare class Database {
     /** Get data by index. `value` is an IDB key — string, number, Date,
      *  BufferSource, or array thereof. */
     getDataByIndex(modelName: string, indexName: string, value: IDBValidKey): Promise<ModelData[]>;
-    /**
-     * Update workspace metadata
-     */
-    /**
-     * Get the last sync ID from workspace metadata
-     */
-    /** Read workspace metadata from IDB (returns null if db not open). */
+    /** Read workspace metadata from IndexedDB. Returns null when the database is not open. */
     getWorkspaceMetadata(): Promise<WorkspaceMetadata | null>;
     getLastSyncId(): Promise<number>;
-    getVersionVector(): Promise<Record<string, number> | null>;
     updateWorkspaceMetadata(metadata: Partial<WorkspaceMetadata>): Promise<void>;
     /** Transaction persistence for offline/retry support.
      *  Returns either the IDB-backed ObjectStore or its in-memory twin
@@ -332,13 +317,13 @@ export declare class Database {
                 notReady: number;
             };
             totalRecords: number;
-            storeDetails: Array<{
+            storeDetails: {
                 modelName: string;
                 storeName: string;
                 strategy: LoadStrategy;
                 ready: boolean;
                 count: number;
-            }>;
+            }[];
         };
         metadata: WorkspaceMetadata | null;
     }>;