API Reference

Complete API reference for @navios/react-query.

declareClient

Creates a client instance for type-safe queries and mutations.

function declareClient(options: ClientOptions): ClientInstance

Parameters

• options.api: BuilderInstance - The configured API builder
• options.defaults (optional): Default options
  • keyPrefix?: string[] - Prefix added to all query/mutation keys
  • keySuffix?: string[] - Suffix added to all query/mutation keys

Returns

A ClientInstance with methods to create queries and mutations.

Example

const client = declareClient({
  api,
  defaults: {
    keyPrefix: ['api', 'v1'],
    keySuffix: ['cache'],
  },
})

ClientInstance Methods

query

Creates a query with inline configuration.

client.query<Config>(config: QueryConfig): QueryHelpers

Config Options:

• method: HTTP method
• url: Endpoint URL
• responseSchema: Zod schema for response
• querySchema?: Zod schema for query parameters
• requestSchema?: Zod schema for request body
• processResponse: Transform response data

Returns: Query helpers with use(), useSuspense(), invalidate(), etc.

queryFromEndpoint

Creates a query from a pre-declared endpoint.

client.queryFromEndpoint<Endpoint>(endpoint: Endpoint, options?: QueryOptions): QueryHelpers

infiniteQuery

Creates an infinite query for paginated data.

client.infiniteQuery<Config>(config: InfiniteQueryConfig): InfiniteQueryHelpers

Additional Options:

• getNextPageParam: Extract next page parameter
• getPreviousPageParam?: Extract previous page parameter
• initialPageParam: Initial page parameter

infiniteQueryFromEndpoint

Creates an infinite query from a pre-declared endpoint.

client.infiniteQueryFromEndpoint<Endpoint>(endpoint: Endpoint, options: InfiniteQueryOptions): InfiniteQueryHelpers

mutation

Creates a mutation for data modification.

client.mutation<Config>(config: MutationConfig): MutationHelpers

Config Options:

• method: HTTP method
• url: Endpoint URL
• requestSchema?: Zod schema for request body
• responseSchema?: Zod schema for response
• querySchema?: Zod schema for query parameters
• processResponse?: Transform response data
• useContext?: Provide context to callbacks
• onMutate?: Called before mutation
• onSuccess?: Called on success
• onError?: Called on error
• onSettled?: Called on completion
• useKey?: Enable mutation key scoping

mutationFromEndpoint

Creates a mutation from a pre-declared endpoint.

client.mutationFromEndpoint<Endpoint>(endpoint: Endpoint, options?: MutationOptions): MutationHelpers

multipartMutation

Creates a mutation for file uploads.

client.multipartMutation<Config>(config: MultipartMutationConfig): MutationHelpers

Same options as mutation, but automatically handles FormData conversion.

Query Helpers

use

Returns a query result object.

query.use(params: QueryArgs): UseQueryResult

Returns:

• data: Query data
• isLoading: Initial load state
• isFetching: Any fetch state
• error: Error object
• refetch: Refetch function
• And all other TanStack Query properties

useSuspense

Returns data directly (throws on loading/error).

query.useSuspense(params: QueryArgs): UseSuspenseQueryResult

invalidate

Invalidate a specific query.

query.invalidate(queryClient: QueryClient, params: QueryArgs): () => Promise<void>

invalidateAll

Invalidate all matching queries.

query.invalidateAll(queryClient: QueryClient, params: QueryUrlParamsArgs): () => Promise<void>

queryKey

Query key utilities.

query.queryKey.dataTag(params: QueryArgs): QueryKey
query.queryKey.filterKey(params: QueryUrlParamsArgs): QueryKey
query.queryKey.bindToUrl(params: QueryUrlParamsArgs): string

Mutation Helpers

Hook Usage

mutation(): UseMutationResult
mutation(urlParams: UrlParams): UseMutationResult // When useKey is enabled

Returns:

• mutate: Fire and forget mutation
• mutateAsync: Promise-based mutation
• isPending: Mutation in progress
• isError: Mutation failed
• isSuccess: Mutation succeeded
• data: Response data
• error: Error object
• reset: Reset mutation state

useIsMutating

Check if mutation is in progress (when useKey is enabled).

mutation.useIsMutating(): number // Global count
mutation.useIsMutating(urlParams: UrlParams): boolean // Specific item

mutationKey

Get mutation key.

mutation.mutationKey(): MutationKey // When useKey is false
mutation.mutationKey(urlParams: UrlParams): MutationKey // When useKey is true

Prefetch Helpers

createPrefetchHelper

Creates a prefetch helper for SSR/RSC usage.

function createPrefetchHelper<TParams, TData, TError>(
  queryOptionsCreator: QueryOptionsCreator<TParams, TData, TError>
): PrefetchHelper<TParams, TData, TError>

Returns: PrefetchHelper with methods:

• prefetch(queryClient, params) - Prefetch data
• ensureData(queryClient, params) - Ensure data exists, returns data
• getQueryOptions(params) - Get raw query options
• prefetchMany(queryClient, paramsList) - Prefetch multiple in parallel

createPrefetchHelpers

Creates multiple prefetch helpers from a record of queries.

function createPrefetchHelpers<T extends Record<string, QueryOptionsCreator<any, any, any>>>(
  queries: T
): { [K in keyof T]: PrefetchHelper<...> }

prefetchAll

Prefetch multiple queries from different helpers in parallel.

function prefetchAll(
  queryClient: QueryClient,
  prefetches: Array<{ helper: PrefetchHelper<any, any, any>; params: unknown }>
): Promise<void>

Optimistic Update Helpers

createOptimisticUpdate

Creates type-safe optimistic update callbacks.

function createOptimisticUpdate<TData, TVariables, TQueryData>(
  config: OptimisticUpdateConfig<TData, TVariables, TQueryData>
): OptimisticUpdateCallbacks<TData, TVariables, TQueryData>

Config Options:

Option	Type	Default	Description
queryKey	readonly unknown[]	Required	Query key to update
updateFn	(oldData, variables) => newData	Required	Compute new cache value
rollbackOnError	boolean	true	Rollback on error
invalidateOnSettled	boolean	true	Invalidate after mutation

createMultiOptimisticUpdate

Creates optimistic update callbacks for multiple query keys.

function createMultiOptimisticUpdate<TData, TVariables>(
  configs: Array<OptimisticUpdateConfig<TData, TVariables, unknown>>
): OptimisticUpdateCallbacks<TData, TVariables, Map<string, unknown>>

Types

QueryConfig

interface QueryConfig {
  method: HttpMethod
  url: string
  responseSchema: ZodType
  querySchema?: ZodType
  requestSchema?: ZodType
  errorSchema?: ErrorSchemaRecord
  processResponse: (data: any) => any
}

MutationConfig

interface MutationConfig {
  method: HttpMethod
  url: string
  requestSchema?: ZodType
  responseSchema?: ZodType
  querySchema?: ZodType
  errorSchema?: ErrorSchemaRecord
  processResponse?: (data: any) => any
  useContext?: () => any
  onMutate?: (variables: any, context: any) => any
  onSuccess?: (data: any, variables: any, context: any) => void
  onError?: (error: any, variables: any, context: any) => void
  onSettled?: (data: any, error: any, variables: any, context: any) => void
  useKey?: boolean
}

InfiniteQueryConfig

interface InfiniteQueryConfig extends QueryConfig {
  getNextPageParam: (lastPage: any, allPages: any[]) => any
  getPreviousPageParam?: (firstPage: any, allPages: any[]) => any
  initialPageParam: any
}

ErrorSchemaRecord

type ErrorSchemaRecord = {
  [statusCode: number]: ZodType
}

PrefetchHelper

interface PrefetchHelper<TParams, TData, TError = Error> {
  prefetch: (queryClient: QueryClient, params: TParams) => Promise<void>
  ensureData: (queryClient: QueryClient, params: TParams) => Promise<TData>
  getQueryOptions: (params: TParams) => FetchQueryOptions<TData, TError, TData, QueryKey>
  prefetchMany: (queryClient: QueryClient, paramsList: TParams[]) => Promise<void>
}

OptimisticUpdateConfig

interface OptimisticUpdateConfig<TData, TVariables, TQueryData> {
  queryKey: readonly unknown[]
  updateFn: (oldData: TQueryData | undefined, variables: TVariables) => TQueryData
  rollbackOnError?: boolean
  invalidateOnSettled?: boolean
}

ComputeBaseResult

Helper type that computes result based on discriminator mode and error schema.

type ComputeBaseResult<
  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>

See Also

• Getting Started - Quick start guide
• Queries - Query usage
• Mutations - Mutation usage
• SSR & Prefetching - Server-side rendering
• Error Schemas - Error handling with discriminator mode
• Best Practices - Best practices and patterns