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

package/dist/esm/index.js

@@ -1,12 +1,13 @@
-import { SQLITE_DRIVER_SHARED_LOGICAL_SCHEDULING_KEY, SingleProcessCoordinator, createPersistedTableName, decodePersistedStorageKey, encodePersistedStorageKey, forwardSQLiteDriverSharedLogicalScheduling, persistedCollectionOptions, validatePersistedCollectionCoordinator } from "./persisted.js";
+import { SQLITE_DRIVER_SHARED_LOGICAL_SCHEDULING_KEY, SingleProcessCoordinator, createPersistedTableName, decodePersistedStorageKey, eagerStorageTarget, encodePersistedStorageKey, forwardSQLiteDriverSharedLogicalScheduling, managedStorageTarget, persistedCollectionOptions, resolvePersistedStorageTarget, validatePersistedCollectionCoordinator } from "./persisted.js";
 import { DuplicateRemoteSubsetOwnerError, IndeterminateCommitError, InvalidPersistedCollectionConfigError, InvalidPersistedCollectionCoordinatorError, InvalidPersistedStorageKeyEncodingError, InvalidPersistedStorageKeyError, InvalidPersistenceAdapterError, InvalidSyncConfigError, PersistedCollectionCoreError, PersistedCollectionDurabilityError, PersistenceUnavailableError, RetryableRemoteSubsetAcquisitionError, SQLiteBigIntOutOfRangeError, toPersistedCollectionDurabilityError } from "./errors.js";
-import { DEFAULT_APPLIED_TX_PRUNE_MAX_AGE_SECONDS, DEFAULT_APPLIED_TX_PRUNE_MAX_ROWS, SQLiteCorePersistenceAdapter, createSQLiteCorePersistenceAdapter } from "./sqlite-core-adapter.js";
+import { DEFAULT_APPLIED_TX_PRUNE_MAX_AGE_SECONDS, DEFAULT_APPLIED_TX_PRUNE_MAX_ROWS, DEFAULT_CACHE_GENERATION_CLAIM_TTL_MS, SQLiteCorePersistenceAdapter, createSQLiteCorePersistenceAdapter } from "./sqlite-core-adapter.js";
 import { PERSISTED_TYPE_TAG, PERSISTED_VALUE_TAG, SQLITE_BIGINT_MAX, SQLITE_BIGINT_MIN, assertSQLiteBigIntInRange, reviveSQLiteTemporal, serializeSQLiteBigInt, serializeSQLiteTemporal, sqliteTemporalIdentity, sqliteTemporalKind } from "./sqlite-value.js";
 import { RemoteSubsetWireValueError, toProcessLocalLoadSubsetOptions, toTransportedLoadSubsetOptions, validateRemoteSubsetOptions } from "./remote-subset-wire.js";
 import { safeRandomUUID } from "@tanstack/db";
 export {
   DEFAULT_APPLIED_TX_PRUNE_MAX_AGE_SECONDS,
   DEFAULT_APPLIED_TX_PRUNE_MAX_ROWS,
+  DEFAULT_CACHE_GENERATION_CLAIM_TTL_MS,
   DuplicateRemoteSubsetOwnerError,
   IndeterminateCommitError,
   InvalidPersistedCollectionConfigError,
@@ -32,9 +33,12 @@ export {
   createPersistedTableName,
   createSQLiteCorePersistenceAdapter,
   decodePersistedStorageKey,
+  eagerStorageTarget,
   encodePersistedStorageKey,
   forwardSQLiteDriverSharedLogicalScheduling,
+  managedStorageTarget,
   persistedCollectionOptions,
+  resolvePersistedStorageTarget,
   reviveSQLiteTemporal,
   safeRandomUUID,
   serializeSQLiteBigInt,

package/dist/esm/persisted.d.ts

@@ -49,6 +49,7 @@ export type TxCommitted = {
     latestRowVersion: number;
 } & ({
     requiresFullReload: true;
+    reconciliationReload?: true;
 } | {
     requiresFullReload: false;
     changedRows: Array<{
@@ -149,6 +150,41 @@ export type ApplyCommittedTxResponse = {
     sourceCode?: string | number;
     path?: string | ReadonlyArray<string | number>;
 };
+/** The durable version read before a source transaction enters coordination. */
+export type CommittedTxAnchor = {
+    latestRowVersion: number;
+    resetEpoch: number;
+};
+export type ReconcileCommittedTxResponse = {
+    type: `rpc:reconcileCommittedTx:res`;
+    rpcId: string;
+    ok: true;
+    alreadyApplied: boolean;
+    committed: {
+        term: number;
+        seq: number;
+        rowVersion: number;
+    };
+} | {
+    type: `rpc:reconcileCommittedTx:res`;
+    rpcId: string;
+    ok: false;
+    code: `NOT_LEADER` | `UNDETERMINED` | `PERSISTENCE_ERROR`;
+    error: string;
+    sourceCode?: string | number;
+    path?: string | ReadonlyArray<string | number>;
+};
+export type ReconciledCommittedTx = {
+    kind: `already-applied` | `applied-now`;
+    committed: {
+        term: number;
+        seq: number;
+        rowVersion: number;
+    };
+    latestRowVersion: number;
+} | {
+    kind: `unknown`;
+};
 export type PullSinceRequest = {
     type: `rpc:pullSince:req`;
     rpcId: string;
@@ -223,6 +259,27 @@ export type PersistedScannedRow<T extends object = Record<string, unknown>, TKey
 };
 export type PersistedRowScanOptions = SyncPersistenceScanOptions;
 export type PersistedKeySetEvidence = SyncPersistenceKeySetEvidence;
+export type PersistedCacheGenerationClaim = {
+    storageCollectionId: string;
+    claimId: string;
+    /** Present when the adapter expires dormant claims. */
+    expiresAtMs?: number;
+};
+/** An eager Collection name or a claim-bound persisted cache generation. */
+export type PersistedStorageTarget = {
+    kind: `eager`;
+    collectionId: string;
+} | {
+    kind: `managed`;
+    storageCollectionId: string;
+    claimId: string;
+};
+export declare function eagerStorageTarget(collectionId: string): PersistedStorageTarget;
+export declare function managedStorageTarget(storageCollectionId: string, claimId: string): PersistedStorageTarget;
+export declare function resolvePersistedStorageTarget(target: PersistedStorageTarget, legacyClaimId?: string): {
+    collectionId: string;
+    claimId?: string;
+};
 export type PersistencePullSinceResult = {
     latestRowVersion: number;
     requiresFullReload: true;
@@ -238,6 +295,8 @@ export type PersistedTx<T extends object = Record<string, unknown>, TKey extends
     term: number;
     seq: number;
     rowVersion: number;
+    /** Claim authorizing this transaction's persisted cache generation. */
+    cacheGenerationClaimId?: string;
     truncate?: boolean;
     mutations: Array<{
         type: `insert`;
@@ -272,16 +331,18 @@ export type PersistedTx<T extends object = Record<string, unknown>, TKey extends
  */
 export declare const SQLITE_DRIVER_SHARED_LOGICAL_SCHEDULING_KEY: unique symbol;
 export interface PersistenceAdapter {
-    loadSubset: (collectionId: string, options: LoadSubsetOptions, ctx?: {
+    loadSubset: (target: PersistedStorageTarget, options: LoadSubsetOptions, ctx?: {
         requiredIndexSignatures?: ReadonlyArray<string>;
+        cacheGenerationClaimId?: string;
     }) => Promise<Array<{
         key: string | number;
         value: Record<string, unknown>;
         metadata?: unknown;
     }>>;
-    loadResumeSnapshot: (collectionId: string, ctx?: {
+    loadResumeSnapshot: (target: PersistedStorageTarget, ctx?: {
         requiredIndexSignatures?: ReadonlyArray<string>;
         includeRows?: boolean;
+        cacheGenerationClaimId?: string;
     }) => Promise<{
         rows: Array<{
             key: string | number;
@@ -298,15 +359,43 @@ export interface PersistenceAdapter {
         latestRowVersion: number;
         resetEpoch: number;
     }>;
-    applyCommittedTx: (collectionId: string, tx: PersistedTx) => Promise<void>;
-    loadCollectionMetadata?: (collectionId: string) => Promise<Array<{
+    applyCommittedTx: (target: PersistedStorageTarget, tx: PersistedTx) => Promise<void>;
+    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>;
+    getCacheGenerationNow?: () => number;
+    /** Atomically certify or apply one source transaction after a lost response. */
+    reconcileCommittedTx?: (target: PersistedStorageTarget, tx: PersistedTx, anchor: CommittedTxAnchor) => Promise<ReconciledCommittedTx>;
+    loadCollectionMetadata?: (target: PersistedStorageTarget, ctx?: {
+        cacheGenerationClaimId?: string;
+    }) => Promise<Array<{
         key: string;
         value: unknown;
     }>>;
-    scanRows?: (collectionId: string, options?: PersistedRowScanOptions) => Promise<Array<PersistedScannedRow>>;
-    ensureIndex: (collectionId: string, signature: string, spec: PersistedIndexSpec) => Promise<void>;
-    markIndexRemoved?: (collectionId: string, signature: string) => Promise<void>;
-    getStreamPosition?: (collectionId: string) => Promise<{
+    scanRows?: (target: PersistedStorageTarget, options?: PersistedRowScanOptions, ctx?: {
+        cacheGenerationClaimId?: string;
+    }) => Promise<Array<PersistedScannedRow>>;
+    ensureIndex: (target: PersistedStorageTarget, signature: string, spec: PersistedIndexSpec, ctx?: {
+        cacheGenerationClaimId?: string;
+    }) => Promise<void>;
+    markIndexRemoved?: (target: PersistedStorageTarget, signature: string, ctx?: {
+        cacheGenerationClaimId?: string;
+    }) => Promise<void>;
+    getStreamPosition?: (target: PersistedStorageTarget, ctx?: {
+        cacheGenerationClaimId?: string;
+    }) => Promise<{
+        latestTerm: number;
+        latestSeq: number;
+        latestRowVersion: number;
+    }>;
+    /** Reserve a new durable election term before announcing Browser leadership. */
+    reserveLeadershipTerm?: (target: PersistedStorageTarget, observedTerm: number, ctx?: {
+        cacheGenerationClaimId?: string;
+    }) => Promise<{
         latestTerm: number;
         latestSeq: number;
         latestRowVersion: number;
@@ -323,7 +412,9 @@ export interface PersistenceAdapter {
     isHydrationScopeScheduled?: () => boolean;
 }
 export type HydrationPersistenceAdapter = PersistenceAdapter & {
-    pullSince?: (collectionId: string, fromRowVersion: number) => Promise<PersistencePullSinceResult>;
+    pullSince?: (target: PersistedStorageTarget, fromRowVersion: number, ctx?: {
+        cacheGenerationClaimId?: string;
+    }) => Promise<PersistencePullSinceResult>;
 };
 export type { RemoteSubsetOwner } from './remote-subset-owner.js';
 export interface SQLiteDriver {
@@ -343,7 +434,7 @@ export interface SQLiteDriver {
 export declare function forwardSQLiteDriverSharedLogicalScheduling<TDriver extends SQLiteDriver>(source: SQLiteDriver, wrapper: TDriver): TDriver;
 export interface PersistedCollectionCoordinator {
     getNodeId: () => string;
-    setAdapterForCollection?: (collectionId: string, adapter: PersistenceAdapter) => void;
+    setAdapterForCollection?: (collectionId: string, adapter: PersistenceAdapter, cacheGenerationClaimId?: string) => void;
     subscribe: (collectionId: string, onMessage: (message: ProtocolEnvelope<unknown>) => void) => () => void;
     publish: (collectionId: string, message: ProtocolEnvelope<unknown>) => void;
     isLeader: (collectionId: string) => boolean;
@@ -356,8 +447,8 @@ export interface PersistedCollectionCoordinator {
      * and is never serialized to a follower. `localEnsureCompleted` lets the
      * built-in leader avoid repeating successful local work.
      */
-    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>;
     /**
      * Applies a committed transaction through the supplied adapter when present.
      * Wrappers must forward this leader-local loan: scheduling it again can wait
@@ -365,8 +456,10 @@ export interface PersistedCollectionCoordinator {
      * loan after the call; ordinary work uses the registered collection adapter.
      */
     requestApplyCommittedTx: (collectionId: string, tx: PersistedTx, scopedAdapter?: HydrationPersistenceAdapter) => Promise<ApplyCommittedTxResponse>;
+    /** Available only when the elected adapter can certify the durable outcome. */
+    reconcileCommittedTx?: (collectionId: string, tx: PersistedTx, anchor: CommittedTxAnchor, scopedAdapter?: HydrationPersistenceAdapter) => Promise<ReconcileCommittedTxResponse>;
     /** The scoped adapter is leader-local and is never serialized to a follower. */
-    pullSince?: (collectionId: string, fromRowVersion: number, scopedAdapter?: HydrationPersistenceAdapter) => Promise<PullSinceResponse>;
+    pullSince?: (collectionId: string, fromRowVersion: number, scopedAdapter?: HydrationPersistenceAdapter, cacheGenerationClaimId?: string) => Promise<PullSinceResponse>;
 }
 export interface PersistedCollectionPersistence {
     adapter: PersistenceAdapter;