@tanstack/db-sqlite-persistence-core 0.2.20 → 0.2.23

package/dist/cjs/persisted.d.cts

@@ -248,6 +248,7 @@ export interface PersistedCollectionUtils extends UtilsRecord {
         mutations: Array<PendingMutation<Record<string, unknown>>>;
     }) => Promise<void> | void;
     getLeadershipState?: () => PersistedCollectionLeadershipState;
+    /** Hydrate once without acquiring a new ongoing subset lease. */
     forceReloadSubset?: (options: LoadSubsetOptions) => Promise<void> | void;
 }
 export type PersistedSyncWrappedOptions<T extends object, TKey extends string | number, TSchema extends StandardSchemaV1 = never, TUtils extends UtilsRecord = UtilsRecord> = CollectionConfig<T, TKey, TSchema, TUtils> & {

package/dist/esm/persisted.d.ts

@@ -248,6 +248,7 @@ export interface PersistedCollectionUtils extends UtilsRecord {
         mutations: Array<PendingMutation<Record<string, unknown>>>;
     }) => Promise<void> | void;
     getLeadershipState?: () => PersistedCollectionLeadershipState;
+    /** Hydrate once without acquiring a new ongoing subset lease. */
     forceReloadSubset?: (options: LoadSubsetOptions) => Promise<void> | void;
 }
 export type PersistedSyncWrappedOptions<T extends object, TKey extends string | number, TSchema extends StandardSchemaV1 = never, TUtils extends UtilsRecord = UtilsRecord> = CollectionConfig<T, TKey, TSchema, TUtils> & {

package/dist/esm/persisted.js

@@ -163,15 +163,6 @@ function toStableSerializable(value) {
 function stableSerialize(value) {
   return JSON.stringify(toStableSerializable(value) ?? null);
 }
-function normalizeSubsetOptionsForKey(options) {
-  return {
-    where: toStableSerializable(options.where),
-    orderBy: toStableSerializable(options.orderBy),
-    limit: options.limit,
-    cursor: toStableSerializable(options.cursor),
-    offset: options.offset
-  };
-}
 function normalizeSyncFnResult(result) {
   if (typeof result === `function`) {
     return { cleanup: result };
@@ -218,7 +209,7 @@ class PersistedCollectionRuntime {
     this.pendingRemoteSubsetEnsures = /* @__PURE__ */ new Map();
     this.queuedHydrationTransactions = [];
     this.queuedTxCommitted = [];
-    this.subscriptionIds = /* @__PURE__ */ new WeakMap();
+    this.requestIds = /* @__PURE__ */ new WeakMap();
     this.collection = null;
     this.syncControls = {
       begin: null,
@@ -230,15 +221,17 @@ class PersistedCollectionRuntime {
     this.started = false;
     this.startupMetadataPromise = null;
     this.startPromise = null;
+    this.resumeBaselinePromise = null;
+    this.lifecycleGeneration = 0;
     this.internalApplyDepth = 0;
     this.appliedReceiptSequence = 0;
     this.pendingAppliedReceipts = /* @__PURE__ */ new Map();
-    this.isHydrating = false;
+    this.hydratingGeneration = null;
     this.coordinatorUnsubscribe = null;
     this.indexAddedUnsubscribe = null;
     this.indexRemovedUnsubscribe = null;
     this.remoteEnsureRetryTimer = null;
-    this.nextSubscriptionId = 0;
+    this.nextRequestId = 0;
     this.latestTerm = 0;
     this.latestSeq = 0;
     this.latestRowVersion = 0;
@@ -247,6 +240,7 @@ class PersistedCollectionRuntime {
     this.localRowVersion = 0;
   }
   setSyncControls(syncControls) {
+    this.advanceLifecycle();
     const commit = syncControls.commit;
     this.syncControls = {
       ...syncControls,
@@ -281,7 +275,7 @@ class PersistedCollectionRuntime {
     };
   }
   isHydratingNow() {
-    return this.isHydrating;
+    return this.hydratingGeneration === this.lifecycleGeneration;
   }
   isApplyingInternally() {
     return this.internalApplyDepth > 0;
@@ -303,49 +297,75 @@ class PersistedCollectionRuntime {
     if (this.startPromise) {
       return this.startPromise;
     }
-    this.startPromise = this.startInternal();
+    const lifecycleGeneration = this.lifecycleGeneration;
+    this.startPromise = this.startInternal(lifecycleGeneration);
     return this.startPromise;
   }
+  ensureResumeBaselineHydrated() {
+    if (this.resumeBaselinePromise) {
+      return this.resumeBaselinePromise;
+    }
+    const lifecycleGeneration = this.lifecycleGeneration;
+    this.resumeBaselinePromise = (async () => {
+      await this.ensureStarted();
+      if (lifecycleGeneration !== this.lifecycleGeneration) return;
+      if (this.syncMode !== `on-demand`) return;
+      await this.hydrateBaseline(lifecycleGeneration);
+    })();
+    return this.resumeBaselinePromise;
+  }
+  async hydrateBaseline(lifecycleGeneration) {
+    if (lifecycleGeneration !== this.lifecycleGeneration) return;
+    const baseline = {};
+    this.activeSubsets.set(this.getSubsetKey(baseline), baseline);
+    const appliedCursor = this.appliedReceiptSequence;
+    await this.applyMutex.run(async () => {
+      if (lifecycleGeneration !== this.lifecycleGeneration) return;
+      await this.hydrateSubsetUnsafe(baseline, {
+        requestRemoteEnsure: false,
+        lifecycleGeneration
+      });
+    });
+    if (lifecycleGeneration !== this.lifecycleGeneration) return;
+    await this.waitForAppliedReceiptsAfter(appliedCursor);
+  }
   async ensureStartupMetadataLoaded() {
     if (this.startupMetadataPromise) {
       return this.startupMetadataPromise;
     }
-    this.startupMetadataPromise = this.loadStartupMetadataInternal();
+    const lifecycleGeneration = this.lifecycleGeneration;
+    this.startupMetadataPromise = this.loadStartupMetadataInternal(lifecycleGeneration);
     return this.startupMetadataPromise;
   }
-  async startInternal() {
+  async startInternal(lifecycleGeneration) {
     if (this.started) {
       return;
     }
     this.started = true;
     await this.ensureStartupMetadataLoaded();
+    if (lifecycleGeneration !== this.lifecycleGeneration) return;
     const indexBootstrapSnapshot = this.collection?.getIndexMetadata() ?? [];
     this.attachIndexLifecycleListeners();
     await this.bootstrapPersistedIndexes(indexBootstrapSnapshot);
+    if (lifecycleGeneration !== this.lifecycleGeneration) return;
     if (this.syncMode !== `on-demand`) {
-      this.activeSubsets.set(this.getSubsetKey({}), {});
-      const appliedCursor = this.appliedReceiptSequence;
-      await this.applyMutex.run(
-        () => this.hydrateSubsetUnsafe({}, { requestRemoteEnsure: false })
-      );
-      await this.waitForAppliedReceiptsAfter(appliedCursor);
+      await this.hydrateBaseline(lifecycleGeneration);
     }
   }
-  async loadStartupMetadataInternal() {
+  async loadStartupMetadataInternal(lifecycleGeneration) {
     if (this.persistence.adapter.getStreamPosition) {
       const position = await this.persistence.adapter.getStreamPosition(
         this.collectionId
       );
+      if (lifecycleGeneration !== this.lifecycleGeneration) return;
       this.observeStreamPosition(
         position.latestTerm,
         position.latestSeq,
         position.latestRowVersion
       );
     }
-    await this.loadCollectionMetadataIntoCollection();
-  }
-  async loadCollectionMetadataIntoCollection() {
     const collectionMetadata = await this.loadCollectionMetadataSnapshot();
+    if (lifecycleGeneration !== this.lifecycleGeneration) return;
     this.replaceCollectionMetadataSnapshot(collectionMetadata);
   }
   async loadCollectionMetadataSnapshot() {
@@ -376,40 +396,43 @@ class PersistedCollectionRuntime {
     });
   }
   async loadSubset(options, upstreamLoadSubset) {
+    const lifecycleGeneration = this.lifecycleGeneration;
     this.activeSubsets.set(this.getSubsetKey(options), options);
     const appliedCursor = this.appliedReceiptSequence;
     await this.applyMutex.run(
       () => this.hydrateSubsetUnsafe(options, {
-        requestRemoteEnsure: this.mode === `sync-present`
+        requestRemoteEnsure: this.mode === `sync-present`,
+        lifecycleGeneration
       })
     );
+    if (lifecycleGeneration !== this.lifecycleGeneration) return;
     await this.waitForAppliedReceiptsAfter(appliedCursor);
     if (upstreamLoadSubset) {
       try {
-        const maybePromise = upstreamLoadSubset(options);
-        if (maybePromise instanceof Promise) {
-          await maybePromise.catch((error) => {
-            console.warn(
-              `Failed to load remote subset in persisted wrapper:`,
-              error
-            );
-            this.queueRemoteSubsetEnsure(options);
-          });
-        }
+        await upstreamLoadSubset(options);
       } catch (error) {
+        if (options.signal?.aborted || typeof error === `object` && error !== null && `name` in error && error.name === `AbortError`) {
+          this.pendingRemoteSubsetEnsures.delete(this.getSubsetKey(options));
+          throw error;
+        }
         console.warn(`Failed to trigger remote subset load:`, error);
         this.queueRemoteSubsetEnsure(options);
+        throw error;
       }
     }
   }
   unloadSubset(options, upstreamUnloadSubset) {
     this.activeSubsets.delete(this.getSubsetKey(options));
+    this.pendingRemoteSubsetEnsures.delete(this.getSubsetKey(options));
     upstreamUnloadSubset?.(options);
   }
   async forceReloadSubset(options) {
-    this.activeSubsets.set(this.getSubsetKey(options), options);
+    const lifecycleGeneration = this.lifecycleGeneration;
     await this.applyMutex.run(
-      () => this.hydrateSubsetUnsafe(options, { requestRemoteEnsure: false })
+      () => this.hydrateSubsetUnsafe(options, {
+        requestRemoteEnsure: false,
+        lifecycleGeneration
+      })
     );
   }
   queueHydrationBufferedTransaction(transaction) {
@@ -499,6 +522,7 @@ class PersistedCollectionRuntime {
     await this.persistAndConfirmCollectionMutations(collectionMutations);
   }
   cleanup() {
+    this.advanceLifecycle();
     this.coordinatorUnsubscribe?.();
     this.coordinatorUnsubscribe = null;
     this.indexAddedUnsubscribe?.();
@@ -517,6 +541,14 @@ class PersistedCollectionRuntime {
     this.queuedHydrationTransactions.length = 0;
     this.queuedTxCommitted.length = 0;
     this.clearSyncControls();
+    this.collection = null;
+  }
+  advanceLifecycle() {
+    this.lifecycleGeneration++;
+    this.started = false;
+    this.startupMetadataPromise = null;
+    this.startPromise = null;
+    this.resumeBaselinePromise = null;
   }
   withInternalApply(task) {
     this.internalApplyDepth++;
@@ -550,12 +582,15 @@ class PersistedCollectionRuntime {
     return this.applyMutex.run(() => this.scanPersistedRowsUnsafe(options));
   }
   async hydrateSubsetUnsafe(options, config) {
-    this.isHydrating = true;
+    this.hydratingGeneration = config.lifecycleGeneration;
     try {
       const rows = await this.loadSubsetRowsUnsafe(options);
+      if (config.lifecycleGeneration !== this.lifecycleGeneration) return;
       this.applyRowsToCollection(rows);
     } finally {
-      this.isHydrating = false;
+      if (this.hydratingGeneration === config.lifecycleGeneration) {
+        this.hydratingGeneration = null;
+      }
     }
     await this.flushQueuedHydrationTransactionsUnsafe();
     await this.flushQueuedTxCommittedUnsafe();
@@ -949,21 +984,15 @@ class PersistedCollectionRuntime {
     };
   }
   getSubsetKey(options) {
-    const subscription = options.subscription;
-    if (subscription && typeof subscription === `object`) {
-      const existingId = this.subscriptionIds.get(subscription);
-      if (existingId) {
-        return existingId;
-      }
-      this.nextSubscriptionId++;
-      const id = `sub:${this.nextSubscriptionId}`;
-      this.subscriptionIds.set(subscription, id);
-      return id;
+    let id = this.requestIds.get(options);
+    if (id === void 0) {
+      id = `request:${++this.nextRequestId}`;
+      this.requestIds.set(options, id);
     }
-    return `opts:${stableSerialize(normalizeSubsetOptionsForKey(options))}`;
+    return id;
   }
   queueRemoteSubsetEnsure(options) {
-    if (this.mode !== `sync-present` || !this.persistence.coordinator.requestEnsureRemoteSubset) {
+    if (this.mode !== `sync-present` || !this.persistence.coordinator.requestEnsureRemoteSubset || this.activeSubsets.get(this.getSubsetKey(options)) !== options) {
       return;
     }
     this.pendingRemoteSubsetEnsures.set(this.getSubsetKey(options), options);
@@ -1020,7 +1049,7 @@ class PersistedCollectionRuntime {
     const { payload } = message;
     const isSelf = message.senderId === this.persistence.coordinator.getNodeId();
     if (isTxCommittedPayload(payload)) {
-      if (this.isHydrating) {
+      if (this.isHydratingNow()) {
         this.queuedTxCommitted.push(payload);
         return;
       }
@@ -1190,13 +1219,16 @@ class PersistedCollectionRuntime {
     });
   }
   async reloadActiveSubsetsUnsafe() {
+    const lifecycleGeneration = this.lifecycleGeneration;
     const activeSubsetOptions = this.activeSubsets.size > 0 ? Array.from(this.activeSubsets.values()) : [{}];
-    this.isHydrating = true;
+    this.hydratingGeneration = lifecycleGeneration;
     try {
       const mergedRows = /* @__PURE__ */ new Map();
       const collectionMetadata = await this.loadCollectionMetadataSnapshot();
+      if (lifecycleGeneration !== this.lifecycleGeneration) return;
       for (const options of activeSubsetOptions) {
         const subsetRows = await this.loadSubsetRowsUnsafe(options);
+        if (lifecycleGeneration !== this.lifecycleGeneration) return;
         for (const row of subsetRows) {
           mergedRows.set(row.key, {
             value: row.value,
@@ -1213,7 +1245,9 @@ class PersistedCollectionRuntime {
         collectionMetadata
       );
     } finally {
-      this.isHydrating = false;
+      if (this.hydratingGeneration === lifecycleGeneration) {
+        this.hydratingGeneration = null;
+      }
     }
     await this.flushQueuedHydrationTransactionsUnsafe();
     await this.flushQueuedTxCommittedUnsafe();
@@ -1297,23 +1331,8 @@ function createWrappedSyncConfig(sourceSyncConfig, runtime) {
       const transactionStack = [];
       const getOpenTransaction = () => transactionStack[transactionStack.length - 1];
       let fullStartPromise = null;
-      const cancelledLoadKeys = /* @__PURE__ */ new Set();
-      const loadSubscriptionIds = /* @__PURE__ */ new WeakMap();
-      let nextLoadSubscriptionId = 0;
-      const getLoadKey = (options) => {
-        const subscription = options.subscription;
-        if (subscription && typeof subscription === `object`) {
-          const existingId = loadSubscriptionIds.get(subscription);
-          if (existingId) {
-            return `sub:${existingId}`;
-          }
-          nextLoadSubscriptionId++;
-          const nextId = String(nextLoadSubscriptionId);
-          loadSubscriptionIds.set(subscription, nextId);
-          return `sub:${nextId}`;
-        }
-        return `opts:${stableSerialize(normalizeSubsetOptionsForKey(options))}`;
-      };
+      const startupState = { cleanedUp: false };
+      const acquisitions = /* @__PURE__ */ new Map();
       runtime.setSyncControls({
         begin: params.begin,
         write: params.write,
@@ -1327,9 +1346,12 @@ function createWrappedSyncConfig(sourceSyncConfig, runtime) {
       const wrappedParams = {
         ...params,
         markReady: () => {
+          if (startupState.cleanedUp) return;
           void (fullStartPromise ?? runtime.ensureStarted()).then(() => {
+            if (startupState.cleanedUp) return;
             params.markReady();
           }).catch((error) => {
+            if (startupState.cleanedUp) return;
             console.warn(
               `Failed persisted sync startup before markReady:`,
               error
@@ -1338,6 +1360,7 @@ function createWrappedSyncConfig(sourceSyncConfig, runtime) {
           });
         },
         begin: (options) => {
+          if (startupState.cleanedUp) return;
           const transaction = {
             operations: [],
             rowMetadataWrites: /* @__PURE__ */ new Map(),
@@ -1352,6 +1375,7 @@ function createWrappedSyncConfig(sourceSyncConfig, runtime) {
           }
         },
         write: (message) => {
+          if (startupState.cleanedUp) return;
           const normalization = runtime.normalizeSyncWriteMessage(message);
           const openTransaction = getOpenTransaction();
           if (!openTransaction) {
@@ -1386,7 +1410,9 @@ function createWrappedSyncConfig(sourceSyncConfig, runtime) {
         },
         metadata: params.metadata ? {
           row: {
+            whenHydrated: () => startupState.cleanedUp ? Promise.resolve() : runtime.ensureResumeBaselineHydrated(),
             get: (key) => {
+              if (startupState.cleanedUp) return void 0;
               const openTransaction = getOpenTransaction();
               const pendingWrite = openTransaction?.rowMetadataWrites.get(key);
               if (pendingWrite) {
@@ -1397,8 +1423,9 @@ function createWrappedSyncConfig(sourceSyncConfig, runtime) {
               }
               return params.metadata.row.get(key);
             },
-            scanPersisted: (options) => runtime.scanPersistedRows(options),
+            scanPersisted: (options) => startupState.cleanedUp ? Promise.resolve([]) : runtime.scanPersistedRows(options),
             set: (key, value) => {
+              if (startupState.cleanedUp) return;
               const openTransaction = getOpenTransaction();
               if (!openTransaction) {
                 throw new InvalidPersistedCollectionConfigError(
@@ -1414,6 +1441,7 @@ function createWrappedSyncConfig(sourceSyncConfig, runtime) {
               }
             },
             delete: (key) => {
+              if (startupState.cleanedUp) return;
               const openTransaction = getOpenTransaction();
               if (!openTransaction) {
                 throw new InvalidPersistedCollectionConfigError(
@@ -1430,6 +1458,7 @@ function createWrappedSyncConfig(sourceSyncConfig, runtime) {
           },
           collection: {
             get: (key) => {
+              if (startupState.cleanedUp) return void 0;
               const openTransaction = getOpenTransaction();
               const pendingWrite = openTransaction?.collectionMetadataWrites.get(key);
               if (pendingWrite) {
@@ -1438,6 +1467,7 @@ function createWrappedSyncConfig(sourceSyncConfig, runtime) {
               return params.metadata.collection.get(key);
             },
             set: (key, value) => {
+              if (startupState.cleanedUp) return;
               const openTransaction = getOpenTransaction();
               if (!openTransaction) {
                 throw new InvalidPersistedCollectionConfigError(
@@ -1453,6 +1483,7 @@ function createWrappedSyncConfig(sourceSyncConfig, runtime) {
               }
             },
             delete: (key) => {
+              if (startupState.cleanedUp) return;
               const openTransaction = getOpenTransaction();
               if (!openTransaction) {
                 throw new InvalidPersistedCollectionConfigError(
@@ -1467,6 +1498,7 @@ function createWrappedSyncConfig(sourceSyncConfig, runtime) {
               }
             },
             list: (prefix) => {
+              if (startupState.cleanedUp) return [];
               const merged = new Map(
                 params.metadata.collection.list().map(({ key, value }) => [key, value])
               );
@@ -1491,6 +1523,7 @@ function createWrappedSyncConfig(sourceSyncConfig, runtime) {
           }
         } : void 0,
         truncate: () => {
+          if (startupState.cleanedUp) return;
           const openTransaction = getOpenTransaction();
           if (!openTransaction) {
             params.truncate();
@@ -1504,6 +1537,7 @@ function createWrappedSyncConfig(sourceSyncConfig, runtime) {
           }
         },
         commit: (signal) => {
+          if (startupState.cleanedUp) return true;
           const openTransaction = transactionStack.pop();
           if (!openTransaction) {
             return params.commit(signal);
@@ -1553,7 +1587,6 @@ function createWrappedSyncConfig(sourceSyncConfig, runtime) {
         }
       };
       let sourceResult = {};
-      const startupState = { cleanedUp: false };
       fullStartPromise = runtime.ensureStarted();
       const sourceResultPromise = (async () => {
         await runtime.ensureStartupMetadataLoaded();
@@ -1568,23 +1601,40 @@ function createWrappedSyncConfig(sourceSyncConfig, runtime) {
       return {
         cleanup: () => {
           startupState.cleanedUp = true;
+          acquisitions.clear();
           sourceResult.cleanup?.();
           runtime.cleanup();
           runtime.clearSyncControls();
         },
         loadSubset: async (options) => {
-          const loadKey = getLoadKey(options);
-          cancelledLoadKeys.delete(loadKey);
+          const acquisition = { forwarded: false };
+          acquisitions.set(options, acquisition);
           await fullStartPromise;
           const resolvedSourceResult = await sourceResultPromise;
-          if (startupState.cleanedUp || cancelledLoadKeys.has(loadKey)) {
+          if (startupState.cleanedUp || acquisitions.get(options) !== acquisition) {
             return;
           }
-          await runtime.loadSubset(options, resolvedSourceResult.loadSubset);
+          return runtime.loadSubset(options, (loadOptions) => {
+            if (startupState.cleanedUp || acquisitions.get(options) !== acquisition) {
+              return true;
+            }
+            if (!resolvedSourceResult.loadSubset) return true;
+            acquisition.forwarded = true;
+            try {
+              return resolvedSourceResult.loadSubset(loadOptions);
+            } catch (error) {
+              acquisition.forwarded = false;
+              throw error;
+            }
+          });
         },
         unloadSubset: (options) => {
-          cancelledLoadKeys.add(getLoadKey(options));
-          runtime.unloadSubset(options, sourceResult.unloadSubset);
+          const acquisition = acquisitions.get(options);
+          acquisitions.delete(options);
+          runtime.unloadSubset(
+            options,
+            acquisition?.forwarded ? sourceResult.unloadSubset : void 0
+          );
         }
       };
     }