@navios/react-query 0.7.0 → 1.0.0-alpha.1

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.
@@ -21,11 +26,51 @@ export type ProcessResponseFunction<TData = unknown, TVariables = unknown> = (
 
 /**
  * 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
   }

package/src/mutation/optimistic.mts

@@ -0,0 +1,294 @@
+import type { QueryClient } from '@tanstack/react-query'
+
+/**
+ * Configuration for creating optimistic update callbacks.
+ *
+ * @template TData - The mutation response data type
+ * @template TVariables - The mutation variables type
+ * @template TQueryData - The query cache data type
+ */
+export interface OptimisticUpdateConfig<
+  TData,
+  TVariables,
+  TQueryData,
+> {
+  /**
+   * The query key to optimistically update.
+   * This should match the query key used for the affected query.
+   */
+  queryKey: readonly unknown[]
+
+  /**
+   * Function to compute the optimistic cache value.
+   * Receives the current cache data and mutation variables.
+   *
+   * @param oldData - Current data in the cache (may be undefined if not cached)
+   * @param variables - The mutation variables being submitted
+   * @returns The new optimistic cache value
+   */
+  updateFn: (oldData: TQueryData | undefined, variables: TVariables) => TQueryData
+
+  /**
+   * Whether to rollback on error.
+   * Defaults to true.
+   */
+  rollbackOnError?: boolean
+
+  /**
+   * Whether to invalidate the query on settlement.
+   * Defaults to true.
+   */
+  invalidateOnSettled?: boolean
+}
+
+/**
+ * Return type for optimistic update callbacks.
+ */
+export interface OptimisticUpdateCallbacks<TData, TVariables, TQueryData> {
+  /**
+   * Called before the mutation starts. Cancels outgoing refetches,
+   * snapshots the current cache value, and applies the optimistic update.
+   */
+  onMutate: (
+    variables: TVariables,
+    context: { queryClient: QueryClient },
+  ) => Promise<{ previousData: TQueryData | undefined }>
+
+  /**
+   * Called when the mutation fails. Rolls back the cache to the previous
+   * value if rollbackOnError is enabled.
+   */
+  onError: (
+    err: Error,
+    variables: TVariables,
+    context: { previousData?: TQueryData; queryClient: QueryClient },
+  ) => void
+
+  /**
+   * Called when the mutation completes (success or error).
+   * Invalidates the query if invalidateOnSettled is enabled.
+   */
+  onSettled: (
+    data: TData | undefined,
+    error: Error | null,
+    variables: TVariables,
+    context: { queryClient: QueryClient },
+  ) => void
+}
+
+/**
+ * Creates type-safe optimistic update callbacks for mutations.
+ *
+ * This helper generates the onMutate, onError, and onSettled callbacks
+ * that implement the standard optimistic update pattern:
+ *
+ * 1. onMutate: Cancel refetches, snapshot cache, apply optimistic update
+ * 2. onError: Rollback cache to previous value on failure
+ * 3. onSettled: Invalidate query to refetch fresh data
+ *
+ * @param config - Configuration for the optimistic update
+ * @returns Object containing onMutate, onError, and onSettled callbacks
+ *
+ * @example
+ * ```ts
+ * // Create a mutation with optimistic updates
+ * const updateUser = client.mutation({
+ *   method: 'PATCH',
+ *   url: '/users/$userId',
+ *   requestSchema: updateUserSchema,
+ *   responseSchema: userSchema,
+ *   processResponse: (data) => data,
+ *   ...createOptimisticUpdate({
+ *     queryKey: ['users', userId],
+ *     updateFn: (oldData, variables) => ({
+ *       ...oldData,
+ *       ...variables.data,
+ *     }),
+ *   }),
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Optimistic update for adding an item to a list
+ * const addTodo = client.mutation({
+ *   method: 'POST',
+ *   url: '/todos',
+ *   requestSchema: createTodoSchema,
+ *   responseSchema: todoSchema,
+ *   processResponse: (data) => data,
+ *   ...createOptimisticUpdate({
+ *     queryKey: ['todos'],
+ *     updateFn: (oldData, variables) => [
+ *       ...(oldData ?? []),
+ *       { id: 'temp-id', ...variables.data, createdAt: new Date() },
+ *     ],
+ *   }),
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Optimistic delete
+ * const deleteTodo = client.mutation({
+ *   method: 'DELETE',
+ *   url: '/todos/$todoId',
+ *   responseSchema: z.object({ success: z.boolean() }),
+ *   processResponse: (data) => data,
+ *   ...createOptimisticUpdate({
+ *     queryKey: ['todos'],
+ *     updateFn: (oldData, variables) =>
+ *       (oldData ?? []).filter((t) => t.id !== variables.urlParams.todoId),
+ *   }),
+ * })
+ * ```
+ */
+export function createOptimisticUpdate<
+  TData,
+  TVariables,
+  TQueryData,
+>(config: OptimisticUpdateConfig<TData, TVariables, TQueryData>): OptimisticUpdateCallbacks<TData, TVariables, TQueryData> {
+  const {
+    queryKey,
+    updateFn,
+    rollbackOnError = true,
+    invalidateOnSettled = true,
+  } = config
+
+  return {
+    onMutate: async (
+      variables: TVariables,
+      context: { queryClient: QueryClient },
+    ) => {
+      // Cancel any outgoing refetches to prevent overwriting optimistic update
+      await context.queryClient.cancelQueries({ queryKey })
+
+      // Snapshot the previous value
+      const previousData = context.queryClient.getQueryData<TQueryData>(queryKey)
+
+      // Optimistically update the cache
+      context.queryClient.setQueryData<TQueryData>(
+        queryKey,
+        (old) => updateFn(old, variables),
+      )
+
+      // Return context with the previous data for potential rollback
+      return { previousData }
+    },
+
+    onError: (
+      _err: Error,
+      _variables: TVariables,
+      context: { previousData?: TQueryData; queryClient: QueryClient },
+    ) => {
+      // Rollback to the previous value on error
+      if (rollbackOnError && context?.previousData !== undefined) {
+        context.queryClient.setQueryData(queryKey, context.previousData)
+      }
+    },
+
+    onSettled: (
+      _data: TData | undefined,
+      _error: Error | null,
+      _variables: TVariables,
+      context: { queryClient: QueryClient },
+    ) => {
+      // Always invalidate to ensure we have the correct server state
+      if (invalidateOnSettled) {
+        void context.queryClient.invalidateQueries({ queryKey })
+      }
+    },
+  }
+}
+
+/**
+ * Creates optimistic update callbacks that work with multiple query keys.
+ *
+ * Useful when a mutation affects multiple cached queries.
+ *
+ * @param configs - Array of optimistic update configurations
+ * @returns Combined callbacks that handle all specified queries
+ *
+ * @example
+ * ```ts
+ * // Updating a user affects both user detail and user list queries
+ * const updateUser = client.mutation({
+ *   method: 'PATCH',
+ *   url: '/users/$userId',
+ *   requestSchema: updateUserSchema,
+ *   responseSchema: userSchema,
+ *   processResponse: (data) => data,
+ *   ...createMultiOptimisticUpdate([
+ *     {
+ *       queryKey: ['users', userId],
+ *       updateFn: (oldData, variables) => ({ ...oldData, ...variables.data }),
+ *     },
+ *     {
+ *       queryKey: ['users'],
+ *       updateFn: (oldList, variables) =>
+ *         (oldList ?? []).map((u) =>
+ *           u.id === userId ? { ...u, ...variables.data } : u
+ *         ),
+ *     },
+ *   ]),
+ * })
+ * ```
+ */
+export function createMultiOptimisticUpdate<TData, TVariables>(
+  configs: Array<OptimisticUpdateConfig<TData, TVariables, unknown>>,
+): OptimisticUpdateCallbacks<TData, TVariables, Map<string, unknown>> {
+  return {
+    onMutate: async (
+      variables: TVariables,
+      context: { queryClient: QueryClient },
+    ) => {
+      // Cancel and snapshot all queries
+      const previousData = new Map<string, unknown>()
+
+      for (const config of configs) {
+        await context.queryClient.cancelQueries({ queryKey: config.queryKey })
+        const key = JSON.stringify(config.queryKey)
+        previousData.set(key, context.queryClient.getQueryData(config.queryKey))
+        context.queryClient.setQueryData(
+          config.queryKey,
+          (old: unknown) => config.updateFn(old, variables),
+        )
+      }
+
+      return { previousData }
+    },
+
+    onError: (
+      _err: Error,
+      _variables: TVariables,
+      context: { previousData?: Map<string, unknown>; queryClient: QueryClient },
+    ) => {
+      // Rollback all queries
+      if (context?.previousData) {
+        for (const config of configs) {
+          if (config.rollbackOnError !== false) {
+            const key = JSON.stringify(config.queryKey)
+            const previous = context.previousData.get(key)
+            if (previous !== undefined) {
+              context.queryClient.setQueryData(config.queryKey, previous)
+            }
+          }
+        }
+      }
+    },
+
+    onSettled: (
+      _data: TData | undefined,
+      _error: Error | null,
+      _variables: TVariables,
+      context: { queryClient: QueryClient },
+    ) => {
+      // Invalidate all queries
+      for (const config of configs) {
+        if (config.invalidateOnSettled !== false) {
+          void context.queryClient.invalidateQueries({ queryKey: config.queryKey })
+        }
+      }
+    },
+  }
+}