docs: update examples to use new explicit sync pattern instead of deprecated return values

- Update ElectricCollectionConfig examples to use await collection.utils.awaitTxId()
- Update overview.md example to use explicit sync awaiting
- Update mutations.md to show cleaner pattern for awaiting txids
- Update examples/react/projects/README.md to use collection.utils.refetch()

Co-authored-by: Kyle Mathews <KyleAMathews@users.noreply.github.com>

Author: github-actions[bot]

docs/guides/mutations.md

@@ -453,14 +453,13 @@ onUpdate: async ({ transaction, collection }) => {
 **ElectricCollection** - wait for txid(s) to sync:
 ```typescript
 onUpdate: async ({ transaction, collection }) => {
-  const txids = await Promise.all(
+  await Promise.all(
     transaction.mutations.map(async (mutation) => {
       const response = await api.todos.update(mutation.original.id, mutation.changes)
-      return response.txid
+      // Wait for this txid to sync
+      await collection.utils.awaitTxId(response.txid)
     })
   )
-  // Wait for all txids to sync
-  await Promise.all(txids.map(txid => collection.utils.awaitTxId(txid)))
 }
 ```
 

docs/overview.md

@@ -498,10 +498,11 @@ export const todoCollection = createCollection(
     },
     getKey: (item) => item.id,
     schema: todoSchema,
-    onInsert: async ({ transaction }) => {
+    onInsert: async ({ transaction, collection }) => {
       const response = await api.todos.create(transaction.mutations[0].modified)
 
-      return { txid: response.txid }
+      // Wait for txid to sync
+      await collection.utils.awaitTxId(response.txid)
     },
     // You can also implement onUpdate, onDelete as needed.
   })

docs/reference/electric-db-collection/interfaces/ElectricCollectionConfig.md

@@ -70,12 +70,13 @@ Promise resolving to { txid, timeout? } or void
 
 ```ts
 // Basic Electric delete handler with txid (recommended)
-onDelete: async ({ transaction }) => {
+onDelete: async ({ transaction, collection }) => {
   const mutation = transaction.mutations[0]
   const result = await api.todos.delete({
     id: mutation.original.id
   })
-  return { txid: result.txid }
+  // Wait for txid to sync
+  await collection.utils.awaitTxId(result.txid)
 }
 ```
 
@@ -122,34 +123,39 @@ Promise resolving to { txid, timeout? } or void
 
 ```ts
 // Basic Electric insert handler with txid (recommended)
-onInsert: async ({ transaction }) => {
+onInsert: async ({ transaction, collection }) => {
   const newItem = transaction.mutations[0].modified
   const result = await api.todos.create({
     data: newItem
   })
-  return { txid: result.txid }
+  // Wait for txid to sync
+  await collection.utils.awaitTxId(result.txid)
 }
 ```
 
 ```ts
 // Insert handler with custom timeout
-onInsert: async ({ transaction }) => {
+onInsert: async ({ transaction, collection }) => {
   const newItem = transaction.mutations[0].modified
   const result = await api.todos.create({
     data: newItem
   })
-  return { txid: result.txid, timeout: 10000 } // Wait up to 10 seconds
+  // Wait for txid to sync with custom timeout (10 seconds)
+  await collection.utils.awaitTxId(result.txid, 10000)
 }
 ```
 
 ```ts
-// Insert handler with multiple items - return array of txids
-onInsert: async ({ transaction }) => {
+// Insert handler with multiple items - wait for all txids
+onInsert: async ({ transaction, collection }) => {
   const items = transaction.mutations.map(m => m.modified)
   const results = await Promise.all(
     items.map(item => api.todos.create({ data: item }))
   )
-  return { txid: results.map(r => r.txid) }
+  // Wait for all txids to sync
+  await Promise.all(
+    results.map(r => collection.utils.awaitTxId(r.txid))
+  )
 }
 ```
 
@@ -196,13 +202,14 @@ Promise resolving to { txid, timeout? } or void
 
 ```ts
 // Basic Electric update handler with txid (recommended)
-onUpdate: async ({ transaction }) => {
+onUpdate: async ({ transaction, collection }) => {
   const { original, changes } = transaction.mutations[0]
   const result = await api.todos.update({
     where: { id: original.id },
     data: changes
   })
-  return { txid: result.txid }
+  // Wait for txid to sync
+  await collection.utils.awaitTxId(result.txid)
 }
 ```
 

examples/react/projects/README.md

@@ -201,14 +201,15 @@ export const todoCollection = createCollection(
     queryClient,
     schema: todoSchema,
     getKey: (item) => item.id,
-    onInsert: async ({ transaction }) => {
+    onInsert: async ({ transaction, collection }) => {
       const { modified: newTodo } = transaction.mutations[0]
-      const result = await trpc.todos.create.mutate({
+      await trpc.todos.create.mutate({
         text: newTodo.text,
         completed: newTodo.completed,
         project_id: newTodo.project_id,
       })
-      return { txid: result.txid }
+      // Trigger refetch to sync server state
+      await collection.utils.refetch()
     },
     // You can also implement onUpdate, onDelete as needed
   })