Merge pull request #53 from guendev/yyy

refactor(useMutation): remove `onOptimistic` hook and related documentation

Author: guendev

.changeset/fifty-months-cough.md

@@ -0,0 +1,6 @@
+---
+"@vue3-apollo/core": patch
+"@vue3-apollo/nuxt": patch
+---
+
+refactor(useMutation): remove `onOptimistic` hook and related documentation

packages/core/src/composables/useMutation.ts

@@ -93,12 +93,6 @@ export function useMutation<
 
     const onDone = createEventHook<[TData, HookContext]>()
     const onError = createEventHook<[ErrorLike, HookContext]>()
-    /**
-     * Event hook that fires when an optimistic response is provided for the mutation.
-     * This is useful to react immediately to UI updates that occur before the
-     * actual network response is received.
-     */
-    const onOptimistic = createEventHook<[TData, HookContext]>()
 
     useApolloTracking({
         state: loading,
@@ -114,16 +108,6 @@ export function useMutation<
         called.value = true
 
         try {
-            // If an optimistic response was provided, notify listeners.
-            // This event is intended to reflect the immediate optimistic update phase.
-            const optimisticSource = mutateOptions?.optimisticResponse ?? options?.optimisticResponse
-            if (optimisticSource) {
-                const optimisticData = typeof optimisticSource === 'function'
-                    ? (optimisticSource as (vars?: TVariables) => TData)(variables)
-                    : optimisticSource
-                void onOptimistic.trigger(optimisticData as TData, { client })
-            }
-
             const result = await client.mutate<TData, TVariables, TCache>({
                 mutation: toValue(document),
                 variables: variables as TVariables ?? undefined,
@@ -243,20 +227,6 @@ export function useMutation<
          */
         onError: onError.on,
 
-        /**
-         * Event hook that fires when an optimistic response is provided for the mutation.
-         * Useful to react to immediate UI updates before the real response arrives.
-         *
-         * @example
-         * ```ts
-         * onOptimistic((optimisticData) => {
-         *   // e.g. set a temporary flag or log optimistic changes
-         *   console.log('Optimistic update:', optimisticData)
-         * })
-         * ```
-         */
-        onOptimistic: onOptimistic.on,
-
         /**
          * Reset the mutation state to initial values.
          * Clears data, error, loading, and called flags.

packages/docs/composables/useMutation.md

@@ -24,7 +24,6 @@ const {
   loading,
   mutate,
   onDone,
-  onOptimistic,
 } = useMutation(CREATE_POST)
 
 async function submit() {
@@ -40,10 +39,6 @@ async function submit() {
 onDone((payload) => {
   console.log('Created post:', payload)
 })
-
-onOptimistic((payload) => {
-  console.log('Optimistic create:', payload)
-})
 ```
 
 ## API
@@ -57,7 +52,6 @@ const {
   called,
   onDone,
   onError,
-  onOptimistic,
   reset,
 } = useMutation(document, options)
 ```
@@ -94,25 +88,6 @@ const {
       context.client.clearStore()
   })
   ```
-- **`onOptimistic((optimisticData, context) => {})`** – Fires when an `optimisticResponse` is provided for the mutation (either via base `options` or per‑call `mutateOptions`). Use this to react immediately to optimistic UI updates before the real network response arrives. The `context` contains the active Apollo client.
-  ```ts
-  const { mutate, onOptimistic } = useMutation(CREATE_POST, {
-    optimisticResponse: (vars) => ({
-      createPost: {
-        __typename: 'Post',
-        id: -1,
-        ...vars
-      }
-    })
-  })
-
-  onOptimistic((optimisticData, context) => {
-    // Example: mark a list item as "pending" using a temporary id
-    console.log('Optimistic:', optimisticData)
-    // You may also access the client if you need manual cache tweaks
-    // context.client.cache.modify(...)
-  })
-  ```
 - **`reset()`** – clear `data`, `error`, `loading`, and `called` back to initial state.
 
 ## Options
@@ -125,16 +100,3 @@ Pass as the second argument to `useMutation`.
 - **Apollo mutate options** (except `mutation` & `variables`, which are provided): `refetchQueries`, `awaitRefetchQueries`, `optimisticResponse`, `update`, `context`, etc.
   - When `optimisticResponse` is provided, the `onOptimistic` hook will fire with the optimistic data.
  - **`clientId`** (from `UseBaseOption`) – target a specific Apollo client if you registered multiple.
-
-## Why both `onOptimistic` and `onDone`?
-
-- `onOptimistic` runs as soon as an `optimisticResponse` is applied. Use it to:
-  - provide instant feedback (e.g., add a temporary item, disable buttons)
-  - annotate UI as pending (temporary ids, spinners)
-  - optionally tweak cache immediately if needed
-- `onDone` runs after the real network response succeeds. Use it to:
-  - finalize UI with authoritative data from the server
-  - perform navigation, toasts, or follow‑up actions that should only happen on actual success
-  - reconcile or replace any optimistic placeholders (e.g., swap temp id with real id)
-
-These two hooks let you clearly separate the optimistic phase from the confirmed success phase, leading to predictable UI flows.

packages/web/src/App.vue

@@ -26,16 +26,12 @@ const { error, result } = useQuery(PostsDocument, vars, {
 
 const title = ref('')
 
-const { loading, mutate, onDone: onUpdatedPost, onOptimistic } = useMutation(UpdatePostDocument)
+const { loading, mutate, onDone: onUpdatedPost } = useMutation(UpdatePostDocument)
 
 onUpdatedPost((data) => {
     console.warn('onUpdatedPost', data)
 })
 
-onOptimistic((data) => {
-    console.warn('onOptimistic', data)
-})
-
 const { data } = useFragment(computed(() => PostDetailFragmentDoc), {
     from: {
         __typename: 'Post',