add (and require) `onMutate` hook to useOptimisticMutation so logic is fully encapsulated

[KyleAMathews]

Right now with useOptimisticMutation you write logic like:

import { useOptimisticMutation } from '@tanstack/react-db'

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
      })
    )
  }

  return <Button onClick={ handleClick } />
}

The problem with this though is it splits logic between the useOptimisticMutation hook & the .mutate call site.

If we add a onMutate hook then you could write:

import { useOptimisticMutation } from '@tanstack/react-db'

const Todo = () => {
  // Create the `addTodo` mutator, passing in your `mutationFn`.
  const addTodo = useOptimisticMutation({
    mutationFn,
    onMutate: (text) => {
      // Instantly applies the local optimistic state.
      todoCollection.insert({
        id: uuid(),
        text,
        completed: false
      })
    }
  })

  const handleClick = () => {
    // Triggers the `onMutate`
    addTodo.mutate('🔥 Make app faster')
  }

  return <Button onClick={ handleClick } />
}

[KyleAMathews]

@DawidWraga pushed on this proposal on Discord that this didn't need to be a hook but could just be a pure action creator. Which I think is spot on — so now I'm thinking we do something like this:

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 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
  }
}

// Usage
const addTodo = createOptimisticAction({ 
  onMutate: ({ variables: text }) => 
    todoCollection.insert({ text }),
  mutationFn: ({ variables: text }) => 
    api.addTodo(text)
})

// later in component
addTodo(event.target.value)

We also discussed how this would make it easier to revisit collection actions e.g.

const collection = createCollection({
  ...config,
  actions: {
    add: createOptimisticMutation({ onMutate, mutationFn }),
    toggle: ({ variables: todo, collection }) => 
      collection.update(todo, (draft) => draft.completed = !draft.completed))
  }
})

// later in component
collection.add(`new todo`)
collection.toggle(todo)

[samwillis]

I like it!

Can I suggest args (or arguments) over variables. Maybe even just arg as it's the first arg only, and then can be destructured or used directly as an object.

[KyleAMathews]

I used variables as that's what TanStack/Query uses — https://tanstack.com/query/latest/docs/framework/react/guides/mutations

The name seems pretty arbitrary to me? Open to arguments one way or another.

I put variables in the object to maintain compatibility with the mutationFn parameters — so it's just one more key. But perhaps actions are distinct enough API that people will be fine with moving the regular mutationFn params to the second argument.