@kubb/plugin-react-query 5.3.0 → 5.3.2

package/docs/guides/calling-operations.md

@@ -0,0 +1,167 @@
+# Call operations
+
+`@kubb/plugin-react-query` can generate a typed TanStack Query hook for each operation. `GET` operations get query hooks such as `useGetPetById`, and `POST`, `PUT`, `PATCH`, and `DELETE` operations get mutation hooks such as `useDeletePet`. Each hook calls the client function from `@kubb/plugin-fetch` or `@kubb/plugin-axios`.
+
+> [!IMPORTANT]
+> By default the plugin emits only the factory helpers (`queryOptions`, `mutationOptions`, `queryKey`, `mutationKey`). Set [`hooks: true`](https://kubb.dev/extensions/kubb-labs/plugin-react-query/options#hooks) in the plugin options to also generate the `use*` hooks shown below.
+
+## Queries
+
+A query hook takes the operation's grouped request config (`path`, `query`, `headers`, whichever the operation declares) as its first argument and returns a TanStack `UseQueryResult`:
+
+```typescript
+import { useGetPetById } from './gen/hooks/useGetPetById'
+
+const { data, error, isLoading } = useGetPetById({ path: { petId: 1n } })
+```
+
+The second argument has two optional groups. `query` takes any TanStack Query option, and `query.client` sets the `QueryClient` to use. The top-level `client` takes request config for this call, such as `baseURL` or `signal`:
+
+```typescript
+import { useGetPetById } from './gen/hooks/useGetPetById'
+
+useGetPetById(
+  { path: { petId: 1n } },
+  {
+    query: { staleTime: 60_000 },
+    client: { baseURL: 'https://api.example.com/v1' },
+  },
+)
+```
+
+## Factories
+
+Each query operation also exports a `queryOptions` factory and a `queryKey` helper. Use them to prefetch or invalidate a query outside a hook. The key includes the operation URL and path parameters, followed by query or body values when present:
+
+```typescript
+import { useQueryClient } from '@tanstack/react-query'
+import { getPetByIdQueryKey, getPetByIdQueryOptions } from './gen/hooks/useGetPetById'
+
+const queryClient = useQueryClient()
+
+await queryClient.prefetchQuery(getPetByIdQueryOptions({ path: { petId: 1n } }))
+queryClient.invalidateQueries({ queryKey: getPetByIdQueryKey({ path: { petId: 1n } }) })
+```
+
+## Mutations
+
+A mutation hook takes only an options object. The grouped request config is the mutation variable, so you pass it to `mutate` or `mutateAsync`:
+
+```typescript
+import { useQueryClient } from '@tanstack/react-query'
+import { useDeletePet } from './gen/hooks/useDeletePet'
+
+const queryClient = useQueryClient()
+
+const { mutate } = useDeletePet({
+  mutation: { onSuccess: () => queryClient.invalidateQueries() },
+})
+
+mutate({ path: { petId: 1n } })
+```
+
+Each mutation also exports a `mutationOptions` factory and a `mutationKey` helper.
+
+## Errors and transport
+
+Each generated hook calls the client function with `throwOnError: true`. A failed request sets TanStack Query's `error`, typed from the error responses in the spec. Set the base URL, authentication, interceptors, serialization, and validation on the client plugin. See the [plugin-fetch](https://kubb.dev/extensions/kubb-labs/plugin-fetch) or [plugin-axios](https://kubb.dev/extensions/kubb-labs/plugin-axios) guide.
+
+## Customize cache keys
+
+Set `queryKey` on the plugin to change generated keys. String entries are emitted as source code, so use `JSON.stringify` for a string literal.
+
+```typescript [kubb.config.ts]
+import { pluginReactQuery } from '@kubb/plugin-react-query'
+
+pluginReactQuery({
+  queryKey: ({ node }) => [JSON.stringify(node.operationId)],
+})
+```
+
+> [!WARNING]
+> This `queryKey` gives every call the same key, such as `['getUserByName']`. If path or query values select different data, add them to the key.
+
+## Load more pages
+
+Configure `infinite` with a query parameter declared by the operation, its initial value, and the response path for the next cursor. Infinite output needs `hooks: true`, and only operations that declare the `queryParam` receive it.
+
+::code-group
+
+```typescript [kubb.config.ts]
+import { pluginReactQuery } from '@kubb/plugin-react-query'
+
+pluginReactQuery({
+  hooks: true,
+  infinite: {
+    queryParam: 'page',
+    initialPageParam: 0,
+    nextParam: 'pagination.next.cursor',
+  },
+})
+```
+
+```typescript [usage.ts]
+import { useInfiniteQuery } from '@tanstack/react-query'
+import { findPetsByTagsInfiniteQueryOptions } from './gen/hooks/useFindPetsByTagsInfinite'
+
+const { data, fetchNextPage, hasNextPage } = useInfiniteQuery(
+  findPetsByTagsInfiniteQueryOptions({ query: { tags: ['dog'] } }),
+)
+```
+
+::
+
+`nextParam` takes dot notation or an array of keys. Change it to match your API's response. Without `getNextPageParam`, `nextParam` or `cursorParam`, the generated options increment the page number until a page returns an empty array.
+
+## Use suspense
+
+Set `suspense: {}` and `hooks: true` to generate suspense hooks alongside regular hooks. Suspense requires TanStack Query v5 or higher.
+
+::code-group
+
+```typescript [kubb.config.ts]
+import { pluginReactQuery } from '@kubb/plugin-react-query'
+
+pluginReactQuery({ hooks: true, suspense: {} })
+```
+
+```typescript [usage.ts]
+import { useGetPetByIdSuspense } from './gen/hooks/useGetPetByIdSuspense'
+
+const { data } = useGetPetByIdSuspense({ path: { petId: 1n } })
+```
+
+::
+
+## Share hook options
+
+Set [`customOptions`](https://kubb.dev/extensions/kubb-labs/plugin-react-query/options#customoptions) to call one options function from every generated hook.
+
+```typescript [kubb.config.ts]
+import { pluginReactQuery } from '@kubb/plugin-react-query'
+
+pluginReactQuery({
+  hooks: true,
+  customOptions: {
+    importPath: './useCustomHookOptions',
+    name: 'useCustomHookOptions',
+  },
+})
+```
+
+Create the function at `importPath`, resolved from the generated hooks folder (here `src/gen/hooks/useCustomHookOptions.ts`). Each hook passes `{ hookName, operationId }`. The generated barrel re-exports `HookOptions`.
+
+```typescript [src/gen/hooks/useCustomHookOptions.ts]
+import type { HookOptions } from './HookOptions'
+
+export function useCustomHookOptions(
+  { hookName }: { hookName: keyof HookOptions; operationId: string },
+) {
+  if (hookName === 'useGetPetById') {
+    return { staleTime: 60_000 } satisfies HookOptions['useGetPetById']
+  }
+  return {}
+}
+```
+
+Per-call query options override shared options.

package/docs/options.md

@@ -0,0 +1,308 @@
+# Options
+
+Pass these options to `pluginReactQuery()`. Shared options link to [Shared plugin options](https://kubb.dev/docs/5.x/reference/plugin-options) for details.
+
+## Options overview
+
+| Option                                                                    | Purpose                                                                | Default                                                                                |
+| ------------------------------------------------------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| [`output`](https://kubb.dev/docs/5.x/reference/plugin-options#output)     | Where files are written: `path`, `mode`, `barrel`, `banner`, `footer`. | `{ path: 'hooks', barrel: { type: 'named' } }`                                         |
+| [`group`](https://kubb.dev/docs/5.x/reference/plugin-options#group)       | Split output by tag or path: `type`, `name`.                           | None                                                                                   |
+| [`client`](#client)                                                       | Which registered client plugin the hooks call.                         | Auto-detected                                                                          |
+| [`infinite`](#infinite)                                                   | Generate `useInfiniteQuery` hooks for pagination.                      | `false`                                                                                |
+| [`suspense`](#suspense)                                                   | Generate `useSuspenseQuery` hooks.                                     | `false`                                                                                |
+| [`query`](#query)                                                         | Configure the query hooks.                                             | `{ methods: ['GET'], importPath: '@tanstack/react-query' }`                            |
+| [`queryKey`](#querykey)                                                   | Build the `queryKey` for each query hook.                              | Built-in `queryKeyTransformer`                                                         |
+| [`mutation`](#mutation)                                                   | Configure the mutation hooks.                                          | `{ methods: ['POST', 'PUT', 'PATCH', 'DELETE'], importPath: '@tanstack/react-query' }` |
+| [`mutationKey`](#mutationkey)                                             | Build the `mutationKey` for each mutation hook.                        | Built-in `mutationKeyTransformer`                                                      |
+| [`customOptions`](#customoptions)                                         | Route every hook through your own options function.                    | None                                                                                   |
+| [`hooks`](#hooks)                                                         | Emit `use*` hook functions on top of the factories.                    | `false`                                                                                |
+| [`include`](https://kubb.dev/docs/5.x/reference/plugin-options#include)   | Keep only operations that match.                                       | None                                                                                   |
+| [`exclude`](https://kubb.dev/docs/5.x/reference/plugin-options#exclude)   | Skip operations that match.                                            | `[]`                                                                                   |
+| [`override`](https://kubb.dev/docs/5.x/reference/plugin-options#override) | Apply different options per pattern.                                   | `[]`                                                                                   |
+| [`resolver`](#resolver)                                                   | Customize generated names and file paths.                              | `resolverReactQuery`                                                                   |
+| [`macros`](https://kubb.dev/docs/5.x/reference/plugin-options#macros)     | Rewrite AST nodes before printing.                                     | `[]`                                                                                   |
+
+## Option details
+
+### client
+
+Selects which registered client plugin the hooks call. A single registered client is auto-detected. Set `client` when several are registered.
+
+|          |                      |
+| -------- | -------------------- |
+| Type     | `'axios' \| 'fetch'` |
+| Required | `false`              |
+
+::field-group
+
+:::field{name="'fetch'"}
+Calls the operations generated by [`@kubb/plugin-fetch`](https://kubb.dev/extensions/kubb-labs/plugin-fetch).
+:::
+
+:::field{name="'axios'"}
+Calls the operations generated by [`@kubb/plugin-axios`](https://kubb.dev/extensions/kubb-labs/plugin-axios).
+:::
+
+::
+
+### infinite
+
+Adds `infiniteQueryOptions` and `useInfiniteQuery` for operations that declare the query parameter named in `infinite.queryParam`. Needs [`hooks: true`](#hooks).
+
+|          |                              |
+| -------- | ---------------------------- |
+| Type     | `Partial<Infinite> \| false` |
+| Required | `false`                      |
+| Default  | `false`                      |
+
+#### infinite.queryParam
+
+Query parameter that carries the page cursor.
+
+|          |          |
+| -------- | -------- |
+| Type     | `string` |
+| Required | `false`  |
+| Default  | `'id'`   |
+
+#### infinite.initialPageParam
+
+Initial value for `pageParam` on the first fetch.
+
+|          |           |
+| -------- | --------- |
+| Type     | `unknown` |
+| Required | `false`   |
+| Default  | `0`       |
+
+#### infinite.nextParam
+
+Path to the next-page cursor on the response, as dot notation (`'pagination.next.id'`) or array form (`['pagination', 'next', 'id']`).
+
+|          |                                   |
+| -------- | --------------------------------- |
+| Type     | `string \| Array<string> \| null` |
+| Required | `false`                           |
+| Default  | `null`                            |
+
+#### infinite.previousParam
+
+Path to the previous-page cursor on the response, in the same dot or array form.
+
+|          |                                   |
+| -------- | --------------------------------- |
+| Type     | `string \| Array<string> \| null` |
+| Required | `false`                           |
+| Default  | `null`                            |
+
+#### infinite.cursorParam
+
+Deprecated path to the cursor field, read for both `getNextPageParam` and `getPreviousPageParam` when set. Use `nextParam` and `previousParam` instead.
+
+|          |                  |
+| -------- | ---------------- |
+| Type     | `string \| null` |
+| Required | `false`          |
+| Default  | `null`           |
+
+#### infinite.getNextPageParam
+
+Source code for TanStack Query's `getNextPageParam`, copied into the generated code as written. Use it when the next page must be computed instead of read from a field. Takes precedence over `nextParam` and `cursorParam`.
+
+|          |                  |
+| -------- | ---------------- |
+| Type     | `string \| null` |
+| Required | `false`          |
+| Default  | `null`           |
+
+```typescript
+infinite: {
+  queryParam: 'page',
+  getNextPageParam: '(lastPage) => (lastPage.hasNext ? lastPage.number + 1 : undefined)',
+  getPreviousPageParam: '(firstPage) => (firstPage.number > 0 ? firstPage.number - 1 : undefined)',
+}
+```
+
+Without `getNextPageParam`, `nextParam` or `cursorParam`, the hook counts pages up from `initialPageParam` until a page is an empty array. This works only for array responses, so generation warns when the response is an object.
+
+#### infinite.getPreviousPageParam
+
+Source code for TanStack Query's `getPreviousPageParam`, copied into the generated code as written. Takes precedence over `previousParam` and `cursorParam`.
+
+|          |                  |
+| -------- | ---------------- |
+| Type     | `string \| null` |
+| Required | `false`          |
+| Default  | `null`           |
+
+### suspense
+
+Adds `useSuspenseQuery` hooks next to the regular query hooks. Pass `{}` to turn it on. Needs TanStack Query v5 or higher and [`hooks: true`](#hooks).
+
+|          |                            |
+| -------- | -------------------------- |
+| Type     | `Partial<object> \| false` |
+| Required | `false`                    |
+| Default  | `false`                    |
+
+### query
+
+Which operations become queries, emitting a `queryOptions` factory by default. Pass `false` to skip, or set [`hooks`](#hooks) to also emit `useQuery`.
+
+|          |                                                             |
+| -------- | ----------------------------------------------------------- |
+| Type     | `Partial<Query> \| false`                                   |
+| Required | `false`                                                     |
+| Default  | `{ methods: ['GET'], importPath: '@tanstack/react-query' }` |
+
+#### query.methods
+
+HTTP methods treated as queries.
+
+|          |                 |
+| -------- | --------------- |
+| Type     | `Array<string>` |
+| Required | `false`         |
+| Default  | `['GET']`       |
+
+#### query.importPath
+
+Module for the `queryOptions` and `useQuery` imports.
+
+|          |                           |
+| -------- | ------------------------- |
+| Type     | `string`                  |
+| Required | `false`                   |
+| Default  | `'@tanstack/react-query'` |
+
+### queryKey
+
+Builds the `queryKey` for each hook from the operation `node`, `casing` and `variant`. Strings are copied into the generated code as written, so wrap a string literal in `JSON.stringify(...)`.
+
+|          |                                                        |
+| -------- | ------------------------------------------------------ |
+| Type     | `(props: { node, casing, variant }) => Array<unknown>` |
+| Required | `false`                                                |
+| Default  | Built-in `queryKeyTransformer`                         |
+
+`variant` is `'query'`, `'suspenseQuery'`, `'infiniteQuery'` or `'suspenseInfiniteQuery'`. The default key adds `infinite: true` to infinite variants so they never share a cache entry with the plain query.
+
+```typescript
+queryKey: ({ node, variant }) => [JSON.stringify({ variant, operationId: node.operationId })]
+```
+
+### mutation
+
+Which operations become mutations, emitting a `mutationOptions` factory by default. Set `false` to skip, or set [`hooks`](#hooks) to also emit `useMutation`.
+
+|          |                                                                                        |
+| -------- | -------------------------------------------------------------------------------------- |
+| Type     | `Partial<Mutation> \| false`                                                           |
+| Required | `false`                                                                                |
+| Default  | `{ methods: ['POST', 'PUT', 'PATCH', 'DELETE'], importPath: '@tanstack/react-query' }` |
+
+#### mutation.methods
+
+HTTP methods treated as mutations.
+
+|          |                                      |
+| -------- | ------------------------------------ |
+| Type     | `Array<string>`                      |
+| Required | `false`                              |
+| Default  | `['POST', 'PUT', 'PATCH', 'DELETE']` |
+
+#### mutation.importPath
+
+Module for the `mutationOptions` and `useMutation` imports.
+
+|          |                           |
+| -------- | ------------------------- |
+| Type     | `string`                  |
+| Required | `false`                   |
+| Default  | `'@tanstack/react-query'` |
+
+### mutationKey
+
+Builds the `mutationKey` for each mutation hook, for batched invalidations or `useMutationState`. Same props and string-inlining caveat as `queryKey`, with `variant` set to `'mutation'`.
+
+|          |                                                        |
+| -------- | ------------------------------------------------------ |
+| Type     | `(props: { node, casing, variant }) => Array<unknown>` |
+| Required | `false`                                                |
+| Default  | Built-in `mutationKeyTransformer`                      |
+
+### customOptions
+
+Routes every hook through your own function that returns extra options such as `onSuccess` or `select`. Also emits a `HookOptions` type that maps each hook name to its options type. Needs [`hooks: true`](#hooks).
+
+|          |                                         |
+| -------- | --------------------------------------- |
+| Type     | `{ importPath: string, name?: string }` |
+| Required | `false`                                 |
+
+#### customOptions.importPath
+
+Module of your custom-options hook, imported as a named import.
+
+|          |                                    |
+| -------- | ---------------------------------- |
+| Type     | `string`                           |
+| Required | `true` when `customOptions` is set |
+
+#### customOptions.name
+
+Exported name of your custom-options hook.
+
+|          |                          |
+| -------- | ------------------------ |
+| Type     | `string`                 |
+| Required | `false`                  |
+| Default  | `'useCustomHookOptions'` |
+
+### hooks
+
+When `false` (the default), only the `queryOptions`, `mutationOptions`, `queryKey` and `mutationKey` helpers are written, using factory imports that work across TanStack Query adapters. Set `true` to also generate `useQuery`, `useSuspenseQuery`, `useInfiniteQuery`, `useSuspenseInfiniteQuery`, and `useMutation`.
+
+|          |           |
+| -------- | --------- |
+| Type     | `boolean` |
+| Required | `false`   |
+| Default  | `false`   |
+
+### resolver
+
+Overrides generated file and symbol names. Omitted members keep `resolverReactQuery`. The shared members (`name`, `file`, `imports`) and the `this` context are described under [`resolver`](https://kubb.dev/docs/5.x/reference/plugin-options#resolver).
+
+|          |                                     |
+| -------- | ----------------------------------- |
+| Type     | `ResolverPatch<ResolverReactQuery>` |
+| Required | `false`                             |
+
+::code-collapse{name="ResolverReactQuery patch members"}
+
+```typescript [Partial override]
+type ResolverReactQueryPatch = {
+  // plus the shared name, file, and imports members
+  query?: {
+    name?(node: OperationNode): string         // → 'useGetPetById'
+    optionsName?(node: OperationNode): string  // → 'getPetByIdQueryOptions'
+    keyName?(node: OperationNode): string       // → 'getPetByIdQueryKey'
+    keyTypeName?(node: OperationNode): string   // → 'GetPetByIdQueryKey'
+    clientName?(node: OperationNode): string    // → 'getPetById'
+  }
+  // suspenseQuery, infiniteQuery, suspenseInfiniteQuery: same members as query
+  mutation?: {
+    name?(node: OperationNode): string          // → 'useUpdatePet'
+    optionsName?(node: OperationNode): string
+    keyName?(node: OperationNode): string
+    typeName?(node: OperationNode): string      // → 'UpdatePet'
+  }
+  hook?: {
+    optionsName?(): string
+    customOptionsName?(): string
+  }
+}
+```
+
+::

package/docs/overview.md

@@ -0,0 +1,43 @@
+# React Query
+
+Generates TanStack Query helpers for React from your OpenAPI spec. By default you get `queryOptions` and `mutationOptions` factories with their cache keys. Set `hooks: true` to also get `useQuery`, `useSuspenseQuery`, `useInfiniteQuery`, and `useMutation` hooks.
+
+The plugin ships no HTTP client. Each helper calls a function generated by a client plugin.
+
+## Setup
+
+- Add `@kubb/plugin-ts` and a client plugin: `@kubb/plugin-fetch` or `@kubb/plugin-axios`.
+- Install `@tanstack/react-query` v5 or higher in the app that uses the generated code.
+- Configure validation on the client plugin, not here.
+
+## Options worth knowing
+
+- `client` picks `fetch` or `axios` when both client plugins are registered. A single client is detected automatically.
+- `hooks` adds the `use*` hooks on top of the option factories.
+- `suspense` adds `useSuspenseQuery` hooks.
+- `infinite` adds infinite queries for pagination. Set `infinite.queryParam` to the query parameter that holds the page cursor.
+- `query` and `mutation` set which HTTP methods become queries (`GET`) and mutations (`POST`, `PUT`, `PATCH`, `DELETE`), and where the TanStack Query runtime is imported from. Set either to `false` to skip it.
+- `customOptions` routes every hook through your own function that returns extra options.
+
+## Example
+
+```typescript [kubb.config.ts]
+import { defineConfig } from 'kubb/config'
+import { pluginTs } from '@kubb/plugin-ts'
+import { pluginFetch } from '@kubb/plugin-fetch'
+import { pluginReactQuery } from '@kubb/plugin-react-query'
+
+export default defineConfig({
+  input: './petStore.yaml',
+  output: { path: './src/gen' },
+  plugins: [
+    pluginTs(),
+    pluginFetch(),
+    pluginReactQuery({ hooks: true }),
+  ],
+})
+```
+
+## See also
+
+- [TanStack Query](https://tanstack.com/query)