@abloatai/ablo 0.35.0 → 0.37.0

package/dist/Database.d.ts

@@ -1,335 +0,0 @@
-/**
- * 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 './transaction/types/index.js';
-import type { BootstrapFetcher, BootstrapData } from './sync/BootstrapFetcher.js';
-import { InMemoryObjectStore } from './adapters/inMemoryStorage.js';
-import type { SyncDeltaAction } from './transaction/wire/delta.js';
-import type { OnStaleMode } from './transaction/coordination/schema.js';
-import type { BootstrapType } from './transaction/types/index.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?: OnStaleMode | 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;
-}
-export type { BootstrapType };
-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 InstanceCache */
-    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?: {
-        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(): BootstrapFetcher;
-    /**
-     * 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
-     * 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;
-    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: BootstrapFetcher, 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>;
-    /**
-     * 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.
-     *
-     * 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;
-    /**
-     * 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>;
-    /**
-     * 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
-     *  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>;
-    /**
-     * Apply a single inbound delta from the WebSocket to the local store.
-     *
-     * 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.
-     *
-     * 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 reportId or title), and an explicit null is kept as a value,
-     * clearing that 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: SyncDeltaAction;
-        modelName: string;
-        modelId: string;
-        data: ModelData | null;
-    }): Promise<{
-        action: 'add' | 'update' | 'remove' | 'archive' | 'verify';
-        modelName: string;
-        modelId: string;
-        data?: ModelData | null;
-    }>;
-    /**
-     * 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.
-     *
-     * 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.
-     *
-     * 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: {
-        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: SyncDeltaAction;
-        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: {
-            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[]>;
-    /** Read workspace metadata from IndexedDB. Returns null when the database is not open. */
-    getWorkspaceMetadata(): Promise<WorkspaceMetadata | null>;
-    getLastSyncId(): Promise<number>;
-    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>;
-    /** Persist one burst of journal rows in a single strict durability group. */
-    saveTransactions(transactions: readonly PersistedTransaction[]): Promise<void>;
-    removeTransaction(id: string): Promise<void>;
-    getPersistedTransactions(): Promise<PersistedTransaction[]>;
-    getPersistedTransaction(id: string): Promise<PersistedTransaction | undefined>;
-    /**
-     * Atomically seal one exact commit request and consume the staged mutation
-     * records it replaces. The read, optional add, and deletes share one strict
-     * IndexedDB transaction, so a crash can expose the staged records or the
-     * sealed envelope, never a missing handoff. Returns the pre-existing record
-     * when the envelope id was already sealed (retry/re-entrant call).
-     */
-    sealTransactionRecord(record: PersistedTransaction, consumedRecordIds: readonly string[]): Promise<PersistedTransaction | undefined>;
-    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;
-            readiness: {
-                ready: number;
-                notReady: number;
-            };
-            totalRecords: number;
-            storeDetails: {
-                modelName: string;
-                storeName: string;
-                strategy: LoadStrategy;
-                ready: boolean;
-                count: number;
-            }[];
-        };
-        metadata: WorkspaceMetadata | null;
-    }>;
-    /**
-     * Lifecycle
-     */
-    isOpen(): boolean;
-    close(): Promise<void>;
-    clear(options?: {
-        includeWriteJournal?: boolean;
-    }): Promise<void>;
-}