queryOptions

The queryOptions method allows you to construct type-safe Query Options.

queryOptions can be used together with @tanstack/react-query APIs that take query options, such as useQuery, useQueries, usePrefetchQuery and QueryClient.fetchQuery among many others.

If you would like to use a query API that is not explicitly supported by openapi-react-query, this is the way to go.

Examples

useQuery example rewritten using queryOptions.

import { useQuery } from '@tanstack/react-query';
import { $api } from "./api";

export const App = () => {
  const { data, error, isLoading } = useQuery(
    $api.queryOptions("get", "/users/{user_id}", {
      params: {
        path: { user_id: 5 },
      },
    }),
  );

  if (!data || isLoading) return "Loading...";
  if (error) return `An error occured: ${error.message}`;

  return <div>{data.firstname}</div>;
};

import createFetchClient from "@ternaus/openapi-fetch";
import createClient from "@ternaus/openapi-react-query";
import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript

const fetchClient = createFetchClient<paths>({
  baseUrl: "https://myapi.dev/v1/",
});
export const $api = createClient(fetchClient);

info Good to Know

Both useQuery and useSuspenseQuery use queryOptions under the hood.

Usage with useQueries.

import { useQueries } from '@tanstack/react-query';
import { $api } from "./api";

export const useUsersById = (userIds: number[]) => (
  useQueries({
    queries: userIds.map((userId) => (
      $api.queryOptions("get", "/users/{user_id}", {
        params: {
          path: { user_id: userId },
        },
      })
    ))
  })
);

import createFetchClient from "@ternaus/openapi-fetch";
import createClient from "@ternaus/openapi-react-query";
import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript

const fetchClient = createFetchClient<paths>({
  baseUrl: "https://myapi.dev/v1/",
});
export const $api = createClient(fetchClient);

Cache invalidation

Create query options for the endpoint, then pass their key to TanStack Query. This retains the client's cache namespace and the endpoint's checked parameters:

const options = $api.queryOptions("get", "/users/{user_id}", {
  params: { path: { user_id: 5 } },
});

await queryClient.invalidateQueries({ queryKey: options.queryKey });

Avoid building a universal wrapper from Parameters<typeof $api.queryOptions>. That extracts the generic function's constraints and loses the relationship between its method, path, and required request fields. Constructing the options first keeps those checks on the ordinary call.

Api

const queryOptions = $api.queryOptions(method, path, options, queryOptions);

Arguments

• method (required)
  • The HTTP method to use for the request.
  • The method is used as key. See Query Keys for more information.
• path (required)
  • The pathname to use for the request.
  • Must be an available path for the given method in your schema.
  • The pathname is used as key. See Query Keys for more information.
• options
  • The fetch options to use for the request.
  • Only required if the OpenApi schema requires parameters.
  • The options params are used as key. See Query Keys for more information.
• queryOptions
  • Additional query options to pass through.

Returns

• Query Options
  • Fully typed thus data and error will be correctly deducted.
  • queryKey is [baseUrl, cacheKey, "query", method, path, init].
  • queryFn is set to a fetcher function.