/** * Storage adapter types for local persistence */ export type DatafnHydrationState = "notStarted" | "hydrating" | "ready"; /** * Factory function for creating storage adapters with namespace-based isolation. * Used for multi-user/multi-tenant data isolation. * * @example * ```typescript * const storageFactory: DatafnStorageFactory = (namespace) => { * return IndexedDbStorageAdapter.createForNamespace("my-app", namespace); * }; * ``` */ export type DatafnStorageFactory = ( namespace: string, ) => DatafnStorageAdapter; export type DatafnChangelogEntry = { /** Monotonic local sequence (assigned by storage adapter). */ seq: number; clientId: string; mutationId: string; mutation: Record; timestampMs: number; /** Actor ID for audit attribution (when available) - AUD-001 */ actorId?: string; /** ISO 8601 timestamp - AUD-001 */ timestamp?: string; }; export interface DatafnStorageAdapterCapabilities { /** * `mergeRecord` atomically chooses between applying `partial` to an existing * record and creating a missing record from the complete `options.ifMissing` * payload. It must not reapply `partial` to that creation payload. */ readonly atomicMergeIfMissing?: boolean; /** * `mergeRecord` calls `options.onResolved` inside its atomic write with * whether it created the record. Callers pass the callback only to * adapters that set this. */ readonly reportsMergeOutcome?: boolean; } export interface DatafnStorageAdapter { readonly capabilities?: DatafnStorageAdapterCapabilities; // Records (by resource) getRecord( resource: string, id: string, ): Promise | null>; listRecords(resource: string): Promise[]>; upsertRecord( resource: string, record: Record, ): Promise; /** * Optional bulk upsert. Adapters that implement it write all records in one * backend transaction; callers fall back to `upsertRecord` per record. */ upsertRecords?( resource: string, records: Array>, ): Promise; deleteRecord(resource: string, id: string): Promise; /** * Atomic read-modify-write merge. MUST be linearizable across every adapter * instance through a backend transaction or equivalent coordination primitive. * If the record does not exist, creates from `options.ifMissing` when * supplied, otherwise from `partial`. * Uses one-level-deep merge for object-type fields. */ mergeRecord( resource: string, id: string, partial: Record, options?: { /** Complete creation payload used instead of `partial` when absent. */ ifMissing?: Record; /** * Called inside the atomic read-modify-write with whether the record * was missing and has been created. Passed only to adapters that set * `capabilities.reportsMergeOutcome`. */ onResolved?: (outcome: { created: boolean }) => void; }, ): Promise>; // Join rows (many-many) listJoinRows(relationKey: string): Promise>>; getJoinRows( relationKey: string, fromId: string, ): Promise>>; getJoinRowsInverse( relationKey: string, toId: string, ): Promise>>; upsertJoinRow( relationKey: string, row: Record, ): Promise; setJoinRows( relationKey: string, rows: Array>, ): Promise; deleteJoinRow(relationKey: string, from: string, to: string): Promise; // Convenience query findRecords( resource: string, field: string, value: unknown, ): Promise[]>; // Sync state getCursor(resource: string): Promise; setCursor(resource: string, cursor: string | null): Promise; getHydrationState(resource: string): Promise; setHydrationState( resource: string, state: DatafnHydrationState, ): Promise; // Offline change log changelogAppend( entry: Omit, ): Promise; changelogList(options?: { limit?: number }): Promise; changelogAck(options: { throughSeq: number }): Promise; /** * Largest sequence number in the changelog, or null when it is empty. * Optional; callers fall back to listing the changelog. */ changelogLastSeq?(): Promise; // Counts for reconcile (SYNC-007) countRecords(resource: string): Promise; countJoinRows(relationKey: string): Promise; // Lifecycle (CLN-001, CLN-002) /** Close all connections and release resources. */ close(): Promise; /** Delete all data across all stores. */ clearAll(): Promise; // Health check (HEAL-001) /** * Health check: verify core stores exist and are accessible. * Returns { ok: true, issues: [] } when healthy. * Returns { ok: false, issues: [...] } when corrupted or inaccessible. */ healthCheck(): Promise<{ ok: boolean; issues: string[] }>; }