@tanstack/db-sqlite-persistence-core 0.4.7 → 0.4.9

package/dist/cjs/sqlite-core-adapter.d.cts

@@ -1,5 +1,5 @@
 import { LoadSubsetOptions } from '@tanstack/db';
-import { HydrationPersistenceAdapter, PersistedIndexSpec, PersistedKeySetEvidence, PersistedRowScanOptions, PersistedScannedRow, PersistedTx, PersistenceAdapter, ReplayableTxDelta, SQLiteDriver } from './persisted.cjs';
+import { CommittedTxAnchor, HydrationPersistenceAdapter, PersistedCacheGenerationClaim, PersistedIndexSpec, PersistedKeySetEvidence, PersistedRowScanOptions, PersistedScannedRow, PersistedStorageTarget, PersistedTx, PersistenceAdapter, ReconciledCommittedTx, ReplayableTxDelta, SQLiteDriver } from './persisted.cjs';
 type SQLiteCoreAdapterSchemaMismatchPolicy = `sync-present-reset` | `sync-absent-error` | `reset`;
 export type SQLiteCoreAdapterOptions = {
     driver: SQLiteDriver;
@@ -8,6 +8,10 @@ export type SQLiteCoreAdapterOptions = {
     appliedTxPruneMaxRows?: number;
     appliedTxPruneMaxAgeSeconds?: number;
     pullSinceReloadThreshold?: number;
+    /** Milliseconds without renewal before a sync run loses cache access. */
+    cacheGenerationClaimTtlMs?: number;
+    /** Host clock, injectable for expiry histories. */
+    now?: () => number;
 };
 export type SQLitePullSinceResult<TKey extends string | number> = {
     latestRowVersion: number;
@@ -19,6 +23,7 @@ export type SQLitePullSinceResult<TKey extends string | number> = {
     deletedKeys: Array<TKey>;
     deltas: Array<ReplayableTxDelta<Record<string, unknown>, TKey>>;
 };
+export declare const DEFAULT_CACHE_GENERATION_CLAIM_TTL_MS: number;
 /**
  * Default cap on retained `applied_tx` rows per collection. The log is a
  * replayable cache, so a bounded row count keeps SQLite files from growing
@@ -43,9 +48,21 @@ export declare class SQLiteCorePersistenceAdapter implements PersistenceAdapter
     private readonly appliedTxPruneMaxAgeSeconds;
     private readonly pullSinceReloadThreshold;
     private readonly replacementBatchSize;
+    private readonly cacheGenerationClaimTtlMs;
+    private readonly now;
     private initialized;
     private readonly collectionTableCache;
     private readonly collectionTableLoads;
+    claimCacheGeneration(collectionId: string): Promise<PersistedCacheGenerationClaim>;
+    rotateCacheGeneration(collectionId: string, claimId: string, resetMetadata?: {
+        key: string;
+        value: unknown;
+    }, expectedStorageCollectionId?: string): Promise<PersistedCacheGenerationClaim>;
+    releaseCacheGenerationClaim(claimId: string): Promise<void>;
+    renewCacheGenerationClaim(storageCollectionId: string, claimId: string): Promise<number | undefined>;
+    private renewCacheGenerationClaimUnscheduled;
+    private collectRetiredCacheGenerations;
+    getCacheGenerationNow(): number;
     constructor(options: SQLiteCoreAdapterOptions);
     runInHydrationScope<T>(task: (adapter: HydrationPersistenceAdapter) => Promise<T>): Promise<T>;
     runInRegularScope<T>(task: (adapter: HydrationPersistenceAdapter) => Promise<T>): Promise<T>;
@@ -54,17 +71,20 @@ export declare class SQLiteCorePersistenceAdapter implements PersistenceAdapter
     private resolveScheduler;
     private runInTransaction;
     private assertCurrentSchemaVersion;
-    loadSubset(collectionId: string, options: LoadSubsetOptions, ctx?: {
+    private assertCacheGenerationReadClaim;
+    loadSubset(target: PersistedStorageTarget, options: LoadSubsetOptions, ctx?: {
         requiredIndexSignatures?: ReadonlyArray<string>;
+        cacheGenerationClaimId?: string;
     }): Promise<Array<{
         key: string | number;
         value: Record<string, unknown>;
         metadata?: unknown;
     }>>;
     private loadSubsetUnscheduled;
-    loadResumeSnapshot(collectionId: string, ctx?: {
+    loadResumeSnapshot(target: PersistedStorageTarget, ctx?: {
         requiredIndexSignatures?: ReadonlyArray<string>;
         includeRows?: boolean;
+        cacheGenerationClaimId?: string;
     }): Promise<{
         rows: Array<{
             key: string | number;
@@ -82,20 +102,41 @@ export declare class SQLiteCorePersistenceAdapter implements PersistenceAdapter
         resetEpoch: number;
     }>;
     private loadResumeSnapshotUnscheduled;
-    applyCommittedTx(collectionId: string, tx: PersistedTx): Promise<void>;
+    applyCommittedTx(target: PersistedStorageTarget, tx: PersistedTx): Promise<void>;
+    reconcileCommittedTx(target: PersistedStorageTarget, tx: PersistedTx, anchor: CommittedTxAnchor): Promise<ReconciledCommittedTx>;
     private applyCommittedTxUnscheduled;
-    loadCollectionMetadata(collectionId: string): Promise<Array<{
+    private reconcileCommittedTxUnscheduled;
+    private applyCommittedTxInternal;
+    loadCollectionMetadata(target: PersistedStorageTarget, ctx?: {
+        cacheGenerationClaimId?: string;
+    }): Promise<Array<{
         key: string;
         value: unknown;
     }>>;
     private loadCollectionMetadataUnscheduled;
-    scanRows(collectionId: string, options?: PersistedRowScanOptions): Promise<Array<PersistedScannedRow>>;
+    scanRows(target: PersistedStorageTarget, options?: PersistedRowScanOptions, ctx?: {
+        cacheGenerationClaimId?: string;
+    }): Promise<Array<PersistedScannedRow>>;
     private scanRowsUnscheduled;
-    ensureIndex(collectionId: string, signature: string, spec: PersistedIndexSpec): Promise<void>;
+    ensureIndex(target: PersistedStorageTarget, signature: string, spec: PersistedIndexSpec, ctx?: {
+        cacheGenerationClaimId?: string;
+    }): Promise<void>;
     private ensureIndexUnscheduled;
-    markIndexRemoved(collectionId: string, signature: string): Promise<void>;
+    markIndexRemoved(target: PersistedStorageTarget, signature: string, ctx?: {
+        cacheGenerationClaimId?: string;
+    }): Promise<void>;
     private markIndexRemovedUnscheduled;
-    getStreamPosition(collectionId: string): Promise<{
+    reserveLeadershipTerm(target: PersistedStorageTarget, observedTerm: number, ctx?: {
+        cacheGenerationClaimId?: string;
+    }): Promise<{
+        latestTerm: number;
+        latestSeq: number;
+        latestRowVersion: number;
+    }>;
+    private reserveLeadershipTermUnscheduled;
+    getStreamPosition(target: PersistedStorageTarget, ctx?: {
+        cacheGenerationClaimId?: string;
+    }): Promise<{
         latestTerm: number;
         latestSeq: number;
         latestRowVersion: number;
@@ -104,7 +145,9 @@ export declare class SQLiteCorePersistenceAdapter implements PersistenceAdapter
     private readLatestRowVersion;
     private readStreamPosition;
     private readKeySetEvidence;
-    pullSince(collectionId: string, fromRowVersion: number): Promise<SQLitePullSinceResult<string | number>>;
+    pullSince(target: PersistedStorageTarget, fromRowVersion: number, ctx?: {
+        cacheGenerationClaimId?: string;
+    }): Promise<SQLitePullSinceResult<string | number>>;
     private pullSinceUnscheduled;
     private loadSubsetInternal;
     private applyInMemoryWhere;

package/dist/esm/broadcast-coordinator.d.ts

@@ -1,8 +1,10 @@
 import { LoadSubsetOptions } from '@tanstack/db';
 import { RemoteSubsetOwner } from './remote-subset-owner.js';
-import { ApplyCommittedTxResponse, ApplyLocalMutationsResponse, HydrationPersistenceAdapter, PersistedCollectionCoordinator, PersistedIndexSpec, PersistedMutationEnvelope, PersistedTx, PersistenceAdapter, ProtocolEnvelope, PullSinceResponse } from './persisted.js';
-type CoordinatorAdapter = Pick<PersistenceAdapter, `loadSubset` | `applyCommittedTx` | `ensureIndex` | `runInRegularScope`> & {
-    pullSince?: (collectionId: string, fromRowVersion: number) => Promise<{
+import { ApplyCommittedTxResponse, ApplyLocalMutationsResponse, CommittedTxAnchor, HydrationPersistenceAdapter, PersistedCollectionCoordinator, PersistedIndexSpec, PersistedMutationEnvelope, PersistedStorageTarget, PersistedTx, PersistenceAdapter, ProtocolEnvelope, PullSinceResponse, ReconcileCommittedTxResponse } from './persisted.js';
+type CoordinatorAdapter = Pick<PersistenceAdapter, `loadSubset` | `applyCommittedTx` | `reconcileCommittedTx` | `ensureIndex` | `runInRegularScope`> & {
+    pullSince?: (target: PersistedStorageTarget, fromRowVersion: number, ctx?: {
+        cacheGenerationClaimId?: string;
+    }) => Promise<{
         latestRowVersion: number;
         requiresFullReload: true;
     } | {
@@ -11,7 +13,16 @@ type CoordinatorAdapter = Pick<PersistenceAdapter, `loadSubset` | `applyCommitte
         changedKeys: Array<string | number>;
         deletedKeys: Array<string | number>;
     }>;
-    getStreamPosition?: (collectionId: string) => Promise<{
+    getStreamPosition?: (target: PersistedStorageTarget, ctx?: {
+        cacheGenerationClaimId?: string;
+    }) => Promise<{
+        latestTerm: number;
+        latestSeq: number;
+        latestRowVersion: number;
+    }>;
+    reserveLeadershipTerm?: (target: PersistedStorageTarget, observedTerm: number, ctx?: {
+        cacheGenerationClaimId?: string;
+    }) => Promise<{
         latestTerm: number;
         latestSeq: number;
         latestRowVersion: number;
@@ -30,6 +41,7 @@ export declare class BroadcastCollectionCoordinator implements PersistedCollecti
     private readonly coordinatorName;
     private defaultAdapter;
     private readonly collectionAdapters;
+    private readonly collectionClaimIds;
     private readonly remoteSubsetOwners;
     private readonly remoteSubsetIds;
     private readonly outboundRemoteSubsetAcquisitions;
@@ -56,7 +68,7 @@ export declare class BroadcastCollectionCoordinator implements PersistedCollecti
      */
     setAdapter(adapter: CoordinatorAdapter): void;
     /** Register the persistence adapter that owns one collection. */
-    setAdapterForCollection(collectionId: string, adapter: CoordinatorAdapter): void;
+    setAdapterForCollection(collectionId: string, adapter: CoordinatorAdapter, cacheGenerationClaimId?: string): void;
     registerRemoteSubsetOwner(collectionId: string, owner: RemoteSubsetOwner): () => void;
     getNodeId(): string;
     subscribe(collectionId: string, onMessage: (message: ProtocolEnvelope<unknown>) => void): () => void;
@@ -65,11 +77,13 @@ export declare class BroadcastCollectionCoordinator implements PersistedCollecti
     ensureLeadership(collectionId: string): Promise<void>;
     requestEnsureRemoteSubset(collectionId: string, options: LoadSubsetOptions): Promise<void>;
     requestReleaseRemoteSubset(collectionId: string, options: LoadSubsetOptions): Promise<void>;
+    private scheduleRemoteSubsetReleaseRetry;
     private acquireRemoteSubset;
-    requestEnsurePersistedIndex(collectionId: string, signature: string, spec: PersistedIndexSpec, scopedAdapter?: HydrationPersistenceAdapter, localEnsureCompleted?: boolean): Promise<void>;
-    requestApplyLocalMutations(collectionId: string, mutations: Array<PersistedMutationEnvelope>): Promise<ApplyLocalMutationsResponse>;
+    requestEnsurePersistedIndex(collectionId: string, signature: string, spec: PersistedIndexSpec, scopedAdapter?: HydrationPersistenceAdapter, localEnsureCompleted?: boolean, cacheGenerationClaimId?: string): Promise<void>;
+    requestApplyLocalMutations(collectionId: string, mutations: Array<PersistedMutationEnvelope>, cacheGenerationClaimId?: string): Promise<ApplyLocalMutationsResponse>;
     requestApplyCommittedTx(collectionId: string, tx: PersistedTx, scopedAdapter?: HydrationPersistenceAdapter): Promise<ApplyCommittedTxResponse>;
-    pullSince(collectionId: string, fromRowVersion: number, scopedAdapter?: HydrationPersistenceAdapter): Promise<PullSinceResponse>;
+    reconcileCommittedTx(collectionId: string, tx: PersistedTx, anchor: CommittedTxAnchor, scopedAdapter?: HydrationPersistenceAdapter): Promise<ReconcileCommittedTxResponse>;
+    pullSince(collectionId: string, fromRowVersion: number, scopedAdapter?: HydrationPersistenceAdapter, cacheGenerationClaimId?: string): Promise<PullSinceResponse>;
     dispose(): void;
     private getOrCreateCollectionState;
     private ensureCollectionState;
@@ -105,6 +119,9 @@ export declare class BroadcastCollectionCoordinator implements PersistedCollecti
     private handleApplyCommittedTx;
     private runDeduplicatedEnvelope;
     private applyCommittedTxOnce;
+    private publishCommittedTx;
+    private handleReconcileCommittedTx;
+    private nextPersistedTxIfLeader;
     private applyDurablyAtNextStreamPosition;
     private handlePullSince;
     private withScheduledWriterLock;