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

package/src/mutation/types.mts

@@ -1,6 +1,8 @@
 import type {
   AnyEndpointConfig,
-  NaviosZodRequest,
+  ErrorSchemaRecord,
+  InferErrorSchemaOutput,
+  RequestArgs,
   UrlHasParams,
   UrlParams,
 } from '@navios/builder'
@@ -9,57 +11,119 @@ 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'
 
+/**
+ * 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)
+ */
+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>
+
 /**
  * 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 +136,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 +147,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 +173,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

package/src/query/make-options.mts

@@ -1,34 +1,83 @@
-import type { AbstractEndpoint, AnyEndpointConfig } from '@navios/builder'
+import type {
+  EndpointHandler,
+  EndpointOptions,
+  InferEndpointReturn,
+  Simplify,
+} from '@navios/builder'
 import type {
   DataTag,
   QueryClient,
   UseQueryOptions,
   UseSuspenseQueryOptions,
 } from '@tanstack/react-query'
+import type { ZodObject, ZodType } from 'zod/v4'
 
 import { queryOptions, useQuery, useSuspenseQuery } from '@tanstack/react-query'
 
 import type { Split } from '../common/types.mjs'
-import type { QueryArgs, QueryParams } from './types.mjs'
+import type { QueryArgs, QueryHelpers, QueryResult } from './types.mjs'
 
 import { createQueryKey } from './key-creator.mjs'
 
+/**
+ * Options for makeQueryOptions.
+ */
+export interface MakeQueryOptionsParams<
+  Options extends EndpointOptions,
+  UseDiscriminator extends boolean = false,
+  Result = QueryResult<Options, UseDiscriminator>,
+> {
+  keyPrefix?: string[]
+  keySuffix?: string[]
+  onFail?: (err: unknown) => void
+  processResponse: (
+    data: InferEndpointReturn<Options, UseDiscriminator>,
+  ) => Result
+}
+
 /**
  * Creates query options for a given endpoint.
  *
  * Returns a function that generates TanStack Query options when called with params.
  * The returned function also has helper methods attached (use, useSuspense, invalidate, etc.)
  *
- * @param endpoint - The navios endpoint to create query options for
+ * Uses const generics pattern to automatically infer types from the endpoint configuration.
+ *
+ * @param endpoint - The navios endpoint handler (from builder's declareEndpoint)
  * @param options - Query configuration including processResponse
  * @param baseQuery - Optional base query options to merge
  * @returns A function that generates query options with attached helpers
+ *
+ * @example
+ * ```ts
+ * const getUser = api.declareEndpoint({
+ *   method: 'GET',
+ *   url: '/users/$userId',
+ *   responseSchema: userSchema,
+ * })
+ *
+ * const queryOptions = makeQueryOptions(getUser, {
+ *   processResponse: (data) => data,
+ * })
+ *
+ * const { data } = queryOptions.useSuspense({ urlParams: { userId: '123' } })
+ * ```
  */
 export function makeQueryOptions<
-  Config extends AnyEndpointConfig,
-  Options extends QueryParams<Config>,
+  const Options extends EndpointOptions,
+  UseDiscriminator extends boolean = false,
+  Result = QueryResult<Options, UseDiscriminator>,
   BaseQuery extends Omit<
-    UseQueryOptions<ReturnType<Options['processResponse']>, Error, any>,
+    UseQueryOptions<Result, Error, any>,
+    | 'queryKey'
+    | 'queryFn'
+    | 'getNextPageParam'
+    | 'initialPageParam'
+    | 'enabled'
+    | 'throwOnError'
+    | 'placeholderData'
+  > = Omit<
+    UseQueryOptions<Result, Error, any>,
     | 'queryKey'
     | 'queryFn'
     | 'getNextPageParam'
@@ -38,34 +87,58 @@ export function makeQueryOptions<
     | 'placeholderData'
   >,
 >(
-  endpoint: AbstractEndpoint<Config>,
-  options: Options,
-  baseQuery: BaseQuery = {} as BaseQuery,
-) {
+  endpoint: EndpointHandler<Options, UseDiscriminator>,
+  options: MakeQueryOptionsParams<Options, UseDiscriminator, Result>,
+  baseQuery?: BaseQuery,
+): ((
+  params: Simplify<
+    QueryArgs<
+      Options['url'],
+      Options extends { querySchema: infer Q extends ZodObject }
+        ? Q
+        : undefined,
+      Options extends { requestSchema: infer R extends ZodType } ? R : undefined
+    >
+  >,
+) => UseSuspenseQueryOptions<
+  Result,
+  Error,
+  BaseQuery extends { select: (...args: any[]) => infer T } ? T : Result,
+  DataTag<Split<Options['url'], '/'>, Result, Error>
+>) &
+  QueryHelpers<
+    Options['url'],
+    Options extends { querySchema: infer Q extends ZodObject } ? Q : undefined,
+    Result,
+    false,
+    Options extends { requestSchema: infer R extends ZodType } ? R : undefined
+  > {
   const config = endpoint.config
-  const queryKey = createQueryKey(config, options, false)
+  const queryKey = createQueryKey(config as any, options as any, false)
   const processResponse = options.processResponse
 
   const result = (
-    params: QueryArgs<Config['url'], Config['querySchema']>,
-  ): Options['processResponse'] extends (...args: any[]) => infer Result
-    ? UseSuspenseQueryOptions<
-        Result,
-        Error,
-        BaseQuery['select'] extends (...args: any[]) => infer T ? T : Result,
-        DataTag<Split<Config['url'], '/'>, Result, Error>
+    params: Simplify<
+      QueryArgs<
+        Options['url'],
+        Options extends { querySchema: infer Q extends ZodObject }
+          ? Q
+          : undefined,
+        Options extends { requestSchema: infer R extends ZodType }
+          ? R
+          : undefined
       >
-    : never => {
-    // @ts-expect-error TS2322 We know that the processResponse is defined
+    >,
+  ): any => {
     return queryOptions({
-      queryKey: queryKey.dataTag(params),
-      queryFn: async ({ signal }): Promise<ReturnType<Options['processResponse']>> => {
+      queryKey: queryKey.dataTag(params as any),
+      queryFn: async ({ signal }): Promise<Result> => {
         let result
         try {
           result = await endpoint({
             signal,
             ...params,
-          })
+          } as any)
         } catch (err) {
           if (options.onFail) {
             options.onFail(err)
@@ -73,38 +146,106 @@ export function makeQueryOptions<
           throw err
         }
 
-        return processResponse(result) as ReturnType<Options['processResponse']>
+        return processResponse(result)
       },
       ...baseQuery,
     })
   }
-  result.queryKey = queryKey
-  result.use = (params: QueryArgs<Config['url'], Config['querySchema']>) => {
+
+  /** The query key creator for this endpoint */
+  result.queryKey = queryKey as any
+
+  /**
+   * React hook that executes the query.
+   * Uses `useQuery` from TanStack Query internally.
+   *
+   * @param params - URL parameters, query parameters, and request body
+   * @returns Query result with data, isLoading, error, etc.
+   */
+  result.use = (params: any) => {
     return useQuery(result(params))
   }
 
-  result.useSuspense = (params: QueryArgs<Config['url'], Config['querySchema']>) => {
+  /**
+   * React hook that executes the query with Suspense support.
+   * Uses `useSuspenseQuery` from TanStack Query internally.
+   * The component will suspend while loading and throw on error.
+   *
+   * @param params - URL parameters, query parameters, and request body
+   * @returns Query result with data guaranteed to be defined
+   */
+  result.useSuspense = (params: any) => {
     return useSuspenseQuery(result(params))
   }
 
-  result.invalidate = (
-    queryClient: QueryClient,
-    params: QueryArgs<Config['url'], Config['querySchema']>,
-  ) => {
-    return queryClient.invalidateQueries({
-      queryKey: result.queryKey.dataTag(params),
-    })
+  /**
+   * Creates a function that invalidates a specific 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
+   *
+   * @example
+   * ```ts
+   * const invalidate = getUser.invalidate(queryClient, { urlParams: { userId: '123' } })
+   * await invalidate() // Invalidates this specific query
+   * ```
+   */
+  result.invalidate = (queryClient: QueryClient, params: any) => {
+    return () =>
+      queryClient.invalidateQueries({
+        queryKey: result.queryKey.dataTag(params),
+      })
   }
 
-  result.invalidateAll = (
-    queryClient: QueryClient,
-    params: QueryArgs<Config['url'], Config['querySchema']>,
-  ) => {
-    return queryClient.invalidateQueries({
-      queryKey: result.queryKey.filterKey(params),
-      exact: false,
-    })
+  /**
+   * Creates a function that invalidates all 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
+   *
+   * @example
+   * ```ts
+   * const invalidateAll = getUserPosts.invalidateAll(queryClient, { urlParams: { userId: '123' } })
+   * await invalidateAll() // Invalidates all getUserPosts queries for user 123
+   * ```
+   */
+  result.invalidateAll = (queryClient: QueryClient, params: any) => {
+    return () =>
+      queryClient.invalidateQueries({
+        queryKey: result.queryKey.filterKey(params),
+        exact: false,
+      })
   }
 
-  return result
+  return result as unknown as ((
+    params: Simplify<
+      QueryArgs<
+        Options['url'],
+        Options extends { querySchema: infer Q extends ZodObject }
+          ? Q
+          : undefined,
+        Options extends { requestSchema: infer R extends ZodType }
+          ? R
+          : undefined
+      >
+    >,
+  ) => UseSuspenseQueryOptions<
+    Result,
+    Error,
+    BaseQuery extends { select: (...args: any[]) => infer T } ? T : Result,
+    DataTag<Split<Options['url'], '/'>, Result, Error>
+  >) &
+    QueryHelpers<
+      Options['url'],
+      Options extends { querySchema: infer Q extends ZodObject }
+        ? Q
+        : undefined,
+      Result,
+      false,
+      Options extends { requestSchema: infer R extends ZodType } ? R : undefined
+    >
 }