@tanstack/electric-db-collection 0.4.3 → 0.4.5

package/src/electric.ts

@@ -47,6 +47,7 @@ import type {
   DeleteMutationFnParams,
   InsertMutationFnParams,
   LoadSubsetOptions,
+  SyncAppliedReceipt,
   SyncConfig,
   SyncMode,
   UpdateMutationFnParams,
@@ -526,6 +527,8 @@ function createLoadSubsetDedupe<T extends Row<unknown>>({
   begin,
   write,
   commit,
+  getCommitCursor,
+  waitForCommitsAfter,
   collectionId,
   encodeColumnName,
   signal,
@@ -539,7 +542,9 @@ function createLoadSubsetDedupe<T extends Row<unknown>>({
     value: T
     metadata: Record<string, unknown>
   }) => void
-  commit: () => void
+  commit: (signal?: AbortSignal) => SyncAppliedReceipt
+  getCommitCursor: () => number
+  waitForCommitsAfter: (cursor: number) => Promise<void>
   collectionId?: string
   /**
    * Optional function to encode column names (e.g., camelCase to snake_case).
@@ -573,12 +578,14 @@ function createLoadSubsetDedupe<T extends Row<unknown>>({
   }
 
   const loadSubset = async (opts: LoadSubsetOptions) => {
+    const commitCursor = getCommitCursor()
+    if (opts.signal?.aborted) return
+
     if (isBufferingInitialSync()) {
       const snapshotParams = compileSQL<T>(opts, compileOptions)
       try {
         const { data: rows } = await stream.fetchSnapshot(snapshotParams)
-
-        if (!isBufferingInitialSync()) {
+        if (opts.signal?.aborted || !isBufferingInitialSync()) {
           debug(`${logPrefix}Ignoring snapshot - sync completed while fetching`)
           return
         }
@@ -592,10 +599,11 @@ function createLoadSubsetDedupe<T extends Row<unknown>>({
               metadata: { ...row.headers },
             })
           }
-          commit()
+          await commit(opts.signal)
           debug(`${logPrefix}Applied snapshot with ${rows.length} rows`)
         }
       } catch (error) {
+        if (opts.signal?.aborted) return
         if (handleSnapshotError(error, `fetchSnapshot`)) {
           return
         }
@@ -643,6 +651,14 @@ function createLoadSubsetDedupe<T extends Row<unknown>>({
       }
     }
 
+    if (opts.signal?.aborted) return
+
+    // Upstream limitation: ShapeStream.requestSnapshot() publishes its rows
+    // through the stream callback before its Promise resolves. It accepts no
+    // request signal and exposes no request identity on those messages, so an
+    // aborted request can already have installed rows before the check below.
+    // Full request-scoped cancellation requires support in the Electric client;
+    // matching snapshots by parameters is unsafe for overlapping equal requests.
     try {
       if (cursor) {
         const whereCurrentOpts: LoadSubsetOptions = {
@@ -675,11 +691,13 @@ function createLoadSubsetDedupe<T extends Row<unknown>>({
         await stream.requestSnapshot(snapshotParams)
       }
     } catch (error) {
+      if (opts.signal?.aborted) return
       if (handleSnapshotError(error, `requestSnapshot`)) {
         return
       }
       throw error
     }
+    await waitForCommitsAfter(commitCursor)
   }
 
   return new DeduplicatedLoadSubset({ loadSubset })
@@ -1476,13 +1494,33 @@ function createElectricSync<T extends Row<unknown>>(
       const {
         begin,
         write,
-        commit,
+        commit: commitSyncTransaction,
         markReady,
         markError,
         truncate,
         collection,
         metadata,
       } = params
+      let commitSequence = 0
+      const pendingAppliedReceipts = new Map<number, Promise<void>>()
+      const commit = (signal?: AbortSignal): SyncAppliedReceipt => {
+        const sequence = ++commitSequence
+        const applied = commitSyncTransaction(signal)
+        if (applied === true) {
+          return true
+        }
+        pendingAppliedReceipts.set(sequence, applied)
+        const removeReceipt = () => pendingAppliedReceipts.delete(sequence)
+        void applied.then(removeReceipt, removeReceipt)
+        return applied
+      }
+      const waitForCommitsAfter = async (cursor: number): Promise<void> => {
+        await Promise.all(
+          Array.from(pendingAppliedReceipts, ([sequence, applied]) =>
+            sequence > cursor ? applied : undefined,
+          ),
+        )
+      }
       const readPersistedResumeState = (): ElectricResumeState | undefined => {
         const persistedResumeState = metadata?.collection.get(`electric:resume`)
         return parseElectricResumeState(persistedResumeState)
@@ -1507,7 +1545,13 @@ function createElectricSync<T extends Row<unknown>>(
 
       // Wrap markReady to wait for test hook in progressive mode
       let progressiveReadyGate: Promise<void> | null = null
-      const wrappedMarkReady = (isBuffering: boolean) => {
+      let streamErrorVersion = 0
+      const wrappedMarkReady = (
+        isBuffering: boolean,
+        expectedErrorVersion = streamErrorVersion,
+      ) => {
+        if (streamErrorVersion !== expectedErrorVersion) return
+
         // Only create gate if we're in buffering phase (first up-to-date)
         if (
           isBuffering &&
@@ -1517,7 +1561,9 @@ function createElectricSync<T extends Row<unknown>>(
           // Create a new gate promise for this sync cycle
           progressiveReadyGate = testHooks.beforeMarkingReady()
           progressiveReadyGate.then(() => {
-            markReady()
+            if (streamErrorVersion === expectedErrorVersion) {
+              markReady()
+            }
           })
         } else {
           // No hook, not buffering, or already past first up-to-date
@@ -1572,6 +1618,7 @@ function createElectricSync<T extends Row<unknown>>(
           (canUsePersistedResume ? persistedResumeState.handle : undefined),
         signal: abortController.signal,
         onError: (errorParams) => {
+          streamErrorVersion++
           // Note that Electric sends a 409 error on a `must-refetch` message, but the
           // ShapeStream handled this and it will not reach this handler, therefor
           // this handler will not run for a `must-refetch`.
@@ -1719,6 +1766,8 @@ function createElectricSync<T extends Row<unknown>>(
         begin,
         write,
         commit,
+        getCommitCursor: () => commitSequence,
+        waitForCommitsAfter,
         collectionId,
         // Pass the columnMapper's encode function to transform column names
         // (e.g., camelCase to snake_case) when compiling SQL for subset queries
@@ -1881,6 +1930,8 @@ function createElectricSync<T extends Row<unknown>>(
         }
 
         if (commitPoint !== null) {
+          let applied: SyncAppliedReceipt = true
+          const wasBufferingInitialSync = isBufferingInitialSync()
           // PROGRESSIVE MODE: Atomic swap on first up-to-date (not subset-end)
           // EXCEPTION: Skip atomic swap if a transaction is already started (e.g., from must-refetch).
           // In that case, do a normal commit to properly close the existing transaction.
@@ -1935,7 +1986,7 @@ function createElectricSync<T extends Row<unknown>>(
 
             // Commit the atomic swap
             stageResumeMetadata()
-            commit()
+            applied = commit()
 
             // Exit buffering phase by marking that we've received up-to-date
             // isBufferingInitialSync() will now return false
@@ -1949,15 +2000,24 @@ function createElectricSync<T extends Row<unknown>>(
             // Both up-to-date and subset-end trigger a commit
             if (transactionStarted) {
               stageResumeMetadata()
-              commit()
+              applied = commit()
               transactionStarted = false
             } else if (commitPoint === `up-to-date` && metadata) {
               begin()
               stageResumeMetadata()
-              commit()
+              applied = commit()
             }
           }
-          wrappedMarkReady(isBufferingInitialSync())
+          const readyErrorVersion = streamErrorVersion
+          if (applied === true) {
+            wrappedMarkReady(wasBufferingInitialSync, readyErrorVersion)
+          } else {
+            void applied.then(
+              () =>
+                wrappedMarkReady(wasBufferingInitialSync, readyErrorVersion),
+              () => undefined,
+            )
+          }
 
           // Track that we've received the first up-to-date for progressive mode
           if (commitPoint === `up-to-date`) {