@navios/react-query 0.7.1 → 1.0.0

package/src/mutation/optimistic.mts

@@ -0,0 +1,300 @@
+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
+ *
+ * @experimental This API is experimental and may change in future versions.
+ * Use with caution in production code.
+ *
+ * @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.
+ *
+ * @experimental This API is experimental and may change in future versions.
+ * Use with caution in production code.
+ *
+ * @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 })
+        }
+      }
+    },
+  }
+}

package/src/mutation/types.mts

@@ -1,6 +1,8 @@
 import type {
   AnyEndpointConfig,
-  NaviosZodRequest,
+  ErrorSchemaRecord,
+  InferErrorSchemaOutput,
+  RequestArgs,
   UrlHasParams,
   UrlParams,
 } from '@navios/builder'
@@ -9,57 +11,103 @@ import type {
   MutationFunctionContext,
   UseMutationOptions,
 } from '@tanstack/react-query'
-import type { z, ZodObject } from 'zod/v4'
+import type { z, ZodObject, ZodType } from 'zod/v4'
 
-import type { ProcessResponseFunction } from '../common/types.mjs'
+import type {
+  ComputeResponseInput,
+  ProcessResponseFunction,
+} from '../common/types.mjs'
 
 /**
  * Arguments for mutation functions based on URL params, request schema, and query schema.
+ * Uses RequestArgs from builder for consistency.
  */
 export type MutationArgs<
   Url extends string = string,
-  RequestSchema = unknown,
-  QuerySchema = unknown,
-> = (UrlHasParams<Url> extends true ? { urlParams: UrlParams<Url> } : {}) &
-  (RequestSchema extends ZodObject ? { data: z.input<RequestSchema> } : {}) &
-  (QuerySchema extends ZodObject ? { params: z.input<QuerySchema> } : {})
+  RequestSchema extends ZodType | undefined = undefined,
+  QuerySchema extends ZodObject | undefined = undefined,
+> = RequestArgs<Url, QuerySchema, RequestSchema>
 
 /**
  * Helper methods attached to mutation hooks.
+ *
+ * @template Url - The URL template string
+ * @template Result - The mutation result type
  */
 export type MutationHelpers<Url extends string, Result = unknown> =
   UrlHasParams<Url> extends true
     ? {
-        mutationKey: (params: UrlParams<Url>) => DataTag<[Url], Result, Error>
-        useIsMutating: (keyParams: UrlParams<Url>) => boolean
+        /**
+         * Generates a mutation key for the given URL parameters.
+         * Useful for tracking mutations or invalidating related queries.
+         */
+        mutationKey: (params: {
+          urlParams: UrlParams<Url>
+        }) => DataTag<[Url], Result, Error>
+        /**
+         * Returns true if a mutation with the given URL parameters is currently in progress.
+         * Requires `useKey: true` to be set when creating the mutation.
+         */
+        useIsMutating: (keyParams: { urlParams: UrlParams<Url> }) => boolean
       }
     : {
+        /**
+         * Generates a mutation key.
+         * Useful for tracking mutations or invalidating related queries.
+         */
         mutationKey: () => DataTag<[Url], Result, Error>
+        /**
+         * Returns true if a mutation is currently in progress.
+         * Requires `useKey: true` to be set when creating the mutation.
+         */
         useIsMutating: () => boolean
       }
 
 /**
  * Base parameters for mutation configuration.
+ *
+ * @template UseDiscriminator - When `true`, errors are returned as union types in processResponse.
+ *   When `false` (default), errors are thrown and not included in TResponse.
  */
 export interface MutationParams<
   Config extends AnyEndpointConfig,
   TData = unknown,
-  TVariables = NaviosZodRequest<Config>,
-  TResponse = z.output<Config['responseSchema']>,
+  TVariables = RequestArgs<
+    Config['url'],
+    Config['querySchema'],
+    Config['requestSchema'],
+    Config['urlParamsSchema']
+  >,
+  _TResponse = ComputeResponseInput<false, Config['responseSchema'], Config['errorSchema']>,
   TOnMutateResult = unknown,
   TContext = unknown,
   UseKey extends boolean = false,
+  UseDiscriminator extends boolean = false,
+  TError = UseDiscriminator extends true
+    ? Error
+    : Config['errorSchema'] extends ErrorSchemaRecord
+      ? InferErrorSchemaOutput<Config['errorSchema']> | Error
+      : Error,
 > extends Omit<
-    UseMutationOptions<TData, Error, TVariables>,
-    | 'mutationKey'
-    | 'mutationFn'
-    | 'onMutate'
-    | 'onSuccess'
-    | 'onError'
-    | 'onSettled'
-    | 'scope'
-  > {
-  processResponse?: ProcessResponseFunction<TData, TResponse>
+  UseMutationOptions<
+    TData,
+    // When UseDiscriminator is false and errorSchema exists, errors are thrown, so Error is correct.
+    // When UseDiscriminator is true, errors are part of the response union, but network/other errors still throw Error.
+    TError,
+    TVariables
+  >,
+  | 'mutationKey'
+  | 'mutationFn'
+  | 'onMutate'
+  | 'onSuccess'
+  | 'onError'
+  | 'onSettled'
+  | 'scope'
+> {
+  processResponse?: ProcessResponseFunction<
+    TData,
+    ComputeResponseInput<UseDiscriminator, Config['responseSchema'], Config['errorSchema']>
+  >
   /**
    * 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
@@ -72,7 +120,7 @@ export interface MutationParams<
       MutationFunctionContext & { onMutateResult: TOnMutateResult | undefined },
   ) => void | Promise<void>
   onError?: (
-    err: unknown,
+    err: TError,
     variables: TVariables,
     context: TContext &
       MutationFunctionContext & { onMutateResult: TOnMutateResult | undefined },
@@ -83,7 +131,7 @@ export interface MutationParams<
   ) => TOnMutateResult | Promise<TOnMutateResult>
   onSettled?: (
     data: TData | undefined,
-    error: Error | null,
+    error: TError | null,
     variables: TVariables,
     context: TContext &
       MutationFunctionContext & { onMutateResult: TOnMutateResult | undefined },
@@ -109,20 +157,29 @@ export interface MutationParams<
 /** @deprecated Use MutationArgs instead */
 export type ClientMutationArgs<
   Url extends string = string,
-  RequestSchema = unknown,
-  QuerySchema = unknown,
+  RequestSchema extends ZodType | undefined = undefined,
+  QuerySchema extends ZodObject | undefined = undefined,
 > = MutationArgs<Url, RequestSchema, QuerySchema>
 
 /** @deprecated Use MutationParams instead */
 export type BaseMutationParams<
   Config extends AnyEndpointConfig,
   TData = unknown,
-  TVariables = NaviosZodRequest<Config>,
+  TVariables = RequestArgs<
+    Config['url'],
+    Config['querySchema'],
+    Config['requestSchema'],
+    Config['urlParamsSchema']
+  >,
   TResponse = z.output<Config['responseSchema']>,
   TContext = unknown,
   UseKey extends boolean = false,
 > = MutationParams<Config, TData, TVariables, TResponse, TContext, UseKey>
 
-/** @deprecated Use NaviosZodRequest from @navios/builder instead */
-export type BaseMutationArgs<Config extends AnyEndpointConfig> =
-  NaviosZodRequest<Config>
+/** @deprecated Use RequestArgs from @navios/builder instead */
+export type BaseMutationArgs<Config extends AnyEndpointConfig> = RequestArgs<
+  Config['url'],
+  Config['querySchema'],
+  Config['requestSchema'],
+  Config['urlParamsSchema']
+>

package/src/query/index.mts

@@ -2,3 +2,4 @@ export * from './types.mjs'
 export * from './key-creator.mjs'
 export * from './make-options.mjs'
 export * from './make-infinite-options.mjs'
+export * from './prefetch.mjs'

package/src/query/key-creator.mts

@@ -46,14 +46,18 @@ export function createQueryKey<
         params && 'querySchema' in config && 'params' in params
           ? config.querySchema?.parse(params.params)
           : []
+
+      // Use bindUrlParams to get the bound URL, then split it to get the parts
+      const boundUrl = bindUrlParams<Url>(
+        url,
+        params && 'urlParams' in params ? params : {},
+        config.urlParamsSchema,
+      )
+      const boundUrlParts = boundUrl.split('/').filter(Boolean)
+
       return [
         ...(options.keyPrefix ?? []),
-        ...urlParts.map((part) =>
-          part.startsWith('$')
-            ? // @ts-expect-error TS2339 We know that the urlParams are defined only if the url has params
-              params.urlParams[part.slice(1)].toString()
-            : part,
-        ),
+        ...boundUrlParts,
         ...(options.keySuffix ?? []),
         queryParams ?? [],
       ] as unknown as DataTag<
@@ -68,14 +72,17 @@ export function createQueryKey<
     },
     // @ts-expect-error We have correct types in return type
     filterKey: (params) => {
+      // Use bindUrlParams to get the bound URL, then split it to get the parts
+      const boundUrl = bindUrlParams<Url>(
+        url,
+        params && 'urlParams' in params ? params : {},
+        config.urlParamsSchema,
+      )
+      const boundUrlParts = boundUrl.split('/').filter(Boolean)
+
       return [
         ...(options.keyPrefix ?? []),
-        ...urlParts.map((part) =>
-          part.startsWith('$')
-            ? // @ts-expect-error TS2339 We know that the urlParams are defined only if the url has params
-              params.urlParams[part.slice(1)].toString()
-            : part,
-        ),
+        ...boundUrlParts,
         ...(options.keySuffix ?? []),
       ] as unknown as DataTag<
         Split<Url, '/'>,
@@ -89,7 +96,11 @@ export function createQueryKey<
     },
 
     bindToUrl: (params) => {
-      return bindUrlParams<Url>(url, params ?? ({} as never))
+      return bindUrlParams<Url>(
+        url,
+        params && 'urlParams' in params ? params : {},
+        config.urlParamsSchema,
+      )
     },
   }
 }

package/src/query/make-infinite-options.mts

@@ -66,8 +66,12 @@ export function makeInfiniteQueryOptions<
     : never => {
     // @ts-expect-error TS2322 We know that the processResponse is defined
     return infiniteQueryOptions({
+      // @ts-expect-error TS2345 We bind the url params only if the url has params
       queryKey: queryKey.dataTag(params),
-      queryFn: async ({ signal, pageParam }): Promise<ReturnType<Options['processResponse']>> => {
+      queryFn: async ({
+        signal,
+        pageParam,
+      }): Promise<ReturnType<Options['processResponse']>> => {
         let result
         try {
           result = await endpoint({
@@ -92,37 +96,76 @@ export function makeInfiniteQueryOptions<
       getPreviousPageParam: options.getPreviousPageParam,
       initialPageParam:
         options.initialPageParam ??
-        config.querySchema.parse('params' in params ? params.params : {}),
+        config.querySchema?.parse('params' in params ? params.params : {}) ??
+        ('params' in params ? params.params : {}),
       ...baseQuery,
     })
   }
+  /** The query key creator for this infinite query endpoint */
   res.queryKey = queryKey
 
+  /**
+   * React hook that executes the infinite query.
+   * Uses `useInfiniteQuery` from TanStack Query internally.
+   *
+   * @param params - URL parameters and initial query parameters
+   * @returns Infinite query result with pages, fetchNextPage, etc.
+   */
   res.use = (params: QueryArgs<Config['url'], Config['querySchema']>) => {
     return useInfiniteQuery(res(params))
   }
 
-  res.useSuspense = (params: QueryArgs<Config['url'], Config['querySchema']>) => {
+  /**
+   * React hook that executes the infinite query with Suspense support.
+   * Uses `useSuspenseInfiniteQuery` from TanStack Query internally.
+   * The component will suspend while loading and throw on error.
+   *
+   * @param params - URL parameters and initial query parameters
+   * @returns Infinite query result with pages guaranteed to be defined
+   */
+  res.useSuspense = (
+    params: QueryArgs<Config['url'], Config['querySchema']>,
+  ) => {
     return useSuspenseInfiniteQuery(res(params))
   }
 
+  /**
+   * Creates a function that invalidates this specific infinite query in the cache.
+   * Call the returned function to trigger the invalidation.
+   *
+   * @param queryClient - The TanStack Query client instance
+   * @param params - The exact parameters used for this query
+   * @returns A function that when called invalidates the query
+   */
   res.invalidate = (
     queryClient: QueryClient,
     params: QueryArgs<Config['url'], Config['querySchema']>,
   ) => {
-    return queryClient.invalidateQueries({
-      queryKey: res.queryKey.dataTag(params),
-    })
+    return () =>
+      queryClient.invalidateQueries({
+        // @ts-expect-error TS2345 We bind the url params only if the url has params
+        queryKey: res.queryKey.dataTag(params),
+      })
   }
 
+  /**
+   * Creates a function that invalidates all infinite queries matching the URL pattern.
+   * Useful for invalidating all queries for a resource regardless of query params.
+   *
+   * @param queryClient - The TanStack Query client instance
+   * @param params - URL parameters only (query params are ignored for matching)
+   * @returns A function that when called invalidates all matching queries
+   */
   res.invalidateAll = (
     queryClient: QueryClient,
     params: QueryArgs<Config['url'], Config['querySchema']>,
   ) => {
-    return queryClient.invalidateQueries({
-      queryKey: res.queryKey.filterKey(params),
-      exact: false,
-    })
+    return () =>
+      queryClient.invalidateQueries({
+        // @ts-expect-error TS2345 We bind the url params only if the url has params
+        queryKey: res.queryKey.filterKey(params),
+        exact: false,
+      })
   }
 
   return res