@navios/react-query 0.5.1 → 0.6.0

package/src/__tests__/make-mutation.spec.mts

@@ -10,6 +10,7 @@ import { makeMutation } from '../mutation/make-hook.mjs'
 
 vi.mock('@tanstack/react-query', async (importReal) => {
   const actual = await importReal<typeof import('@tanstack/react-query')>()
+  const mockMutationContext = { mutationId: 1, meta: undefined }
   return {
     ...actual,
     useQueryClient: () => ({
@@ -22,11 +23,27 @@ vi.mock('@tanstack/react-query', async (importReal) => {
       ...req,
       mutateAsync: async (data: unknown) => {
         try {
+          const onMutateResult = await req.onMutate?.(data, mockMutationContext)
           const res = await req.mutationFn(data)
-          await req.onSuccess?.(res, data)
+          await req.onSuccess?.(res, data, onMutateResult, mockMutationContext)
+          await req.onSettled?.(
+            res,
+            null,
+            data,
+            onMutateResult,
+            mockMutationContext,
+          )
           return res
         } catch (err) {
-          req.onError?.(err, data)
+          const onMutateResult = undefined
+          await req.onError?.(err, data, onMutateResult, mockMutationContext)
+          await req.onSettled?.(
+            undefined,
+            err,
+            data,
+            onMutateResult,
+            mockMutationContext,
+          )
           throw err
         }
       },
@@ -77,7 +94,7 @@ describe('makeMutation', () => {
         }
         return data
       },
-      onSuccess: (queryClient, data, variables) => {
+      onSuccess: (data, variables, context) => {
         expect(data).toMatchObject({
           success: true,
           test: 'test',
@@ -95,10 +112,12 @@ describe('makeMutation', () => {
             foo: 'bar',
           },
         })
+        expect(context).toHaveProperty('mutationId')
+        expect(context).toHaveProperty('onMutateResult')
       },
 
-      onError: (err) => {
-        console.log('onError', err)
+      onError: (err, _variables, context) => {
+        console.log('onError', err, context)
       },
     })
     // @ts-expect-error internal type
@@ -137,4 +156,194 @@ describe('makeMutation', () => {
     // @ts-expect-error from mock
     expect(mutationResult.mutationKey).toMatchObject(['test', '1', 'foo', '2'])
   })
+
+  describe('stream mutations', () => {
+    const streamEndpoint = api.declareStream({
+      method: 'GET',
+      url: '/files/$fileId/download' as const,
+    })
+
+    adapter.mock('/files/123/download', 'GET', () => {
+      const blob = new Blob(['test file content'], { type: 'text/plain' })
+      return new Response(blob, {
+        status: 200,
+        statusText: 'OK',
+        headers: {
+          'content-type': 'application/octet-stream',
+        },
+      })
+    })
+
+    it('should work without processResponse (returns Blob)', async () => {
+      // @ts-expect-error stream endpoint type differs from regular endpoint
+      const mutation = makeMutation(streamEndpoint, {})
+      // @ts-expect-error internal type
+      const mutationResult = mutation()
+
+      const result = await mutationResult.mutateAsync({
+        urlParams: { fileId: '123' },
+      })
+
+      expect(result).toBeInstanceOf(Blob)
+    })
+
+    it('should work with processResponse transformation', async () => {
+      // @ts-expect-error stream endpoint type differs from regular endpoint
+      const mutation = makeMutation(streamEndpoint, {
+        processResponse: (blob: Blob) => URL.createObjectURL(blob),
+      })
+      // @ts-expect-error internal type
+      const mutationResult = mutation()
+
+      const result = await mutationResult.mutateAsync({
+        urlParams: { fileId: '123' },
+      })
+
+      expect(typeof result).toBe('string')
+      expect(result).toContain('blob:')
+    })
+
+    it('should call onSuccess with Blob data and context', async () => {
+      const onSuccess = vi.fn()
+      // @ts-expect-error stream endpoint type differs from regular endpoint
+      const mutation = makeMutation(streamEndpoint, {
+        onSuccess,
+      })
+      // @ts-expect-error internal type
+      const mutationResult = mutation()
+
+      await mutationResult.mutateAsync({
+        urlParams: { fileId: '123' },
+      })
+
+      expect(onSuccess).toHaveBeenCalledTimes(1)
+      expect(onSuccess.mock.calls[0][0]).toBeInstanceOf(Blob)
+      expect(onSuccess.mock.calls[0][1]).toMatchObject({
+        urlParams: { fileId: '123' },
+      })
+      // Third argument should be context with onMutateResult and mutationId
+      expect(onSuccess.mock.calls[0][2]).toHaveProperty('onMutateResult')
+      expect(onSuccess.mock.calls[0][2]).toHaveProperty('mutationId')
+    })
+  })
+
+  describe('mutation callbacks', () => {
+    it('should call onMutate before mutation and pass result to other callbacks', async () => {
+      const callOrder: string[] = []
+      const onMutate = vi.fn((_variables, _context) => {
+        callOrder.push('onMutate')
+        return { optimisticId: 'temp-123' }
+      })
+      const onSuccess = vi.fn((_data, _variables, context) => {
+        callOrder.push('onSuccess')
+        expect(context.onMutateResult).toEqual({ optimisticId: 'temp-123' })
+      })
+      const onSettled = vi.fn((_data, _error, _variables, context) => {
+        callOrder.push('onSettled')
+        expect(context.onMutateResult).toEqual({ optimisticId: 'temp-123' })
+      })
+
+      const mutation = makeMutation(endpoint, {
+        processResponse: (data) => {
+          if (!data.success) throw new Error(data.message)
+          return data
+        },
+        onMutate,
+        onSuccess,
+        onSettled,
+      })
+
+      // @ts-expect-error internal type
+      const mutationResult = mutation()
+      await mutationResult.mutateAsync({
+        urlParams: { testId: '1', fooId: '2' },
+        data: { testId: '1', fooId: '2' },
+        params: { foo: 'bar' },
+      })
+
+      expect(callOrder).toEqual(['onMutate', 'onSuccess', 'onSettled'])
+      expect(onMutate).toHaveBeenCalledTimes(1)
+      expect(onSuccess).toHaveBeenCalledTimes(1)
+      expect(onSettled).toHaveBeenCalledTimes(1)
+    })
+
+    it('should call onError and onSettled on failure', async () => {
+      adapter.mock('/test/1/foo/2', 'POST', () => {
+        return new Response(
+          JSON.stringify({ success: false, message: 'Test error' }),
+          { status: 200, headers: { 'content-type': 'application/json' } },
+        )
+      })
+
+      const onError = vi.fn()
+      const onSettled = vi.fn()
+
+      const mutation = makeMutation(endpoint, {
+        processResponse: (data) => {
+          if (!data.success) throw new Error(data.message)
+          return data
+        },
+        onError,
+        onSettled,
+      })
+
+      // @ts-expect-error internal type
+      const mutationResult = mutation()
+
+      await expect(
+        mutationResult.mutateAsync({
+          urlParams: { testId: '1', fooId: '2' },
+          data: { testId: '1', fooId: '2' },
+          params: { foo: 'bar' },
+        }),
+      ).rejects.toThrow('Test error')
+
+      expect(onError).toHaveBeenCalledTimes(1)
+      expect(onError.mock.calls[0][0]).toBeInstanceOf(Error)
+      expect(onError.mock.calls[0][0].message).toBe('Test error')
+      expect(onSettled).toHaveBeenCalledTimes(1)
+      expect(onSettled.mock.calls[0][1]).toBeInstanceOf(Error)
+
+      // Restore the mock
+      adapter.mock('/test/1/foo/2', 'POST', () => {
+        return new Response(
+          JSON.stringify({ success: true, test: 'test' }),
+          { status: 200, headers: { 'content-type': 'application/json' } },
+        )
+      })
+    })
+
+    it('should merge useContext result with MutationFunctionContext', async () => {
+      const useContext = () => ({
+        queryClient: { invalidate: vi.fn() },
+        customValue: 'test',
+      })
+
+      const onSuccess = vi.fn()
+
+      const mutation = makeMutation(endpoint, {
+        processResponse: (data) => {
+          if (!data.success) throw new Error(data.message)
+          return data
+        },
+        useContext,
+        onSuccess,
+      })
+
+      // @ts-expect-error internal type
+      const mutationResult = mutation()
+      await mutationResult.mutateAsync({
+        urlParams: { testId: '1', fooId: '2' },
+        data: { testId: '1', fooId: '2' },
+        params: { foo: 'bar' },
+      })
+
+      expect(onSuccess).toHaveBeenCalledTimes(1)
+      const context = onSuccess.mock.calls[0][2]
+      expect(context).toHaveProperty('queryClient')
+      expect(context).toHaveProperty('customValue', 'test')
+      expect(context).toHaveProperty('mutationId')
+      expect(context).toHaveProperty('onMutateResult')
+    })
+  })
 })

package/src/client/__type-tests__/client-instance.spec-d.mts

@@ -10,11 +10,12 @@ import type { z } from 'zod/v4'
 import { assertType, describe, test } from 'vitest'
 import { z as zod } from 'zod/v4'
 
-import type { ClientInstance } from '../types.mjs'
+import type { ClientInstance, StreamHelper } from '../types.mjs'
 import type { QueryHelpers } from '../../query/types.mjs'
 import type { MutationHelpers } from '../../mutation/types.mjs'
 import type { EndpointHelper } from '../types.mjs'
 import type { Split } from '../../common/types.mjs'
+import type { BaseStreamConfig } from '@navios/builder'
 
 declare const client: ClientInstance
 
@@ -644,6 +645,155 @@ describe('ClientInstance', () => {
   })
 })
 
+// Stream endpoint type declarations for testing
+declare const streamEndpointGet: {
+  config: BaseStreamConfig<'GET', '/files/$fileId/download', undefined, undefined>
+} & ((params: { urlParams: { fileId: string | number } }) => Promise<Blob>)
+
+declare const streamEndpointGetWithQuery: {
+  config: BaseStreamConfig<
+    'GET',
+    '/files/$fileId/download',
+    typeof querySchema,
+    undefined
+  >
+} & ((params: {
+  urlParams: { fileId: string | number }
+  params: z.input<typeof querySchema>
+}) => Promise<Blob>)
+
+declare const streamEndpointPost: {
+  config: BaseStreamConfig<
+    'POST',
+    '/files/$fileId/export',
+    undefined,
+    typeof requestSchema
+  >
+} & ((params: {
+  urlParams: { fileId: string | number }
+  data: z.input<typeof requestSchema>
+}) => Promise<Blob>)
+
+describe('mutationFromEndpoint() with stream endpoints', () => {
+  test('GET stream mutation without options (returns Blob)', () => {
+    const mutation = client.mutationFromEndpoint(streamEndpointGet)
+
+    // Should return a function that returns UseMutationResult with Blob
+    assertType<
+      () => UseMutationResult<Blob, Error, { urlParams: { fileId: string | number } }>
+    >(mutation)
+
+    // Should have StreamHelper
+    assertType<
+      StreamHelper<'GET', '/files/$fileId/download', undefined, undefined>['endpoint']
+    >(mutation.endpoint)
+  })
+
+  test('GET stream mutation with processResponse transformation', () => {
+    const mutation = client.mutationFromEndpoint(streamEndpointGet, {
+      processResponse: (blob) => URL.createObjectURL(blob),
+    })
+
+    // Result type should be string (transformed)
+    assertType<
+      () => UseMutationResult<
+        string,
+        Error,
+        { urlParams: { fileId: string | number } }
+      >
+    >(mutation)
+  })
+
+  test('GET stream mutation with useKey', () => {
+    const mutation = client.mutationFromEndpoint(streamEndpointGet, {
+      useKey: true,
+    })
+
+    // With useKey, should require urlParams in the call
+    assertType<
+      (params: {
+        urlParams: { fileId: string | number }
+      }) => UseMutationResult<
+        Blob,
+        Error,
+        { urlParams: { fileId: string | number } }
+      >
+    >(mutation)
+
+    // Should have MutationHelpers
+    assertType<
+      MutationHelpers<'/files/$fileId/download', Blob>['mutationKey']
+    >(mutation.mutationKey)
+  })
+
+  test('GET stream mutation with querySchema', () => {
+    const mutation = client.mutationFromEndpoint(streamEndpointGetWithQuery)
+
+    assertType<
+      () => UseMutationResult<
+        Blob,
+        Error,
+        {
+          urlParams: { fileId: string | number }
+          params: z.input<typeof querySchema>
+        }
+      >
+    >(mutation)
+  })
+
+  test('POST stream mutation with requestSchema', () => {
+    const mutation = client.mutationFromEndpoint(streamEndpointPost)
+
+    assertType<
+      () => UseMutationResult<
+        Blob,
+        Error,
+        {
+          urlParams: { fileId: string | number }
+          data: z.input<typeof requestSchema>
+        }
+      >
+    >(mutation)
+  })
+
+  test('stream mutation with onSuccess callback', () => {
+    const mutation = client.mutationFromEndpoint(streamEndpointGet, {
+      onSuccess: (_queryClient, data, variables) => {
+        // data should be Blob
+        assertType<Blob>(data)
+        // variables should have urlParams
+        assertType<{ urlParams: { fileId: string | number } }>(variables)
+      },
+    })
+
+    assertType<
+      () => UseMutationResult<
+        Blob,
+        Error,
+        { urlParams: { fileId: string | number } }
+      >
+    >(mutation)
+  })
+
+  test('stream mutation with custom processResponse and onSuccess', () => {
+    const mutation = client.mutationFromEndpoint(streamEndpointGet, {
+      processResponse: (blob) => ({ url: URL.createObjectURL(blob), size: blob.size }),
+      onSuccess: (_queryClient, data) => {
+        // data should be the transformed type
+        assertType<{ url: string; size: number }>(data)
+      },
+    })
+
+    assertType<
+      () => UseMutationResult<
+        { url: string; size: number },
+        Error,
+        { urlParams: { fileId: string | number } }
+      >
+    >(mutation)
+  })
+})
+
 describe('Error cases - should fail type checking', () => {
   test('GET query without urlParams when URL has params', () => {
     const query = client.query({

package/src/client/declare-client.mts

@@ -1,12 +1,21 @@
 import type {
   AbstractEndpoint,
+  AbstractStream,
   AnyEndpointConfig,
+  AnyStreamConfig,
   HttpMethod,
 } from '@navios/builder'
-import type { InfiniteData, QueryClient } from '@tanstack/react-query'
+import type {
+  InfiniteData,
+  MutationFunctionContext,
+  QueryClient,
+} from '@tanstack/react-query'
 import type { z, ZodObject, ZodType } from 'zod/v4'
 
-import type { ClientOptions, ProcessResponseFunction } from '../common/types.mjs'
+import type {
+  ClientOptions,
+  ProcessResponseFunction,
+} from '../common/types.mjs'
 import type { MutationArgs } from '../mutation/types.mjs'
 import type { ClientInstance } from './types.mjs'
 
@@ -82,6 +91,7 @@ export interface MutationConfig<
   Response extends ZodType = ZodType,
   ReqResult = z.output<Response>,
   Result = unknown,
+  TOnMutateResult = unknown,
   Context = unknown,
   UseKey extends boolean = false,
 > {
@@ -93,18 +103,30 @@ export interface MutationConfig<
   processResponse: ProcessResponseFunction<Result, ReqResult>
   useContext?: () => Context
   onSuccess?: (
-    queryClient: QueryClient,
-    data: NoInfer<Result>,
+    data: Result,
     variables: MutationArgs<Url, RequestSchema, QuerySchema>,
-    context: Context,
+    context: Context &
+      MutationFunctionContext & { onMutateResult: TOnMutateResult | undefined },
   ) => void | Promise<void>
   onError?: (
-    queryClient: QueryClient,
-    error: Error,
+    err: unknown,
+    variables: MutationArgs<Url, RequestSchema, QuerySchema>,
+    context: Context &
+      MutationFunctionContext & { onMutateResult: TOnMutateResult | undefined },
+  ) => void | Promise<void>
+  onMutate?: (
+    variables: MutationArgs<Url, RequestSchema, QuerySchema>,
+    context: Context & MutationFunctionContext,
+  ) => TOnMutateResult | Promise<TOnMutateResult>
+  onSettled?: (
+    data: Result | undefined,
+    error: Error | null,
     variables: MutationArgs<Url, RequestSchema, QuerySchema>,
-    context: Context,
+    context: Context &
+      MutationFunctionContext & { onMutateResult: TOnMutateResult | undefined },
   ) => void | Promise<void>
   useKey?: UseKey
+  meta?: Record<string, unknown>
 }
 
 /**
@@ -235,6 +257,7 @@ export function declareClient<Options extends ClientOptions>({
       // @ts-expect-error We forgot about the DELETE method in original makeMutation
       onError: config.onError,
       useKey: config.useKey,
+      meta: config.meta,
       ...defaults,
     })
 
@@ -244,9 +267,11 @@ export function declareClient<Options extends ClientOptions>({
   }
 
   function mutationFromEndpoint(
-    endpoint: AbstractEndpoint<AnyEndpointConfig>,
-    options: {
-      processResponse: ProcessResponseFunction
+    endpoint:
+      | AbstractEndpoint<AnyEndpointConfig>
+      | AbstractStream<AnyStreamConfig>,
+    options?: {
+      processResponse?: ProcessResponseFunction
       useContext?: () => unknown
       onSuccess?: (
         queryClient: QueryClient,
@@ -262,12 +287,12 @@ export function declareClient<Options extends ClientOptions>({
       ) => void | Promise<void>
     },
   ) {
+    // @ts-expect-error endpoint types are compatible at runtime
     return makeMutation(endpoint, {
-      processResponse: options.processResponse,
-      useContext: options.useContext,
-      onSuccess: options.onSuccess,
-      // @ts-expect-error simplify types here
-      onError: options.onError,
+      processResponse: options?.processResponse,
+      useContext: options?.useContext,
+      onSuccess: options?.onSuccess,
+      onError: options?.onError,
       ...defaults,
     })
   }
@@ -289,6 +314,10 @@ export function declareClient<Options extends ClientOptions>({
       onSuccess: config.onSuccess,
       // @ts-expect-error We forgot about the DELETE method in original makeMutation
       onError: config.onError,
+      // @ts-expect-error We forgot about the DELETE method in original makeMutation
+      onMutate: config.onMutate,
+      // @ts-expect-error We forgot about the DELETE method in original makeMutation
+      onSettled: config.onSettled,
       useKey: config.useKey,
       ...defaults,
     })