Fix returning an array of txids from an Electric collection handler (#795)

* test: add failing test for array txid bug in electric collection

This test demonstrates issue #793 where returning an array of txids
from a collection handler (e.g., `return { txid: [txid1, txid2] }`)
causes a TimeoutWaitingForTxIdError instead of properly waiting for
all txids to be seen in the sync stream.

The test shows that when a handler returns multiple txids, the
processMatchingStrategy function doesn't correctly handle the array,
even though it has code that appears to support arrays.

* test: make array txid test more realistic with staggered arrivals

Update the test to send txids on different ticks (50ms and 100ms apart)
rather than in a single batch. This better simulates real-world
conditions where multiple txids rarely arrive together.

* fix: correct array txid handling in electric collection handlers

The bug was in processMatchingStrategy when handling arrays of txids.
Using `.map(awaitTxId)` directly caused Array.map() to pass three
arguments (element, index, array), and the index was being interpreted
as the timeout parameter of awaitTxId.

For example:
- awaitTxId(txid1, 0) → timeout 0ms (immediate timeout!)
- awaitTxId(txid2, 1) → timeout 1ms (immediate timeout!)

This caused TimeoutWaitingForTxIdError even though the txids were
being sent correctly via the sync stream.

The fix uses an arrow function to ensure only the txid is passed:
await Promise.all(result.txid.map((txid) => awaitTxId(txid)))

This allows the timeout to use its default value of 5000ms.

Fixes #793

* chore: add changeset for array txid fix

* test: fix TypeScript errors in array txid test

Add non-null assertions for array element access to fix type errors
where txids[0] and txids[1] could theoretically be undefined.

* chore: remove obvious comment

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: KyleAMathews

.changeset/fix-array-txid-handling.md

@@ -0,0 +1,5 @@
+---
+"@tanstack/electric-db-collection": patch
+---
+
+Fix array txid handling in electric collection handlers. When returning `{ txid: [txid1, txid2] }` from an `onInsert`, `onUpdate`, or `onDelete` handler, the system would timeout with `TimeoutWaitingForTxIdError` instead of properly waiting for all txids. The bug was caused by passing array indices as timeout parameters when calling `awaitTxId` via `.map()`.

packages/electric-db-collection/src/electric.ts

@@ -533,7 +533,7 @@ export function electricCollectionOptions(
     if (result && `txid` in result) {
       // Handle both single txid and array of txids
       if (Array.isArray(result.txid)) {
-        await Promise.all(result.txid.map(awaitTxId))
+        await Promise.all(result.txid.map((txid) => awaitTxId(txid)))
       } else {
         await awaitTxId(result.txid)
       }

packages/electric-db-collection/tests/electric.test.ts

@@ -672,6 +672,84 @@ describe(`Electric Integration`, () => {
       expect(onInsert).toHaveBeenCalled()
     })
 
+    it(`should handle array of txids returned from handler`, async () => {
+      // Create a fake backend that returns multiple txids
+      const fakeBackend = {
+        persist: (
+          mutations: Array<PendingMutation<Row>>
+        ): Promise<Array<number>> => {
+          // Simulate multiple items being persisted and each getting a txid
+          const txids = mutations.map(() => Math.floor(Math.random() * 10000))
+          return Promise.resolve(txids)
+        },
+      }
+
+      // Create handler that returns array of txids
+      const onInsert = vi.fn(async (params: MutationFnParams<Row>) => {
+        const txids = await fakeBackend.persist(params.transaction.mutations)
+
+        // Simulate server sending sync messages on different ticks
+        // In the real world, multiple txids rarely arrive together
+        setTimeout(() => {
+          subscriber([
+            {
+              key: `1`,
+              value: { id: 1, name: `Item 1` },
+              headers: {
+                operation: `insert`,
+                txids: [txids[0]!],
+              },
+            },
+            { headers: { control: `up-to-date` } },
+          ])
+        }, 1)
+
+        setTimeout(() => {
+          subscriber([
+            {
+              key: `2`,
+              value: { id: 2, name: `Item 2` },
+              headers: {
+                operation: `insert`,
+                txids: [txids[1]!],
+              },
+            },
+            { headers: { control: `up-to-date` } },
+          ])
+        }, 2)
+
+        // Return array of txids - this is the pattern that's failing
+        return { txid: txids }
+      })
+
+      const config = {
+        id: `test-array-txids`,
+        shapeOptions: {
+          url: `http://test-url`,
+          params: { table: `test_table` },
+        },
+        startSync: true,
+        getKey: (item: Row) => item.id as number,
+        onInsert,
+      }
+
+      const testCollection = createCollection(electricCollectionOptions(config))
+
+      // Insert multiple items
+      const tx = testCollection.insert([
+        { id: 1, name: `Item 1` },
+        { id: 2, name: `Item 2` },
+      ])
+
+      // This should resolve when all txids are seen
+      await expect(tx.isPersisted.promise).resolves.toBeDefined()
+      expect(onInsert).toHaveBeenCalled()
+
+      // Verify both items were added
+      expect(testCollection.has(1)).toBe(true)
+      expect(testCollection.has(2)).toBe(true)
+    })
+
     it(`should support custom match function using awaitMatch utility`, async () => {
       let resolveCustomMatch: () => void
       const customMatchPromise = new Promise<void>((resolve) => {