@navios/react-query 0.5.1 → 0.6.0

package/src/client/types.mts

@@ -1,5 +1,6 @@
 import type {
   BaseEndpointConfig,
+  BaseStreamConfig,
   EndpointFunctionArgs,
   HttpMethod,
   UrlHasParams,
@@ -55,6 +56,24 @@ export type ClientEndpointHelper<
   QuerySchema = unknown,
 > = EndpointHelper<Method, Url, RequestSchema, ResponseSchema, QuerySchema>
 
+/**
+ * Helper type that attaches a stream endpoint to mutation results.
+ */
+export type StreamHelper<
+  Method extends HttpMethod = HttpMethod,
+  Url extends string = string,
+  RequestSchema = unknown,
+  QuerySchema = unknown,
+> = {
+  endpoint: ((
+    params: Util_FlatObject<
+      EndpointFunctionArgs<Url, QuerySchema, RequestSchema>
+    >,
+  ) => Promise<Blob>) & {
+    config: BaseStreamConfig<Method, Url, QuerySchema, RequestSchema>
+  }
+}
+
 /**
  * The main client instance interface.
  * Provides methods for creating queries, infinite queries, and mutations.
@@ -1133,4 +1152,308 @@ export interface ClientInstance {
   >) &
     MutationHelpers<Url, Result> &
     EndpointHelper<Method, Url, RequestSchema, Response>
+
+  // ============================================================================
+  // STREAM MUTATION FROM ENDPOINT METHODS
+  // ============================================================================
+
+  // Stream mutation with useKey, requestSchema, and querySchema
+  mutationFromEndpoint<
+    Method extends 'POST' | 'PUT' | 'PATCH' = 'POST' | 'PUT' | 'PATCH',
+    Url extends string = string,
+    RequestSchema extends ZodType = ZodType,
+    QuerySchema extends ZodObject = ZodObject,
+    Result = Blob,
+    Context = unknown,
+    UseKey extends true = true,
+  >(
+    endpoint: {
+      config: BaseStreamConfig<Method, Url, QuerySchema, RequestSchema>
+    },
+    mutationOptions: {
+      processResponse?: ProcessResponseFunction<Result, Blob>
+      useKey: UseKey
+      useContext?: () => Context
+      onSuccess?: (
+        queryClient: QueryClient,
+        data: NoInfer<Result>,
+        variables: Util_FlatObject<
+          MutationArgs<Url, RequestSchema, QuerySchema>
+        >,
+        context: Context,
+      ) => void | Promise<void>
+      onError?: (
+        queryClient: QueryClient,
+        error: Error,
+        variables: Util_FlatObject<
+          MutationArgs<Url, RequestSchema, QuerySchema>
+        >,
+        context: Context,
+      ) => void | Promise<void>
+    },
+  ): ((
+    params: UrlHasParams<Url> extends true ? { urlParams: UrlParams<Url> } : {},
+  ) => UseMutationResult<
+    Result,
+    Error,
+    MutationArgs<Url, RequestSchema, QuerySchema>
+  >) &
+    MutationHelpers<Url, Result> &
+    StreamHelper<Method, Url, RequestSchema, QuerySchema>
+
+  // Stream mutation without useKey, with requestSchema and querySchema
+  mutationFromEndpoint<
+    Method extends 'POST' | 'PUT' | 'PATCH' = 'POST' | 'PUT' | 'PATCH',
+    Url extends string = string,
+    RequestSchema extends ZodType = ZodType,
+    QuerySchema extends ZodObject = ZodObject,
+    Result = Blob,
+    Context = unknown,
+  >(
+    endpoint: {
+      config: BaseStreamConfig<Method, Url, QuerySchema, RequestSchema>
+    },
+    mutationOptions?: {
+      processResponse?: ProcessResponseFunction<Result, Blob>
+      useContext?: () => Context
+      onSuccess?: (
+        queryClient: QueryClient,
+        data: NoInfer<Result>,
+        variables: Util_FlatObject<
+          MutationArgs<Url, RequestSchema, QuerySchema>
+        >,
+        context: Context,
+      ) => void | Promise<void>
+      onError?: (
+        queryClient: QueryClient,
+        error: Error,
+        variables: Util_FlatObject<
+          MutationArgs<Url, RequestSchema, QuerySchema>
+        >,
+        context: Context,
+      ) => void | Promise<void>
+    },
+  ): (() => UseMutationResult<
+    Result,
+    Error,
+    MutationArgs<Url, RequestSchema, QuerySchema>
+  >) &
+    StreamHelper<Method, Url, RequestSchema, QuerySchema>
+
+  // Stream mutation with useKey, requestSchema only
+  mutationFromEndpoint<
+    Method extends 'POST' | 'PUT' | 'PATCH' = 'POST' | 'PUT' | 'PATCH',
+    Url extends string = string,
+    RequestSchema extends ZodType = ZodType,
+    Result = Blob,
+    Context = unknown,
+    UseKey extends true = true,
+  >(
+    endpoint: {
+      config: BaseStreamConfig<Method, Url, undefined, RequestSchema>
+    },
+    mutationOptions: {
+      processResponse?: ProcessResponseFunction<Result, Blob>
+      useKey: UseKey
+      useContext?: () => Context
+      onSuccess?: (
+        queryClient: QueryClient,
+        data: NoInfer<Result>,
+        variables: Util_FlatObject<MutationArgs<Url, RequestSchema, undefined>>,
+        context: Context,
+      ) => void | Promise<void>
+      onError?: (
+        queryClient: QueryClient,
+        error: Error,
+        variables: Util_FlatObject<MutationArgs<Url, RequestSchema, undefined>>,
+        context: Context,
+      ) => void | Promise<void>
+    },
+  ): ((
+    params: UrlHasParams<Url> extends true ? { urlParams: UrlParams<Url> } : {},
+  ) => UseMutationResult<
+    Result,
+    Error,
+    MutationArgs<Url, RequestSchema, undefined>
+  >) &
+    MutationHelpers<Url, Result> &
+    StreamHelper<Method, Url, RequestSchema, undefined>
+
+  // Stream mutation without useKey, with requestSchema only
+  mutationFromEndpoint<
+    Method extends 'POST' | 'PUT' | 'PATCH' = 'POST' | 'PUT' | 'PATCH',
+    Url extends string = string,
+    RequestSchema extends ZodType = ZodType,
+    Result = Blob,
+    Context = unknown,
+  >(
+    endpoint: {
+      config: BaseStreamConfig<Method, Url, undefined, RequestSchema>
+    },
+    mutationOptions?: {
+      processResponse?: ProcessResponseFunction<Result, Blob>
+      useContext?: () => Context
+      onSuccess?: (
+        queryClient: QueryClient,
+        data: NoInfer<Result>,
+        variables: Util_FlatObject<MutationArgs<Url, RequestSchema, undefined>>,
+        context: Context,
+      ) => void | Promise<void>
+      onError?: (
+        queryClient: QueryClient,
+        error: Error,
+        variables: Util_FlatObject<MutationArgs<Url, RequestSchema, undefined>>,
+        context: Context,
+      ) => void | Promise<void>
+    },
+  ): (() => UseMutationResult<
+    Result,
+    Error,
+    MutationArgs<Url, RequestSchema, undefined>
+  >) &
+    StreamHelper<Method, Url, RequestSchema, undefined>
+
+  // Stream mutation GET methods with useKey and querySchema
+  mutationFromEndpoint<
+    Method extends 'GET' | 'DELETE' | 'OPTIONS' | 'HEAD' = 'GET',
+    Url extends string = string,
+    QuerySchema extends ZodObject = ZodObject,
+    Result = Blob,
+    Context = unknown,
+    UseKey extends true = true,
+  >(
+    endpoint: {
+      config: BaseStreamConfig<Method, Url, QuerySchema, undefined>
+    },
+    mutationOptions: {
+      processResponse?: ProcessResponseFunction<Result, Blob>
+      useKey: UseKey
+      useContext?: () => Context
+      onSuccess?: (
+        queryClient: QueryClient,
+        data: NoInfer<Result>,
+        variables: Util_FlatObject<MutationArgs<Url, undefined, QuerySchema>>,
+        context: Context,
+      ) => void | Promise<void>
+      onError?: (
+        queryClient: QueryClient,
+        error: Error,
+        variables: Util_FlatObject<MutationArgs<Url, undefined, QuerySchema>>,
+        context: Context,
+      ) => void | Promise<void>
+    },
+  ): ((
+    params: UrlHasParams<Url> extends true ? { urlParams: UrlParams<Url> } : {},
+  ) => UseMutationResult<
+    Result,
+    Error,
+    MutationArgs<Url, undefined, QuerySchema>
+  >) &
+    MutationHelpers<Url, Result> &
+    StreamHelper<Method, Url, undefined, QuerySchema>
+
+  // Stream mutation GET methods without useKey, with querySchema
+  mutationFromEndpoint<
+    Method extends 'GET' | 'DELETE' | 'OPTIONS' | 'HEAD' = 'GET',
+    Url extends string = string,
+    QuerySchema extends ZodObject = ZodObject,
+    Result = Blob,
+    Context = unknown,
+  >(
+    endpoint: {
+      config: BaseStreamConfig<Method, Url, QuerySchema, undefined>
+    },
+    mutationOptions?: {
+      processResponse?: ProcessResponseFunction<Result, Blob>
+      useContext?: () => Context
+      onSuccess?: (
+        queryClient: QueryClient,
+        data: NoInfer<Result>,
+        variables: Util_FlatObject<MutationArgs<Url, undefined, QuerySchema>>,
+        context: Context,
+      ) => void | Promise<void>
+      onError?: (
+        queryClient: QueryClient,
+        error: Error,
+        variables: Util_FlatObject<MutationArgs<Url, undefined, QuerySchema>>,
+        context: Context,
+      ) => void | Promise<void>
+    },
+  ): (() => UseMutationResult<
+    Result,
+    Error,
+    MutationArgs<Url, undefined, QuerySchema>
+  >) &
+    StreamHelper<Method, Url, undefined, QuerySchema>
+
+  // Stream mutation GET methods with useKey only (no schemas)
+  mutationFromEndpoint<
+    Method extends 'GET' | 'DELETE' | 'OPTIONS' | 'HEAD' = 'GET',
+    Url extends string = string,
+    Result = Blob,
+    Context = unknown,
+    UseKey extends true = true,
+  >(
+    endpoint: {
+      config: BaseStreamConfig<Method, Url, undefined, undefined>
+    },
+    mutationOptions: {
+      processResponse?: ProcessResponseFunction<Result, Blob>
+      useKey: UseKey
+      useContext?: () => Context
+      onSuccess?: (
+        queryClient: QueryClient,
+        data: NoInfer<Result>,
+        variables: Util_FlatObject<MutationArgs<Url, undefined, undefined>>,
+        context: Context,
+      ) => void | Promise<void>
+      onError?: (
+        queryClient: QueryClient,
+        error: Error,
+        variables: Util_FlatObject<MutationArgs<Url, undefined, undefined>>,
+        context: Context,
+      ) => void | Promise<void>
+    },
+  ): ((
+    params: UrlHasParams<Url> extends true ? { urlParams: UrlParams<Url> } : {},
+  ) => UseMutationResult<
+    Result,
+    Error,
+    MutationArgs<Url, undefined, undefined>
+  >) &
+    MutationHelpers<Url, Result> &
+    StreamHelper<Method, Url, undefined, undefined>
+
+  // Stream mutation GET methods without useKey (no schemas)
+  mutationFromEndpoint<
+    Method extends 'GET' | 'DELETE' | 'OPTIONS' | 'HEAD' = 'GET',
+    Url extends string = string,
+    Result = Blob,
+    Context = unknown,
+  >(
+    endpoint: {
+      config: BaseStreamConfig<Method, Url, undefined, undefined>
+    },
+    mutationOptions?: {
+      processResponse?: ProcessResponseFunction<Result, Blob>
+      useContext?: () => Context
+      onSuccess?: (
+        queryClient: QueryClient,
+        data: NoInfer<Result>,
+        variables: Util_FlatObject<MutationArgs<Url, undefined, undefined>>,
+        context: Context,
+      ) => void | Promise<void>
+      onError?: (
+        queryClient: QueryClient,
+        error: Error,
+        variables: Util_FlatObject<MutationArgs<Url, undefined, undefined>>,
+        context: Context,
+      ) => void | Promise<void>
+    },
+  ): (() => UseMutationResult<
+    Result,
+    Error,
+    MutationArgs<Url, undefined, undefined>
+  >) &
+    StreamHelper<Method, Url, undefined, undefined>
 }

package/src/mutation/make-hook.mts

@@ -5,14 +5,13 @@ import type {
   UrlHasParams,
   UrlParams,
 } from '@navios/builder'
-import type { UseMutationResult } from '@tanstack/react-query'
+import type {
+  MutationFunctionContext,
+  UseMutationResult,
+} from '@tanstack/react-query'
 import type { z } from 'zod/v4'
 
-import {
-  useIsMutating,
-  useMutation,
-  useQueryClient,
-} from '@tanstack/react-query'
+import { useIsMutating, useMutation } from '@tanstack/react-query'
 
 import type { MutationParams } from './types.mjs'
 
@@ -33,6 +32,7 @@ export function makeMutation<
   TData = unknown,
   TVariables extends NaviosZodRequest<Config> = NaviosZodRequest<Config>,
   TResponse = z.output<Config['responseSchema']>,
+  TOnMutateResult = unknown,
   TContext = unknown,
   UseKey extends boolean = false,
 >(
@@ -42,70 +42,127 @@ export function makeMutation<
     TData,
     TVariables,
     TResponse,
+    TOnMutateResult,
     TContext,
     UseKey
   >,
 ) {
   const config = endpoint.config
 
-  const mutationKey = createMutationKey(config, options)
+  const mutationKey = createMutationKey(config, {
+    ...options,
+    processResponse: options.processResponse ?? ((data) => data),
+  })
   const result = (
     keyParams: UseKey extends true
       ? UrlHasParams<Config['url']> extends true
         ? UrlParams<Config['url']>
         : never
       : never,
-  ): UseMutationResult<TData, Error, NaviosZodRequest<Config>> => {
-    const queryClient = useQueryClient()
+  ): UseMutationResult<
+    TData,
+    Error,
+    NaviosZodRequest<Config>,
+    TOnMutateResult
+  > => {
     const {
       useKey,
       useContext,
+      onMutate,
       onError,
       onSuccess,
+      onSettled,
       keyPrefix: _keyPrefix,
       keySuffix: _keySuffix,
       processResponse,
       ...rest
     } = options
 
-    const context = useContext?.() as TContext
+    const ownContext = (useContext?.() as TContext) ?? {}
 
     // @ts-expect-error The types match
-    return useMutation(
-      {
-        ...rest,
-        mutationKey: useKey
-          ? mutationKey({
-              urlParams: keyParams,
-            })
-          : undefined,
-        scope: useKey
-          ? {
-              id: JSON.stringify(
-                mutationKey({
-                  urlParams: keyParams,
-                }),
-              ),
-            }
-          : undefined,
-        async mutationFn(params: TVariables) {
-          const response = await endpoint(params)
+    return useMutation({
+      ...rest,
+      mutationKey: useKey
+        ? mutationKey({
+            urlParams: keyParams,
+          })
+        : undefined,
+      scope: useKey
+        ? {
+            id: JSON.stringify(
+              mutationKey({
+                urlParams: keyParams,
+              }),
+            ),
+          }
+        : undefined,
+      async mutationFn(params: TVariables) {
+        const response = await endpoint(params)
 
-          return processResponse(response) as TData
-        },
-        onSuccess: onSuccess
-          ? (data: TData, variables: TVariables) => {
-              return onSuccess?.(queryClient, data, variables, context)
-            }
-          : undefined,
-        onError: onError
-          ? (err: Error, variables: TVariables) => {
-              return onError?.(queryClient, err, variables, context)
-            }
-          : undefined,
+        return (processResponse ? processResponse(response) : response) as TData
       },
-      queryClient,
-    )
+      onSuccess: onSuccess
+        ? (
+            data: TData,
+            variables: TVariables,
+            onMutateResult: TOnMutateResult | undefined,
+            context: MutationFunctionContext,
+          ) => {
+            return onSuccess?.(data, variables, {
+              ...ownContext,
+              ...context,
+              onMutateResult,
+            } as TContext &
+              MutationFunctionContext & {
+                onMutateResult: TOnMutateResult | undefined
+              })
+          }
+        : undefined,
+      onError: onError
+        ? (
+            err: Error,
+            variables: TVariables,
+            onMutateResult: TOnMutateResult | undefined,
+            context: MutationFunctionContext,
+          ) => {
+            return onError?.(err, variables, {
+              onMutateResult,
+              ...ownContext,
+              ...context,
+            } as TContext &
+              MutationFunctionContext & {
+                onMutateResult: TOnMutateResult | undefined
+              })
+          }
+        : undefined,
+      onMutate: onMutate
+        ? (variables: TVariables, context: MutationFunctionContext) => {
+            return onMutate(variables, {
+              ...ownContext,
+              ...context,
+            } as TContext & MutationFunctionContext)
+          }
+        : undefined,
+      onSettled: onSettled
+        ? (
+            data: TData | undefined,
+            error: Error | null,
+            variables: TVariables,
+            onMutateResult: TOnMutateResult | undefined,
+            context: MutationFunctionContext,
+          ) => {
+            return onSettled(data, error, variables, {
+              ...ownContext,
+              ...context,
+              onMutateResult,
+            } as TContext &
+              MutationFunctionContext & {
+                onMutateResult: TOnMutateResult | undefined
+              })
+          }
+        : undefined,
+    })
   }
   result.useIsMutating = (
     keyParams: UseKey extends true

package/src/mutation/types.mts

@@ -4,7 +4,11 @@ import type {
   UrlHasParams,
   UrlParams,
 } from '@navios/builder'
-import type { DataTag, QueryClient, UseMutationOptions } from '@tanstack/react-query'
+import type {
+  DataTag,
+  MutationFunctionContext,
+  UseMutationOptions,
+} from '@tanstack/react-query'
 import type { z, ZodObject } from 'zod/v4'
 
 import type { ProcessResponseFunction } from '../common/types.mjs'
@@ -42,29 +46,47 @@ export interface MutationParams<
   TData = unknown,
   TVariables = NaviosZodRequest<Config>,
   TResponse = z.output<Config['responseSchema']>,
+  TOnMutateResult = unknown,
   TContext = unknown,
   UseKey extends boolean = false,
 > extends Omit<
     UseMutationOptions<TData, Error, TVariables>,
-    'mutationKey' | 'mutationFn' | 'onSuccess' | 'onError' | 'scope'
+    | 'mutationKey'
+    | 'mutationFn'
+    | 'onMutate'
+    | 'onSuccess'
+    | 'onError'
+    | 'onSettled'
+    | 'scope'
   > {
-  processResponse: ProcessResponseFunction<TData, TResponse>
+  processResponse?: ProcessResponseFunction<TData, TResponse>
   /**
    * React hooks that will prepare the context for the mutation onSuccess and onError
    * callbacks. This is useful for when you want to use the context in the callbacks
    */
   useContext?: () => TContext
   onSuccess?: (
-    queryClient: QueryClient,
     data: TData,
     variables: TVariables,
-    context: TContext,
+    context: TContext &
+      MutationFunctionContext & { onMutateResult: TOnMutateResult | undefined },
   ) => void | Promise<void>
   onError?: (
-    queryClient: QueryClient,
     err: unknown,
     variables: TVariables,
-    context: TContext,
+    context: TContext &
+      MutationFunctionContext & { onMutateResult: TOnMutateResult | undefined },
+  ) => void | Promise<void>
+  onMutate?: (
+    variables: TVariables,
+    context: TContext & MutationFunctionContext,
+  ) => TOnMutateResult | Promise<TOnMutateResult>
+  onSettled?: (
+    data: TData | undefined,
+    error: Error | null,
+    variables: TVariables,
+    context: TContext &
+      MutationFunctionContext & { onMutateResult: TOnMutateResult | undefined },
   ) => void | Promise<void>
 
   /**