From 0ac89c73727be3250eb7d7a107ec17114bbfa440 Mon Sep 17 00:00:00 2001
From: Kyle Mathews <mathews.kyle@gmail.com>
Date: Thu, 26 Jun 2025 11:23:18 -0600
Subject: [PATCH 1/8] Add createOptimisticAction helper

---
 docs/overview.md                              | 144 +++++------
 packages/db/src/index.ts                      |   1 +
 packages/db/src/optimistic-action.ts          |  27 +++
 packages/db/src/types.ts                      |  11 +
 packages/db/tests/optimistic-action.test.ts   | 227 ++++++++++++++++++
 .../react-db/src/useOptimisticMutation.ts     |  15 --
 packages/react-db/vite.config.ts              |   1 -
 packages/vue-db/src/useOptimisticMutation.ts  |  15 --
 8 files changed, 328 insertions(+), 113 deletions(-)
 create mode 100644 packages/db/src/optimistic-action.ts
 create mode 100644 packages/db/tests/optimistic-action.test.ts
 delete mode 100644 packages/react-db/src/useOptimisticMutation.ts
 delete mode 100644 packages/vue-db/src/useOptimisticMutation.ts

diff --git a/docs/overview.md b/docs/overview.md
index ac5e7b9e..98a62d0a 100644
--- a/docs/overview.md
+++ b/docs/overview.md
@@ -117,12 +117,13 @@ Mutations are based on a `Transaction` primitive.
 
 For simple state changes, directly mutating the collection and persisting with the operator handlers is enough.
 
-But for more complex use cases, you can directly create custom mutators with `useOptimisticMutation`. This lets you do things such as do transactions with multiple mutations across multiple collections, do chained transactions w/ intermediate rollbacks, etc.
+But for more complex use cases, you can directly create custom actions with `createOptimisticAction` or custom transactions with `createTransaction`. This lets you do things such as do transactions with multiple mutations across multiple collections, do chained transactions w/ intermediate rollbacks, etc.
 
 For example, in the following code, the mutationFn first sends the write to the server using `await api.todos.update(updatedTodo)` and then calls `await collection.refetch()` to trigger a re-fetch of the collection contents using TanStack Query. When this second await resolves, the collection is up-to-date with the latest changes and the optimistic state is safely discarded.
 
 ```ts
-const updateTodo = useOptimisticMutation({
+const updateTodo = createOptimisticAction<{id: string}>({
+  onMutate,
   mutationFn: async ({ transaction }) => {
     const { collection, modified: updatedTodo } = transaction.mutations[0]
 
@@ -384,55 +385,83 @@ const mutationFn: MutationFn = async ({ transaction }) => {
 }
 ```
 
-#### `useOptimisticMutation`
+#### `createOptimisticAction`
 
-Use the `useOptimisticMutation` hook with your `mutationFn` to create a mutator that you can use to mutate data in your components:
+Use `createOptimisticAction` with your `mutationFn` and `onMutate` functions to create an action that you can use to mutate data in your components in fully custom ways:
 
 ```tsx
-import { useOptimisticMutation } from '@tanstack/react-db'
+import { createOptimisticAction } from '@tanstack/react-db'
+
+// Create the `addTodo` action, passing in your `mutationFn` and `onMutate`.
+const addTodo = createOptimisticAction<string>({
+  onMutate: (text) => {
+    // Instantly applies the local optimistic state.
+    todoCollection.insert({
+      id: uuid(),
+      text,
+      completed: false
+    })
+  },
+  mutationFn: async (text) => {
+    // Persist the todo to your backend
+    const response = await fetch('/api/todos', {
+      method: 'POST',
+      body: JSON.stringify({ text, completed: false }),
+    })
+    return response.json()
+  }
+})
 
 const Todo = () => {
-  // Create the `addTodo` mutator, passing in your `mutationFn`.
-  const addTodo = useOptimisticMutation({ mutationFn })
-
   const handleClick = () => {
-    // Triggers the mutationFn
-    addTodo.mutate(() =>
-      // Instantly applies the local optimistic state.
-      todoCollection.insert({
-        id: uuid(),
-        text: '🔥 Make app faster',
-        completed: false
-      })
-    )
+    // Triggers the onMutate and then the mutationFn
+    addTodo('🔥 Make app faster')
   }
 
   return <Button onClick={ handleClick } />
 }
 ```
 
-Transaction lifecycles can be manually controlled:
+## Manual Transactions
+
+By manually creating transactions, you can fully control their lifecycles and behaviors. `createOptimisticAction` is a ~25 line
+function which implements a common transaction pattern. Feel free to invent your own patterns and hooks!
+
+
+Here's one way you could use transactions.
 
 ```ts
-const addTodo = useOptimisticMutation({ mutationFn })
-const tx = addTodo.createTransaction()
+import { createTransaction } from "@tanstack/react-db"
 
-tx.mutate(() => {}
+const addTodoTx = createTransaction({
+  autoCommit: false,
+  mutationFn: async ({ transaction }) => {
+    // Persist data to backend
+    await Promise.all(transaction.mutations.map(mutation => {
+      return await api.saveTodo(mutation.modified)
+    })
+  },
+})
+
+// Apply first change
+addTodoTx.mutate(() => todoCollection.insert({ id: '1', text: 'First todo', completed: false }))
 
 // user reviews change
 
-// Another mutation
-tx.mutate(() => {}
+// Apply another change
+addTodoTx.mutate(() => todoCollection.insert({ id: '2', text: 'Second todo', completed: false }))
 
-// Mutation is approved
-tx.commit()
+// User decides to save and we call .commit() and the mutations are persisted to the backend.
+addTodoTx.commit()
 ```
 
+## Transaction lifecycle
+
 Transactions progress through the following states:
 
 1. `pending`: Initial state when a transaction is created and optimistic mutations can be applied
 2. `persisting`: Transaction is being persisted to the backend
-3. `completed`: Transaction has been successfully persisted
+3. `completed`: Transaction has been successfully persisted and any backend changes have been synced back.
 4. `failed`: An error was thrown while persisting or syncing back the Transaction
 
 #### Write operations
@@ -569,10 +598,7 @@ This pattern allows you to extend an existing TanStack Query application, or any
 
 One of the most powerful ways of using TanStack DB is with a sync engine, for a fully local-first experience with real-time sync. This allows you to incrementally adopt sync into an existing app, whilst still handling writes with your existing API.
 
-Here, we illustrate this pattern:
-
-- using [ElectricSQL](https://electric-sql.com) as the sync engine; and
-- Instead of sending mutations to unique endpoints, we show an example here of how to POST mutations to a generic `/ingest/mutations` endpoint
+Here, we illustrate this pattern using [ElectricSQL](https://electric-sql.com) as the sync engine.
 
 ```tsx
 import type { Collection } from '@tanstack/db'
@@ -592,71 +618,25 @@ export const todoCollection = createCollection(electricCollectionOptions<Todo>({
   },
   getKey: (item) => item.id,
   schema: todoSchema
-}))
-
-// Define a generic `mutationFn` that handles all mutations and
-// POSTs them to a backend ingestion endpoint.
-const mutationFn: MutationFn = async ({ transaction }) => {
-  const payload = transaction.mutations.map((mutation: PendingMutation) => {
-    const { collection: _, ...rest } = mutation
-
-    return rest
-  })
-
-  const response = await fetch('/ingest/mutations', {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-    },
-    body: JSON.stringify(payload)
-  })
+  onInsert: ({ transaction }) => {
+    const response = await api.todos.create(transaction.mutations[0].modified)
 
-  if (!response.ok) {
-    // Throwing an error will rollback the optimistic state.
-    throw new Error(`HTTP Error: ${response.status}`)
+    return { txid: response.txid}
   }
+  // You can also implement onUpdate, onDelete as needed.
+}))
 
-  const result = await response.json()
-
-  // Wait for the transaction to be synced back from the server
-  // before discarding the optimistic state.
-  const collection: Collection = transaction.mutations[0].collection
-
-  // Here we use an ElectricSQL feature to monitor the incoming sync
-  // stream for the database transaction ID that the writes we made
-  // were applied under. When this syncs through, we can safely
-  // discard the local optimistic state.
-  await collection.awaitTxId(result.txid)
-}
-
-// We can now use the same mutationFn for any local write operations.
 const AddTodo = () => {
-  const addTodo = useOptimisticMutation({ mutationFn })
-
   return (
     <Button
       onClick={() =>
-        addTodo.mutate(() =>
-          todoCollection.insert({
-            id: uuid(),
-            text: "🔥 Make app faster",
-            completed: false
-          })
-        )
+        todoCollection.insert({ text: "🔥 Make app faster" })
       }
     />
   )
 }
 ```
 
-The key requirements for the server in this case are:
-
-1. to be able to parse and ingest the payload format
-2. to return the database transaction ID that the changes were applied under; this then allows the mutationFn to monitor the replication stream for that `txid`, at which point the local optimistic state is discarded
-
-> [!TIP]
-> One reference implementation of a backend designed to ingest changes from TanStack DB is the [`Phoenix.Sync.Writer`](https://hexdocs.pm/phoenix_sync/Phoenix.Sync.Writer.html) module from the [Phoenix.Sync](https://hexdocs.pm/phoenix_sync) library for the [Phoenix web framework](https://www.phoenixframework.org).
-
 ## More info
 
 If you have questions / need help using TanStack DB, let us know on the Discord or start a GitHub discussion:
diff --git a/packages/db/src/index.ts b/packages/db/src/index.ts
index 67efce2f..f02eed52 100644
--- a/packages/db/src/index.ts
+++ b/packages/db/src/index.ts
@@ -7,6 +7,7 @@ export * from "./errors"
 export * from "./utils"
 export * from "./proxy"
 export * from "./query/index.js"
+export * from "./optimistic-action"
 
 // Re-export some stuff explicitly to ensure the type & value is exported
 export type { Collection } from "./collection"
diff --git a/packages/db/src/optimistic-action.ts b/packages/db/src/optimistic-action.ts
new file mode 100644
index 00000000..b23dbddf
--- /dev/null
+++ b/packages/db/src/optimistic-action.ts
@@ -0,0 +1,27 @@
+import { createTransaction } from "./transactions"
+import type { CreateOptimisticActionsOptions, Transaction } from "./types"
+
+export function createOptimisticAction<TVariables = unknown>(
+  options: CreateOptimisticActionsOptions<TVariables>
+) {
+  const { mutationFn, onMutate, ...config } = options
+
+  return (variables: TVariables): Transaction => {
+    // Create transaction with the original config
+    const transaction = createTransaction({
+      ...config,
+      // Wire the mutationFn to use the provided variables
+      mutationFn: async (params) => {
+        return await mutationFn(variables, params)
+      },
+    })
+
+    // Execute the transaction (no callback needed since onMutate was already called)
+    transaction.mutate(() => {
+      // Call onMutate with variables to apply optimistic updates
+      onMutate(variables)
+    })
+
+    return transaction
+  }
+}
diff --git a/packages/db/src/types.ts b/packages/db/src/types.ts
index bf0b40f4..6189dd55 100644
--- a/packages/db/src/types.ts
+++ b/packages/db/src/types.ts
@@ -111,6 +111,17 @@ export interface TransactionConfig<T extends object = Record<string, unknown>> {
   metadata?: Record<string, unknown>
 }
 
+/**
+ * Options for the useOptimisticMutation hook
+ */
+export interface CreateOptimisticActionsOptions<TVars = unknown>
+  extends Omit<TransactionConfig, `mutationFn`> {
+  /** Function to apply optimistic updates locally before the mutation completes */
+  onMutate: (vars: TVars) => void
+  /** Function to execute the mutation on the server */
+  mutationFn: (vars: TVars, params: MutationFnParams) => Promise<any>
+}
+
 export type { Transaction }
 
 type Value<TExtensions = never> =
diff --git a/packages/db/tests/optimistic-action.test.ts b/packages/db/tests/optimistic-action.test.ts
new file mode 100644
index 00000000..25dd4c09
--- /dev/null
+++ b/packages/db/tests/optimistic-action.test.ts
@@ -0,0 +1,227 @@
+import { describe, expect, expectTypeOf, it, vi } from "vitest"
+import { createCollection, createOptimisticAction } from "../src"
+import type {
+  MutationFnParams,
+  Transaction,
+  TransactionWithMutations,
+} from "../src"
+
+describe(`createOptimisticAction`, () => {
+  // Runtime tests
+  it(`should apply optimistic updates and execute mutation function`, async () => {
+    // Setup a mock collection
+    const collection = createCollection<{ id: string; text: string }>({
+      id: `test-collection`,
+      getKey: (item) => item.id,
+      sync: {
+        sync: () => {
+          // No-op sync for testing
+        },
+      },
+    })
+
+    // Mock functions to verify they're called with correct arguments
+    const onMutateMock = vi.fn()
+    const mutationFnMock = vi.fn().mockResolvedValue({ success: true })
+
+    // Create an optimistic action with string variables
+    const addTodo = createOptimisticAction<string>({
+      onMutate: (text) => {
+        // Verify text is a string
+        expect(typeof text).toBe(`string`)
+        collection.insert({ id: `1`, text })
+        onMutateMock(text)
+      },
+      mutationFn: async (text, params) => {
+        // Verify text is a string and params has transaction
+        expect(typeof text).toBe(`string`)
+        expect(params).toHaveProperty(`transaction`)
+        return Promise.resolve(mutationFnMock(text, params))
+      },
+    })
+
+    // Execute the optimistic action
+    const transaction = addTodo(`Test Todo`)
+
+    // Verify onMutate was called immediately with the correct argument
+    expect(onMutateMock).toHaveBeenCalledWith(`Test Todo`)
+
+    // Verify the optimistic update was applied to the collection
+    expect(collection.get(`1`)).toEqual({ id: `1`, text: `Test Todo` })
+
+    // Wait for the mutation to complete
+    await transaction.isPersisted.promise
+
+    // Verify mutationFn was called with the correct arguments
+    expect(mutationFnMock).toHaveBeenCalledTimes(1)
+    expect(mutationFnMock.mock.calls[0]?.[0]).toBe(`Test Todo`)
+    expect(mutationFnMock.mock.calls[0]?.[1]).toHaveProperty(`transaction`)
+  })
+
+  // Test with complex object variables
+  it(`should handle complex object variables correctly`, async () => {
+    // Setup a mock collection
+    const collection = createCollection<{
+      id: string
+      name: string
+      completed: boolean
+    }>({
+      id: `todo-collection`,
+      getKey: (item) => item.id,
+      sync: {
+        sync: () => {
+          // No-op sync for testing
+        },
+      },
+    })
+
+    // Mock functions
+    const onMutateMock = vi.fn()
+    const mutationFnMock = vi.fn().mockResolvedValue({ success: true })
+
+    // Define a complex type for our variables
+    type TodoInput = {
+      id: string
+      name: string
+      completed: boolean
+    }
+
+    // Create an optimistic action with complex object variables
+    const addComplexTodo = createOptimisticAction<TodoInput>({
+      onMutate: (todoInput) => {
+        // Verify todoInput has the expected shape
+        expect(todoInput).toHaveProperty(`id`)
+        expect(todoInput).toHaveProperty(`name`)
+        expect(todoInput).toHaveProperty(`completed`)
+
+        collection.insert(todoInput)
+        onMutateMock(todoInput)
+      },
+      mutationFn: async (todoInput, params) => {
+        // Verify todoInput has the expected shape and params has transaction
+        expect(todoInput).toHaveProperty(`id`)
+        expect(todoInput).toHaveProperty(`name`)
+        expect(todoInput).toHaveProperty(`completed`)
+        expect(params).toHaveProperty(`transaction`)
+
+        return Promise.resolve(mutationFnMock(todoInput, params))
+      },
+    })
+
+    // Execute the optimistic action with a complex object
+    const todoData = { id: `2`, name: `Complex Todo`, completed: false }
+    const transaction = addComplexTodo(todoData)
+
+    // Verify onMutate was called with the correct object
+    expect(onMutateMock).toHaveBeenCalledWith(todoData)
+
+    // Verify the optimistic update was applied to the collection
+    expect(collection.get(`2`)).toEqual(todoData)
+
+    // Wait for the mutation to complete
+    await transaction.isPersisted.promise
+
+    // Verify mutationFn was called with the correct arguments
+    expect(mutationFnMock).toHaveBeenCalledTimes(1)
+    expect(mutationFnMock.mock.calls[0]?.[0]).toEqual(todoData)
+    expect(mutationFnMock.mock.calls[0]?.[1]).toHaveProperty(`transaction`)
+  })
+
+  // Type tests using expectTypeOf
+  it(`should enforce correct types for variables`, () => {
+    // String variables
+    const stringAction = createOptimisticAction<string>({
+      onMutate: (text) => {
+        // Verify text is inferred as string
+        expectTypeOf(text).toBeString()
+      },
+      mutationFn: async (text, params) => {
+        // Verify text is inferred as string and params has transaction
+        expectTypeOf(text).toBeString()
+        expectTypeOf(params).toEqualTypeOf<MutationFnParams>()
+        expectTypeOf(
+          params.transaction
+        ).toEqualTypeOf<TransactionWithMutations>()
+        return Promise.resolve({ success: true })
+      },
+    })
+
+    // Verify the returned function accepts a string and returns a Transaction
+    expectTypeOf(stringAction).parameters.toEqualTypeOf<[string]>()
+    expectTypeOf(stringAction).returns.toEqualTypeOf<Transaction>()
+
+    // Complex object variables
+    interface User {
+      id: number
+      name: string
+      email: string
+    }
+
+    const userAction = createOptimisticAction<User>({
+      onMutate: (user) => {
+        // Verify user is inferred as User
+        expectTypeOf(user).toEqualTypeOf<User>()
+        expectTypeOf(user.id).toBeNumber()
+        expectTypeOf(user.name).toBeString()
+        expectTypeOf(user.email).toBeString()
+      },
+      mutationFn: async (user, params) => {
+        // Verify user is inferred as User and params has transaction
+        expectTypeOf(user).toEqualTypeOf<User>()
+        expectTypeOf(user.id).toBeNumber()
+        expectTypeOf(params).toEqualTypeOf<MutationFnParams>()
+        expectTypeOf(
+          params.transaction
+        ).toEqualTypeOf<TransactionWithMutations>()
+        return Promise.resolve({ success: true })
+      },
+    })
+
+    // Verify the returned function accepts a User and returns a Transaction
+    expectTypeOf(userAction).parameters.toEqualTypeOf<[User]>()
+    expectTypeOf(userAction).returns.toEqualTypeOf<Transaction>()
+  })
+
+  // Test error handling
+  it(`should handle errors in mutationFn correctly`, async () => {
+    // Setup a mock collection
+    const collection = createCollection<{ id: string; text: string }>({
+      id: `error-collection`,
+      getKey: (item) => item.id,
+      sync: {
+        sync: () => {
+          // No-op sync for testing
+        },
+      },
+    })
+
+    // Create an optimistic action that will fail
+    const failingAction = createOptimisticAction<string>({
+      onMutate: (text) => {
+        collection.insert({ id: `3`, text })
+      },
+      mutationFn: () => {
+        throw new Error(`Mutation failed`)
+      },
+    })
+
+    // Execute the optimistic action
+    const transaction = failingAction(`Will Fail`)
+
+    // Verify the optimistic update was applied
+    expect(collection.get(`3`)).toEqual({ id: `3`, text: `Will Fail` })
+
+    // Wait for the transaction to complete (it will fail)
+    try {
+      await transaction.isPersisted.promise
+      // Should not reach here
+      expect(true).toBe(false)
+    } catch (error) {
+      // Verify the error was caught
+      expect(error).toBeDefined()
+      expect(transaction.state).toBe(`failed`)
+      expect(transaction.error).toBeDefined()
+      expect(transaction.error?.message).toContain(`Mutation failed`)
+    }
+  })
+})
diff --git a/packages/react-db/src/useOptimisticMutation.ts b/packages/react-db/src/useOptimisticMutation.ts
deleted file mode 100644
index c8b1b84f..00000000
--- a/packages/react-db/src/useOptimisticMutation.ts
+++ /dev/null
@@ -1,15 +0,0 @@
-import { createTransaction } from "@tanstack/db"
-import type { Transaction, TransactionConfig } from "@tanstack/db"
-
-export function useOptimisticMutation(config: TransactionConfig) {
-  return {
-    mutate: (callback: () => void): Transaction => {
-      const transaction = createTransaction(config)
-      transaction.mutate(callback)
-      return transaction
-    },
-    createTransaction: (): Transaction => {
-      return createTransaction({ ...config, autoCommit: false })
-    },
-  }
-}
diff --git a/packages/react-db/vite.config.ts b/packages/react-db/vite.config.ts
index f21131bf..ac77356d 100644
--- a/packages/react-db/vite.config.ts
+++ b/packages/react-db/vite.config.ts
@@ -8,7 +8,6 @@ const config = defineConfig({
   test: {
     name: packageJson.name,
     dir: `./tests`,
-    watch: false,
     environment: `jsdom`,
     setupFiles: [`./tests/test-setup.ts`],
     coverage: { enabled: true, provider: `istanbul`, include: [`src/**/*`] },
diff --git a/packages/vue-db/src/useOptimisticMutation.ts b/packages/vue-db/src/useOptimisticMutation.ts
deleted file mode 100644
index c8b1b84f..00000000
--- a/packages/vue-db/src/useOptimisticMutation.ts
+++ /dev/null
@@ -1,15 +0,0 @@
-import { createTransaction } from "@tanstack/db"
-import type { Transaction, TransactionConfig } from "@tanstack/db"
-
-export function useOptimisticMutation(config: TransactionConfig) {
-  return {
-    mutate: (callback: () => void): Transaction => {
-      const transaction = createTransaction(config)
-      transaction.mutate(callback)
-      return transaction
-    },
-    createTransaction: (): Transaction => {
-      return createTransaction({ ...config, autoCommit: false })
-    },
-  }
-}

From 892c292951056f1c91f79c5184e2ff799ec14f45 Mon Sep 17 00:00:00 2001
From: Kyle Mathews <mathews.kyle@gmail.com>
Date: Thu, 26 Jun 2025 11:25:26 -0600
Subject: [PATCH 2/8] add changeset

---
 .changeset/solid-pandas-draw.md | 7 +++++++
 1 file changed, 7 insertions(+)
 create mode 100644 .changeset/solid-pandas-draw.md

diff --git a/.changeset/solid-pandas-draw.md b/.changeset/solid-pandas-draw.md
new file mode 100644
index 00000000..150c8871
--- /dev/null
+++ b/.changeset/solid-pandas-draw.md
@@ -0,0 +1,7 @@
+---
+"@tanstack/react-db": patch
+"@tanstack/vue-db": patch
+"@tanstack/db": patch
+---
+
+Add createOptimisticAction helper that replaces useOptimisticMutation

From 2e0cc4129743539ba7266531a13509ba0610a8c0 Mon Sep 17 00:00:00 2001
From: Kyle Mathews <mathews.kyle@gmail.com>
Date: Thu, 26 Jun 2025 11:26:13 -0600
Subject: [PATCH 3/8] cleanup refs to useOptimisticMutation

---
 packages/db/src/types.ts       | 2 +-
 packages/react-db/src/index.ts | 1 -
 packages/vue-db/src/index.ts   | 1 -
 3 files changed, 1 insertion(+), 3 deletions(-)

diff --git a/packages/db/src/types.ts b/packages/db/src/types.ts
index 6189dd55..dcd55ac6 100644
--- a/packages/db/src/types.ts
+++ b/packages/db/src/types.ts
@@ -112,7 +112,7 @@ export interface TransactionConfig<T extends object = Record<string, unknown>> {
 }
 
 /**
- * Options for the useOptimisticMutation hook
+ * Options for the createOptimisticAction helper
  */
 export interface CreateOptimisticActionsOptions<TVars = unknown>
   extends Omit<TransactionConfig, `mutationFn`> {
diff --git a/packages/react-db/src/index.ts b/packages/react-db/src/index.ts
index 991790fe..bd98349f 100644
--- a/packages/react-db/src/index.ts
+++ b/packages/react-db/src/index.ts
@@ -1,5 +1,4 @@
 // Re-export all public APIs
-export * from "./useOptimisticMutation"
 export * from "./useLiveQuery"
 
 // Re-export everything from @tanstack/db
diff --git a/packages/vue-db/src/index.ts b/packages/vue-db/src/index.ts
index 991790fe..bd98349f 100644
--- a/packages/vue-db/src/index.ts
+++ b/packages/vue-db/src/index.ts
@@ -1,5 +1,4 @@
 // Re-export all public APIs
-export * from "./useOptimisticMutation"
 export * from "./useLiveQuery"
 
 // Re-export everything from @tanstack/db

From 893f2c76792e11594342c634d17e24a20a87f7ee Mon Sep 17 00:00:00 2001
From: Kyle Mathews <mathews.kyle@gmail.com>
Date: Thu, 26 Jun 2025 11:40:53 -0600
Subject: [PATCH 4/8] improve changelog

---
 .changeset/solid-pandas-draw.md | 48 +++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/.changeset/solid-pandas-draw.md b/.changeset/solid-pandas-draw.md
index 150c8871..0fa5001e 100644
--- a/.changeset/solid-pandas-draw.md
+++ b/.changeset/solid-pandas-draw.md
@@ -5,3 +5,51 @@
 ---
 
 Add createOptimisticAction helper that replaces useOptimisticMutation
+
+An example of converting a `useOptimisticMutation` hook to `createOptimisticAction`. Now all optimistic & server mutation logic are consolidated.
+
+```diff
+-import { useOptimisticMutation } from '@tanstack/react-db'
++import { createOptimisticAction } from '@tanstack/react-db'
++
++// Create the `addTodo` action, passing in your `mutationFn` and `onMutate`.
++const addTodo = createOptimisticAction<string>({
++  onMutate: (text) => {
++    // Instantly applies the local optimistic state.
++    todoCollection.insert({
++      id: uuid(),
++      text,
++      completed: false
++    })
++  },
++  mutationFn: async (text) => {
++    // Persist the todo to your backend
++    const response = await fetch('/api/todos', {
++      method: 'POST',
++      body: JSON.stringify({ text, completed: false }),
++    })
++    return response.json()
++  }
++})
+ 
+ const Todo = () => {
+-  // Create the `addTodo` mutator, passing in your `mutationFn`.
+-  const addTodo = useOptimisticMutation({ mutationFn })
+-
+   const handleClick = () => {
+-    // Triggers the mutationFn
+-    addTodo.mutate(() =>
+-      // Instantly applies the local optimistic state.
+-      todoCollection.insert({
+-        id: uuid(),
+-        text: '🔥 Make app faster',
+-        completed: false
+-      })
+-    )
++    // Triggers the onMutate and then the mutationFn
++    addTodo('🔥 Make app faster')
+   }
+ 
+   return <Button onClick={ handleClick } />
+ }
+```

From 44dd13bbde359374ea87ca79cfdc93bc83aa817d Mon Sep 17 00:00:00 2001
From: Kyle Mathews <mathews.kyle@gmail.com>
Date: Thu, 26 Jun 2025 11:47:27 -0600
Subject: [PATCH 5/8] prettier

---
 .changeset/solid-pandas-draw.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.changeset/solid-pandas-draw.md b/.changeset/solid-pandas-draw.md
index 0fa5001e..d7a90add 100644
--- a/.changeset/solid-pandas-draw.md
+++ b/.changeset/solid-pandas-draw.md
@@ -31,7 +31,7 @@ An example of converting a `useOptimisticMutation` hook to `createOptimisticActi
 +    return response.json()
 +  }
 +})
- 
+
  const Todo = () => {
 -  // Create the `addTodo` mutator, passing in your `mutationFn`.
 -  const addTodo = useOptimisticMutation({ mutationFn })
@@ -49,7 +49,7 @@ An example of converting a `useOptimisticMutation` hook to `createOptimisticActi
 +    // Triggers the onMutate and then the mutationFn
 +    addTodo('🔥 Make app faster')
    }
- 
+
    return <Button onClick={ handleClick } />
  }
 ```

From a87d2e82df5e89e0654cd0bfa8e2fe9637530df9 Mon Sep 17 00:00:00 2001
From: Kyle Mathews <mathews.kyle@gmail.com>
Date: Thu, 26 Jun 2025 11:50:15 -0600
Subject: [PATCH 6/8] fix comment

---
 packages/db/src/optimistic-action.ts | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/db/src/optimistic-action.ts b/packages/db/src/optimistic-action.ts
index b23dbddf..8cfff527 100644
--- a/packages/db/src/optimistic-action.ts
+++ b/packages/db/src/optimistic-action.ts
@@ -16,7 +16,8 @@ export function createOptimisticAction<TVariables = unknown>(
       },
     })
 
-    // Execute the transaction (no callback needed since onMutate was already called)
+    // Execute the transaction. The mutationFn is called once mutate()
+    // is finished.
     transaction.mutate(() => {
       // Call onMutate with variables to apply optimistic updates
       onMutate(variables)

From b7149a35f0ac047eeb06a27b592a5e356b628a34 Mon Sep 17 00:00:00 2001
From: Kyle Mathews <mathews.kyle@gmail.com>
Date: Thu, 26 Jun 2025 11:52:04 -0600
Subject: [PATCH 7/8] jsdoc

---
 packages/db/src/optimistic-action.ts | 37 ++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/packages/db/src/optimistic-action.ts b/packages/db/src/optimistic-action.ts
index 8cfff527..83db572b 100644
--- a/packages/db/src/optimistic-action.ts
+++ b/packages/db/src/optimistic-action.ts
@@ -1,6 +1,43 @@
 import { createTransaction } from "./transactions"
 import type { CreateOptimisticActionsOptions, Transaction } from "./types"
 
+/**
+ * Creates an optimistic action function that applies local optimistic updates immediately
+ * before executing the actual mutation on the server.
+ *
+ * This pattern allows for responsive UI updates while the actual mutation is in progress.
+ * The optimistic update is applied via the `onMutate` callback, and the server mutation
+ * is executed via the `mutationFn`.
+ *
+ * @example
+ * ```ts
+ * const addTodo = createOptimisticAction<string>({
+ *   onMutate: (text) => {
+ *     // Instantly applies local optimistic state
+ *     todoCollection.insert({
+ *       id: uuid(),
+ *       text,
+ *       completed: false
+ *     })
+ *   },
+ *   mutationFn: async (text, params) => {
+ *     // Persist the todo to your backend
+ *     const response = await fetch('/api/todos', {
+ *       method: 'POST',
+ *       body: JSON.stringify({ text, completed: false }),
+ *     })
+ *     return response.json()
+ *   }
+ * })
+ *
+ * // Usage
+ * const transaction = addTodo('New Todo Item')
+ * ```
+ *
+ * @template TVariables - The type of variables that will be passed to the action function
+ * @param options - Configuration options for the optimistic action
+ * @returns A function that accepts variables of type TVariables and returns a Transaction
+ */
 export function createOptimisticAction<TVariables = unknown>(
   options: CreateOptimisticActionsOptions<TVariables>
 ) {

From 5fff068bb0e387fca687d89bebd09a2a4a1d8da3 Mon Sep 17 00:00:00 2001
From: Kyle Mathews <mathews.kyle@gmail.com>
Date: Thu, 26 Jun 2025 11:53:41 -0600
Subject: [PATCH 8/8] tweak doc

---
 docs/overview.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/overview.md b/docs/overview.md
index 98a62d0a..811c4a16 100644
--- a/docs/overview.md
+++ b/docs/overview.md
@@ -425,7 +425,7 @@ const Todo = () => {
 ## Manual Transactions
 
 By manually creating transactions, you can fully control their lifecycles and behaviors. `createOptimisticAction` is a ~25 line
-function which implements a common transaction pattern. Feel free to invent your own patterns and hooks!
+function which implements a common transaction pattern. Feel free to invent your own patterns!
 
 
 Here's one way you could use transactions.