@abloatai/humans 0.37.0

package/dist/local/Database.d.ts

@@ -0,0 +1,322 @@
+/**
+ * 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 './stores/DatabaseManager.js';
+import type { PersistenceIdentity } from './stores/persistenceIdentity.js';
+import { ModelRegistry } from './ModelRegistry.js';
+import { LoadStrategy } from '@abloatai/transaction/types';
+import type { RuntimeContext } from './RuntimeContext.js';
+import type { AppliedChange } from '../plugin.js';
+import type { BootstrapFetcher, BootstrapData } from './sync/BootstrapFetcher.js';
+import { InMemoryObjectStore } from './adapters/inMemoryStorage.js';
+import type { SyncDeltaAction } from '@abloatai/transaction/wire/delta';
+import type { OnStaleMode } from '@abloatai/transaction/coordination/schema';
+import type { BootstrapType } from '@abloatai/transaction/types';
+/** 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?: AppliedChange[];
+}
+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;
+    private readonly runtime;
+    /** 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;
+        runtime?: RuntimeContext;
+    });
+    /**
+     * 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(identity: PersistenceIdentity, 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;
+    }, options?: {
+        updateCursor?: boolean;
+    }): Promise<AppliedChange>;
+    /**
+     * 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: AppliedChange[];
+        /**
+         * 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>;
+    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;
+    }>;
+    isOpen(): boolean;
+    close(): Promise<void>;
+    /** Delegate authenticated local-state teardown to the persistence owner. */
+    purgePersistence(): Promise<void>;
+    clear(options?: {
+        includeWriteJournal?: boolean;
+    }): Promise<void>;
+}