@abloatai/ablo 0.3.0

package/dist/Database.d.ts

@@ -0,0 +1,344 @@
+/**
+ * Database - Simplified persistence layer
+ * Fixed bootstrap triggering and data flow
+ */
+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 { InMemoryObjectStore } from './adapters/inMemoryStorage.js';
+/** Generic record type for model data */
+type ModelData = Record<string, unknown>;
+/** Persisted mutation in a transaction */
+interface PersistedMutation {
+    type: 'create' | 'update' | 'delete' | 'archive';
+    modelData: ModelData;
+    modelName: string;
+    timestamp: string;
+    writeOptions?: {
+        readAt?: number | null;
+        onStale?: 'reject' | 'force' | 'flag' | 'merge' | null;
+    };
+}
+/** Persisted transaction for offline/retry support.
+ *
+ *  Index signature is part of the contract: this interface targets
+ *  the generic record-shaped storage layer (`InMemoryObjectStore.put`
+ *  + the IDB ObjectStore equivalent), both of which take
+ *  `Record<string, unknown>`. Every declared field below already
+ *  satisfies `unknown`; the index signature just makes the
+ *  interface assignable to the storage parameter without a cast. */
+interface PersistedTransaction {
+    id: string;
+    type?: string;
+    timestamp?: number;
+    createdAt?: number;
+    mutations?: PersistedMutation[];
+    awaitingDelta?: {
+        syncIdNeeded: number;
+        modelName: string;
+        modelId: string;
+        operationType: string;
+    };
+    [key: string]: unknown;
+}
+/**
+ * Bootstrap strategies (aligned with Linear's architecture):
+ *
+ * 'full' - Full bootstrap from server
+ *   - Fetch complete snapshot from server
+ *   - Clear IndexedDB
+ *   - Load snapshot data
+ *   - Use snapshot's 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
+ */
+export type BootstrapType = 'full' | 'partial' | 'local';
+export interface BootstrapRequirements {
+    type: BootstrapType;
+    modelsToLoad: string[];
+    lastSyncId: number;
+    syncGroups: string[];
+}
+export interface BootstrapResult {
+    modelsLoaded: number;
+    modelsStored: number;
+    /** The raw bootstrap response — callers can apply models directly to ObjectPool */
+    bootstrapData: BootstrapData;
+    /**
+     * Results of applying partial-bootstrap deltas to IDB. Present only when
+     * `bootstrapData.type === 'partial'` and deltas were processed. Callers
+     * forward these to `syncClient.applyDeltaBatchToPool` so the in-memory
+     * pool reflects inserts/updates/deletes that arrived while the client
+     * was disconnected — without this, DELETE deltas persist to IDB but
+     * ghost entities linger in the pool until a full reload.
+     */
+    deltaResults?: Array<{
+        action: 'add' | 'update' | 'remove' | 'archive' | 'verify';
+        modelName: string;
+        modelId: string;
+        data?: ModelData | null;
+    }>;
+}
+export declare class Database {
+    private databaseManager;
+    private storeManager;
+    private modelRegistry;
+    private bootstrapHelper;
+    /** The pre-configured query helper for lazy-loading data from the sync server. */
+    get helper(): BootstrapHelper;
+    private currentDbInfo;
+    private workspaceDb;
+    /**
+     * Flag to track if database is closing/closed.
+     * Used for graceful degradation when operations are attempted during shutdown.
+     */
+    private isClosing;
+    /**
+     * When set, forces the next requiredBootstrap() call to return 'full' even if offline.
+     * Used when a sync group change delta is received — we must re-bootstrap to purge
+     * revoked data, even if the device is currently offline (it will bootstrap when online).
+     */
+    private _forceFullBootstrap;
+    /** Essential fields that must be preserved during partial UPDATE merges.
+     * Sourced from SyncEngineConfig.essentialFields — consumers define their own. */
+    private get essentialFields();
+    /**
+     * When true, all IndexedDB operations are replaced with in-memory Maps.
+     * Enables the SDK to run headlessly in Node.js / agent workers / tests
+     * without requiring a browser environment.
+     *
+     * Set via createSyncEngine({ storage: inMemoryStorage() }) or directly:
+     *   new Database(registry, bootstrap, { inMemory: true })
+     */
+    private readonly inMemory;
+    /** In-memory stores used when inMemory=true. Keyed by model name. */
+    private inMemoryStores;
+    /** In-memory workspace metadata when inMemory=true. */
+    private inMemoryMetadata;
+    constructor(modelRegistry: ModelRegistry, bootstrapHelper: BootstrapHelper, options?: {
+        inMemory?: boolean;
+    });
+    /**
+     * Get store for a model, or `undefined` if no store exists.
+     *
+     * Routes to `inMemoryStores` in inMemory mode and `storeManager`
+     * otherwise. Both implementations satisfy `ObjectStoreContract`, so
+     * callers don't branch on which one they got back.
+     *
+     * Pass `context` to emit an observability breadcrumb when the store
+     * is missing — useful for hot paths (bootstrap, delta apply, hydrate)
+     * where a missing store points to silent data loss. Callers that
+     * already expect optional behavior (e.g. lazy lookups) can omit it.
+     */
+    getStore(modelName: string, context?: string): import("./stores/ObjectStore.js").ObjectStore | InMemoryObjectStore | undefined;
+    /** Get store or throw if not found (for operations that require the store). */
+    private getRequiredStore;
+    /** Log preserved fields during partial UPDATE merge (debug helper) */
+    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
+     *
+     * Note: We do NOT drop required defaults; server provides them.
+     */
+    private compactRecord;
+    /**
+     * Mark that the next bootstrap must be a full bootstrap.
+     * Called when a sync group change ("G" delta) is received — the client must
+     * re-fetch all data from the server to purge models from revoked sync groups.
+     */
+    markRequiresFullBootstrap(): void;
+    /**
+     * Smart bootstrap requirements based on data freshness
+     */
+    requiredBootstrap(): Promise<BootstrapRequirements>;
+    /**
+     * Bootstrap database with data from Go server
+     */
+    bootstrapFromServer(requirements: BootstrapRequirements, 
+    /** Full sync-group subscription list — what the WS subscribes to
+     *  AND what gets persisted as `subscribedSyncGroups` for the
+     *  shrinkage check. Caller supplies the complete list, not just
+     *  team-derived groups. */
+    syncGroups: readonly string[], onProgress?: (loaded: number) => void): Promise<BootstrapResult>;
+    /**
+     * Process incoming delta from WebSocket - simplified
+     *
+     * ⚠️ 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).
+     *
+     * 📝 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
+     */
+    processDelta(delta: {
+        syncId?: number;
+        /**
+         * Includes 'G' and 'S' defensively — those are routed upstream by
+         * BaseSyncedStore.processDeltaWithBatching and should not reach here,
+         * but the switch returns a no-op verify if one slips through (e.g.
+         * replayed from the bootstrap queue) rather than crashing the engine.
+         */
+        actionType: 'I' | 'U' | 'D' | 'A' | 'V' | 'C' | 'G' | 'S';
+        modelName: string;
+        modelId: string;
+        data: ModelData | null;
+    }): Promise<{
+        action: 'add' | 'update' | 'remove' | 'archive' | 'verify';
+        modelName: string;
+        modelId: string;
+        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
+     *
+     * 📝 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
+     *
+     * 🔄 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
+     */
+    processDeltaBatch(deltas: Array<{
+        syncId?: number;
+        /**
+         * Includes 'G' and 'S' defensively — they're routed upstream and
+         * shouldn't reach batch processing, but the switch inside returns
+         * no-op verify for them if one slips through.
+         */
+        actionType: 'I' | 'U' | 'D' | 'A' | 'V' | 'C' | 'G' | 'S';
+        modelName: string;
+        modelId: string;
+        data: ModelData | null;
+        /**
+         * Server-stamped transaction id from the originating client's
+         * commit op. Threaded through to the result so the receive
+         * pipeline can recognize echoes of the local client's own
+         * mutations and skip the pool mutation in
+         * `SyncClient.applyDeltaBatchToPool`. Optional because system-
+         * emitted deltas (sync_group changes, schema-derived ops) don't
+         * have a client transaction.
+         */
+        transactionId?: string;
+    }>): Promise<{
+        results: Array<{
+            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
+         * 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.
+         * 0 when nothing persisted.
+         */
+        persistedSyncId: number;
+    }>;
+    /** Get raw data for hydration */
+    hydrateModels(modelName: string): Promise<ModelData[]>;
+    /** Put a single record to IndexedDB (for self-healing corrupted records) */
+    putRecord(modelName: string, id: string, data: Record<string, unknown>): Promise<void>;
+    /** 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). */
+    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
+     *  (`InMemoryObjectStore`) — both expose the same async put/get/
+     *  delete/getAll/getAllFromIndex surface, so callers don't need to
+     *  branch on which one they got back. */
+    private get transactionStore();
+    saveTransaction(transaction: PersistedTransaction): Promise<void>;
+    removeTransaction(id: string): Promise<void>;
+    getPersistedTransactions(): Promise<PersistedTransaction[]>;
+    cleanupOldTransactions(maxAge: number): Promise<number>;
+    /**
+     * Store management
+     *
+     * `getStore(modelName, context?)` is defined near the top of this
+     * class — single accessor for both inMemory and IDB modes.
+     */
+    getAllStores(): Map<string, import("./stores/ObjectStore.js").ObjectStore> | Map<string, InMemoryObjectStore>;
+    /**
+     * Model persistence tracking
+     */
+    setModelPersisted(modelName: string, persisted: boolean): Promise<void>;
+    isModelPersisted(modelName: string): Promise<boolean>;
+    /**
+     * Statistics
+     */
+    getStats(): Promise<{
+        database: DatabaseInfo | null;
+        stores: {
+            totalStores: number;
+            storeTypes: {
+                full: number;
+                partial: number;
+            };
+            readiness: {
+                ready: number;
+                notReady: number;
+            };
+            totalRecords: number;
+            storeDetails: Array<{
+                modelName: string;
+                storeName: string;
+                strategy: LoadStrategy;
+                ready: boolean;
+                count: number;
+            }>;
+        };
+        metadata: WorkspaceMetadata | null;
+    }>;
+    /**
+     * Lifecycle
+     */
+    isOpen(): boolean;
+    close(): Promise<void>;
+    clear(): Promise<void>;
+}
+export {};