@navios/react-query 0.7.1 → 1.0.0

package/src/common/types.mts

@@ -1,4 +1,9 @@
-import type { BuilderInstance } from '@navios/builder'
+import type {
+  BuilderInstance,
+  ErrorSchemaRecord,
+  InferErrorSchemaOutput,
+} from '@navios/builder'
+import type { z, ZodType } from 'zod/v4'
 
 /**
  * Splits a string by a delimiter into a tuple type.
@@ -19,13 +24,72 @@ export type ProcessResponseFunction<TData = unknown, TVariables = unknown> = (
   variables: TVariables,
 ) => Promise<TData> | TData
 
+/**
+ * Compute the response input type based on discriminator and error schema.
+ * When UseDiscriminator=true and errorSchema is present, errors are included as a union.
+ * When UseDiscriminator=false, only the success type is returned (errors are thrown).
+ *
+ * @template UseDiscriminator - Whether to include error types in the response union
+ * @template ResponseSchema - The success response schema
+ * @template ErrorSchema - The error schema record (optional)
+ */
+export type ComputeResponseInput<
+  UseDiscriminator extends boolean,
+  ResponseSchema extends ZodType,
+  ErrorSchema extends ErrorSchemaRecord | undefined,
+> = UseDiscriminator extends true
+  ? ErrorSchema extends ErrorSchemaRecord
+    ? z.output<ResponseSchema> | InferErrorSchemaOutput<ErrorSchema>
+    : z.output<ResponseSchema>
+  : z.output<ResponseSchema>
+
 /**
  * Options for creating a client instance.
+ *
+ * @template UseDiscriminator - When `true`, errors are returned as union types.
+ *   When `false` (default), errors are thrown.
  */
-export type ClientOptions = {
-  api: BuilderInstance
+export type ClientOptions<UseDiscriminator extends boolean = false> = {
+  api: BuilderInstance<UseDiscriminator>
   defaults?: {
     keyPrefix?: string[]
     keySuffix?: string[]
   }
 }
+
+/**
+ * Infers the full response type from an endpoint configuration.
+ * Returns `ResponseType | ErrorTypes` if errorSchema exists,
+ * otherwise just `ResponseType`.
+ *
+ * @example
+ * ```ts
+ * type Response = InferEndpointResponse<{
+ *   responseSchema: z.ZodObject<{ data: z.ZodString }>,
+ *   errorSchema: { 400: z.ZodObject<{ error: z.ZodString }> }
+ * }>
+ * // Result: { data: string } | { error: string }
+ * ```
+ */
+export type InferEndpointResponse<
+  Config extends {
+    responseSchema: ZodType
+    errorSchema?: ErrorSchemaRecord
+  },
+> = Config['errorSchema'] extends ErrorSchemaRecord
+  ? z.output<Config['responseSchema']> | InferErrorSchemaOutput<Config['errorSchema']>
+  : z.output<Config['responseSchema']>
+
+/**
+ * Computes the Result type, applying processResponse transformation
+ * to the full response (including error union when present).
+ */
+export type ComputeResultType<
+  ResponseSchema extends ZodType,
+  ErrorSchema extends ErrorSchemaRecord | undefined,
+  ProcessedResult,
+> = ProcessedResult extends undefined
+  ? ErrorSchema extends ErrorSchemaRecord
+    ? z.output<ResponseSchema> | InferErrorSchemaOutput<ErrorSchema>
+    : z.output<ResponseSchema>
+  : ProcessedResult

package/src/mutation/index.mts

@@ -1,3 +1,4 @@
 export * from './types.mjs'
 export * from './key-creator.mjs'
 export * from './make-hook.mjs'
+export * from './optimistic.mjs'

package/src/mutation/make-hook.mts

@@ -1,22 +1,105 @@
 import type {
-  AbstractEndpoint,
   AnyEndpointConfig,
-  NaviosZodRequest,
+  BaseEndpointConfig,
+  ErrorSchemaRecord,
+  HttpMethod,
+  InferErrorSchemaOutput,
   UrlHasParams,
   UrlParams,
 } from '@navios/builder'
 import type {
   MutationFunctionContext,
+  UseMutationOptions,
   UseMutationResult,
 } from '@tanstack/react-query'
-import type { z } from 'zod/v4'
+import type { z, ZodObject, ZodType } from 'zod/v4'
 
 import { useIsMutating, useMutation } from '@tanstack/react-query'
 
-import type { MutationParams } from './types.mjs'
+import type { ProcessResponseFunction } from '../common/types.mjs'
+import type { MutationHelpers } from './types.mjs'
 
 import { createMutationKey } from './key-creator.mjs'
 
+/**
+ * Helper type for endpoint with config property
+ */
+type EndpointWithConfig<Config extends AnyEndpointConfig> = ((
+  params: any,
+) => Promise<any>) & {
+  config: Config
+}
+
+/**
+ * Helper type for response input when errorSchema is present
+ */
+type ResponseInput<
+  ResponseSchema extends ZodType,
+  ErrorSchema extends ErrorSchemaRecord | undefined,
+> = ErrorSchema extends ErrorSchemaRecord
+  ? z.output<ResponseSchema> | InferErrorSchemaOutput<ErrorSchema>
+  : z.output<ResponseSchema>
+
+/**
+ * Options type for makeMutation
+ */
+type MakeMutationParams<
+  Config extends AnyEndpointConfig,
+  ResponseSchema extends ZodType,
+  ErrorSchema extends ErrorSchemaRecord | undefined,
+  TData,
+  TVariables,
+  TOnMutateResult,
+  TContext,
+  UseKey extends boolean,
+> = Omit<
+  UseMutationOptions<TData, Error, TVariables>,
+  | 'mutationKey'
+  | 'mutationFn'
+  | 'onMutate'
+  | 'onSuccess'
+  | 'onError'
+  | 'onSettled'
+  | 'scope'
+> & {
+  processResponse?: ProcessResponseFunction<TData, ResponseInput<ResponseSchema, ErrorSchema>>
+  useContext?: () => TContext
+  onSuccess?: (
+    data: TData,
+    variables: TVariables,
+    context: TContext &
+      MutationFunctionContext & { onMutateResult: TOnMutateResult | undefined },
+  ) => void | Promise<void>
+  onError?: (
+    err: unknown,
+    variables: TVariables,
+    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>
+  useKey?: UseKey
+  keyPrefix?: UseKey extends true
+    ? UrlHasParams<Config['url']> extends true
+      ? string[]
+      : never
+    : never
+  keySuffix?: UseKey extends true
+    ? UrlHasParams<Config['url']> extends true
+      ? string[]
+      : never
+    : never
+}
+
 /**
  * Creates a mutation hook for a given endpoint.
  *
@@ -27,44 +110,87 @@ import { createMutationKey } from './key-creator.mjs'
  * @param options - Mutation configuration including processResponse and callbacks
  * @returns A hook function that returns mutation result with attached helpers
  */
+// Overload: WITH errorSchema
 export function makeMutation<
-  Config extends AnyEndpointConfig,
-  TData = unknown,
-  TVariables extends NaviosZodRequest<Config> = NaviosZodRequest<Config>,
-  TResponse = z.output<Config['responseSchema']>,
+  Method extends HttpMethod,
+  Url extends string,
+  QuerySchema extends ZodObject | undefined,
+  ResponseSchema extends ZodType,
+  RequestSchema extends ZodType,
+  ErrorSchema extends ErrorSchemaRecord,
+  TData,
+  TOnMutateResult = unknown,
+  TContext = unknown,
+  UseKey extends boolean = false,
+>(
+  endpoint: EndpointWithConfig<
+    BaseEndpointConfig<Method, Url, QuerySchema, ResponseSchema, RequestSchema, ErrorSchema>
+  >,
+  options: MakeMutationParams<
+    BaseEndpointConfig<Method, Url, QuerySchema, ResponseSchema, RequestSchema, ErrorSchema>,
+    ResponseSchema,
+    ErrorSchema,
+    TData,
+    any,
+    TOnMutateResult,
+    TContext,
+    UseKey
+  >,
+): ((
+  keyParams: UseKey extends true
+    ? UrlHasParams<Url> extends true
+      ? { urlParams: UrlParams<Url> }
+      : never
+    : never,
+) => UseMutationResult<TData, Error, any, TOnMutateResult>) &
+  MutationHelpers<Url, TData>
+
+// Overload: WITHOUT errorSchema
+export function makeMutation<
+  Method extends HttpMethod,
+  Url extends string,
+  QuerySchema extends ZodObject | undefined,
+  ResponseSchema extends ZodType,
+  RequestSchema extends ZodType | undefined,
+  TData,
   TOnMutateResult = unknown,
   TContext = unknown,
   UseKey extends boolean = false,
 >(
-  endpoint: AbstractEndpoint<Config>,
-  options: MutationParams<
-    Config,
+  endpoint: EndpointWithConfig<
+    BaseEndpointConfig<Method, Url, QuerySchema, ResponseSchema, RequestSchema, undefined>
+  >,
+  options: MakeMutationParams<
+    BaseEndpointConfig<Method, Url, QuerySchema, ResponseSchema, RequestSchema, undefined>,
+    ResponseSchema,
+    undefined,
     TData,
-    TVariables,
-    TResponse,
+    any,
     TOnMutateResult,
     TContext,
     UseKey
   >,
-) {
+): ((
+  keyParams: UseKey extends true
+    ? UrlHasParams<Url> extends true
+      ? { urlParams: UrlParams<Url> }
+      : never
+    : never,
+) => UseMutationResult<TData, Error, any, TOnMutateResult>) &
+  MutationHelpers<Url, TData>
+
+// Implementation
+export function makeMutation(
+  endpoint: EndpointWithConfig<AnyEndpointConfig>,
+  options: any,
+): any {
   const config = endpoint.config
 
   const mutationKey = createMutationKey(config, {
     ...options,
-    processResponse: options.processResponse ?? ((data) => data),
+    processResponse: options.processResponse ?? ((data: any) => data),
   })
-  const result = (
-    keyParams: UseKey extends true
-      ? UrlHasParams<Config['url']> extends true
-        ? { urlParams: UrlParams<Config['url']> }
-        : never
-      : never,
-  ): UseMutationResult<
-    TData,
-    Error,
-    NaviosZodRequest<Config>,
-    TOnMutateResult
-  > => {
+  const result = (keyParams: any): any => {
     const {
       useKey,
       useContext,
@@ -78,9 +204,8 @@ export function makeMutation<
       ...rest
     } = options
 
-    const ownContext = (useContext?.() as TContext) ?? {}
+    const ownContext = useContext?.() ?? {}
 
-    // @ts-expect-error The types match
     return useMutation({
       ...rest,
       mutationKey: useKey ? mutationKey(keyParams) : undefined,
@@ -89,89 +214,72 @@ export function makeMutation<
             id: JSON.stringify(mutationKey(keyParams)),
           }
         : undefined,
-      async mutationFn(params: TVariables) {
+      async mutationFn(params: any) {
         const response = await endpoint(params)
 
-        return (processResponse ? processResponse(response) : response) as TData
+        return processResponse ? processResponse(response) : response
       },
       onSuccess: onSuccess
         ? (
-            data: TData,
-            variables: TVariables,
-            onMutateResult: TOnMutateResult | undefined,
+            data: any,
+            variables: any,
+            onMutateResult: any,
             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,
+            variables: any,
+            onMutateResult: any,
             context: MutationFunctionContext,
           ) => {
             return onError?.(err, variables, {
               onMutateResult,
               ...ownContext,
               ...context,
-            } as TContext &
-              MutationFunctionContext & {
-                onMutateResult: TOnMutateResult | undefined
-              })
+            })
           }
         : undefined,
       onMutate: onMutate
-        ? (variables: TVariables, context: MutationFunctionContext) => {
+        ? (variables: any, context: MutationFunctionContext) => {
             return onMutate(variables, {
               ...ownContext,
               ...context,
-            } as TContext & MutationFunctionContext)
+            })
           }
         : undefined,
       onSettled: onSettled
         ? (
-            data: TData | undefined,
+            data: any,
             error: Error | null,
-            variables: TVariables,
-            onMutateResult: TOnMutateResult | undefined,
+            variables: any,
+            onMutateResult: any,
             context: MutationFunctionContext,
           ) => {
             return onSettled(data, error, variables, {
               ...ownContext,
               ...context,
               onMutateResult,
-            } as TContext &
-              MutationFunctionContext & {
-                onMutateResult: TOnMutateResult | undefined
-              })
+            })
           }
         : undefined,
     })
   }
-  result.useIsMutating = (
-    keyParams: UseKey extends true
-      ? UrlHasParams<Config['url']> extends true
-        ? UrlParams<Config['url']>
-        : never
-      : never,
-  ): boolean => {
+  result.useIsMutating = (keyParams: any): boolean => {
     if (!options.useKey) {
       throw new Error(
         'useIsMutating can only be used when useKey is set to true',
       )
     }
     const isMutating = useIsMutating({
-      mutationKey: mutationKey({
-        urlParams: keyParams,
-      }),
+      mutationKey: mutationKey(keyParams),
     })
     return isMutating > 0
   }