@navios/react-query 0.5.2 → 0.6.1

package/CHANGELOG.md

@@ -1,31 +1,72 @@
 # Changelog
 
-## [0.5.2] - Dec 13, 2025
+## [0.6.0] - Dec 13, 2025
+
+### Breaking Changes
+
+- **Mutation callback signatures changed** - The `onSuccess`, `onError`, `onMutate`, and `onSettled` callbacks now use a unified context-based signature instead of receiving `queryClient` as the first parameter:
+
+  **Before (0.5.x):**
+  ```typescript
+  const mutation = client.mutation({
+    onSuccess: (queryClient, data, variables) => {
+      queryClient.invalidateQueries({ queryKey: ['users'] })
+    },
+    onError: (queryClient, error, variables) => {
+      console.error(error)
+    },
+  })
+  ```
+
+  **After (0.6.0):**
+  ```typescript
+  const mutation = client.mutation({
+    onSuccess: (data, variables, context) => {
+      // Access queryClient via useContext if needed
+      context.queryClient.invalidateQueries({ queryKey: ['users'] })
+    },
+    onError: (error, variables, context) => {
+      console.error(error)
+    },
+    onMutate: (variables, context) => {
+      // Return value is available in other callbacks as context.onMutateResult
+      return { previousData: context.queryClient.getQueryData(['users']) }
+    },
+    onSettled: (data, error, variables, context) => {
+      // Called on both success and error
+      // context.onMutateResult contains the return value from onMutate
+    },
+    useContext: () => {
+      const queryClient = useQueryClient()
+      return { queryClient }
+    },
+  })
+  ```
+
+- **New `TOnMutateResult` type parameter** - `MutationParams` now includes a `TOnMutateResult` generic for typing the return value of `onMutate`, which is passed to other callbacks via `context.onMutateResult`.
 
 ### Added
 
+- **`onMutate` callback** - Called before the mutation executes. The return value is available in `onSuccess`, `onError`, and `onSettled` callbacks via `context.onMutateResult`. This enables optimistic updates pattern.
+
+- **`onSettled` callback** - Called after the mutation completes (success or failure). Receives `data` (undefined on error), `error` (null on success), `variables`, and `context`.
+
+- **`MutationFunctionContext` integration** - All callbacks now receive TanStack Query's `MutationFunctionContext` merged with your custom context, providing access to `mutationId` and `meta`.
+
 - **Stream mutation support** - `mutationFromEndpoint` now supports stream endpoints created with `api.declareStream()`. This enables file downloads and other blob responses in mutations.
 
   ```typescript
-  // Create a stream endpoint
   const downloadFile = api.declareStream({
     method: 'GET',
     url: '/files/$id/download',
   })
 
-  // Use it with mutationFromEndpoint - processResponse is optional
   const useDownloadFile = client.mutationFromEndpoint(downloadFile, {
-    onSuccess: (queryClient, blob, variables) => {
-      // blob is typed as Blob
+    onSuccess: (blob, variables, context) => {
       const url = URL.createObjectURL(blob)
       window.open(url)
     },
   })
-
-  // Or transform the response
-  const useDownloadFile2 = client.mutationFromEndpoint(downloadFile, {
-    processResponse: (blob) => URL.createObjectURL(blob),
-  })
   ```
 
 - **New `StreamHelper` type** - Helper type that attaches stream endpoint to mutation results, similar to `EndpointHelper` for regular endpoints.