@kubb/plugin-react-query 5.10.0 → 5.10.2

package/docs/guides/calling-operations.md

@@ -12,16 +12,20 @@ A query hook takes the operation's grouped request config (`path`, `query`, `hea
 ```typescript
 import { useGetPetById } from './gen/hooks/useGetPetById'
 
-const { data, error, isLoading } = useGetPetById({ path: { petId: 1n } })
+const { data, error, isLoading } = useGetPetById({ path: { petId: 1 } })
 ```
 
+The examples set [`integerType: 'number'`](https://kubb.dev/extensions/kubb-labs/adapter-oas/options#integertype) on the adapter, so an `int64` id such as `petId` is a `number`. With the default it is a `bigint` and the call takes `1n`.
+
+Path keys keep the names from the spec, so a `{pet-id}` placeholder is passed as `path: { 'pet-id': 1 }`. Set [`pathParamsCasing: 'camelcase'`](https://kubb.dev/extensions/kubb-labs/adapter-oas/options#pathparamscasing) on the adapter (`@kubb/adapter-oas` 5.20.0 or later) to pass `path: { petId: 1 }` instead, the name MSW handlers and query keys already use. The HTTP request stays the same.
+
 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 } },
+  { path: { petId: 1 } },
   {
     query: { staleTime: 60_000 },
     client: { baseURL: 'https://api.example.com/v1' },
@@ -39,8 +43,8 @@ import { getPetByIdQueryKey, getPetByIdQueryOptions } from './gen/hooks/useGetPe
 
 const queryClient = useQueryClient()
 
-await queryClient.prefetchQuery(getPetByIdQueryOptions({ path: { petId: 1n } }))
-queryClient.invalidateQueries({ queryKey: getPetByIdQueryKey({ path: { petId: 1n } }) })
+await queryClient.prefetchQuery(getPetByIdQueryOptions({ path: { petId: 1 } }))
+queryClient.invalidateQueries({ queryKey: getPetByIdQueryKey({ path: { petId: 1 } }) })
 ```
 
 ## Mutations
@@ -57,7 +61,7 @@ const { mutate } = useDeletePet({
   mutation: { onSuccess: () => queryClient.invalidateQueries() },
 })
 
-mutate({ path: { petId: 1n } })
+mutate({ path: { petId: 1 } })
 ```
 
 Each mutation also exports a `mutationOptions` factory and a `mutationKey` helper.
@@ -111,7 +115,7 @@ const { data, fetchNextPage, hasNextPage } = useInfiniteQuery(
 
 ::
 
-`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.
+`nextParam` takes dot notation or an array of keys. Change it to match your API's response, and give `initialPageParam` the same type as the query parameter. Without `getNextPageParam`, `nextParam` or `cursorParam`, the generated options increment the page number until a page returns an empty array.
 
 ## Use suspense
 
@@ -128,7 +132,7 @@ pluginReactQuery({ hooks: true, suspense: {} })
 ```typescript [usage.ts]
 import { useGetPetByIdSuspense } from './gen/hooks/useGetPetByIdSuspense'
 
-const { data } = useGetPetByIdSuspense({ path: { petId: 1n } })
+const { data } = useGetPetByIdSuspense({ path: { petId: 1 } })
 ```
 
 ::

package/docs/options.md

@@ -16,7 +16,7 @@ Pass these options to `pluginReactQuery()`. Shared options link to [Shared plugi
 | [`queryKey`](#querykey)                                                   | Build the `queryKey` for each query hook.                              | Exported `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.                        | Exported `mutationKeyTransformer`                                                      |
-| [`customOptions`](#customoptions)                                         | Route every hook through your own options function.                    | None                                                                                   |
+| [`customOptions`](#customoptions)                                         | Route every hook through a custom 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.                                            | `[]`                                                                                   |
@@ -46,7 +46,7 @@ Calls the operations generated by [`@kubb/plugin-axios`](https://kubb.dev/extens
 :::
 
 :::field{name="'client'"}
-Calls the operations generated by [`@kubb/plugin-client`](https://kubb.dev/extensions/kubb-labs/plugin-client). Your client module must also export the `RequestConfig` and `ResponseErrorConfig` types.
+Calls the operations generated by [`@kubb/plugin-client`](https://kubb.dev/extensions/kubb-labs/plugin-client). The client module must also export the `RequestConfig` and `ResponseErrorConfig` types.
 :::
 
 ::
@@ -64,7 +64,7 @@ Shape of the value the generated hooks resolve to.
 ::field-group
 
 :::field{name="'full'"}
-Returns the client's whole `RequestResult` (`{ status, data, error, contentType, headers, request, response }`), so a hook can read the status and the response headers next to `data`. Infinite queries read the page cursor from `lastPage.data`. Needs a client plugin whose own `returnType` is `'full'` or `'plain'`; with a client `returnType: 'data'` generation stops with an error.
+Returns the client's whole `RequestResult` (`{ status, data, error, contentType, headers, request, response }`), so a hook can read the status and the response headers next to `data`. Infinite queries read the page cursor from `lastPage.data`. Needs a client plugin whose own `returnType` is `'full'` or `'plain'`. With a client `returnType: 'data'`, generation stops with an error.
 :::
 
 :::field{name="'data'"}
@@ -82,6 +82,8 @@ const etag = result?.response.headers.get('ETag')
 const pet = result?.data
 ```
 
+The examples set [`integerType: 'number'`](https://kubb.dev/extensions/kubb-labs/adapter-oas/options#integertype) on the adapter, so an `int64` id such as `petId` is a `number`. With the default it is a `bigint` and the call takes `1n`.
+
 ### infinite
 
 Adds `infiniteQueryOptions` and `useInfiniteQuery` for operations that declare the query parameter named in `infinite.queryParam`. Needs [`hooks: true`](#hooks).
@@ -134,7 +136,7 @@ Path to the previous-page cursor on the response, in the same dot or array form.
 
 #### infinite.cursorParam
 
-Deprecated path to the cursor field, read for both `getNextPageParam` and `getPreviousPageParam` when set. Use `nextParam` and `previousParam` instead.
+Deprecated name of a top-level response field that holds the cursor, read for both `getNextPageParam` and `getPreviousPageParam` when set. Dot paths are not supported. Use `nextParam` and `previousParam` instead.
 
 |          |                  |
 | -------- | ---------------- |
@@ -144,13 +146,13 @@ Deprecated path to the cursor field, read for both `getNextPageParam` and `getPr
 
 #### 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`.
+Source code for TanStack Query's `getNextPageParam`, copied into the generated code as written. Pass a string or a function. 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`           |
+|          |                                 |
+| -------- | ------------------------------- |
+| Type     | `string \| PageParamFn \| null` |
+| Required | `false`                         |
+| Default  | `null`                          |
 
 ```typescript
 infinite: {
@@ -160,17 +162,33 @@ infinite: {
 }
 ```
 
-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.
+`definePageParam` types the page and the page parameter, and returns the function's source. A plain function works too. Only the source is copied, so the function cannot reference variables from the config file.
+
+```typescript [kubb.config.ts]
+import { definePageParam, pluginReactQuery } from '@kubb/plugin-react-query'
+
+type PetsPage = { hasNext: boolean; number: number }
+
+pluginReactQuery({
+  hooks: true,
+  infinite: {
+    queryParam: 'page',
+    getNextPageParam: definePageParam<PetsPage, number>((lastPage) => (lastPage.hasNext ? lastPage.number + 1 : undefined)),
+  },
+})
+```
+
+Without `getNextPageParam`, `nextParam` or `cursorParam`, the hook counts pages up from `initialPageParam` until a page is an empty array. Counting works only for array responses, so generation warns for any other response.
 
 #### infinite.getPreviousPageParam
 
-Source code for TanStack Query's `getPreviousPageParam`, copied into the generated code as written. Takes precedence over `previousParam` and `cursorParam`.
+Source code for TanStack Query's `getPreviousPageParam`, copied into the generated code as written. Takes a string or a function, like `getNextPageParam`. Takes precedence over `previousParam` and `cursorParam`.
 
-|          |                  |
-| -------- | ---------------- |
-| Type     | `string \| null` |
-| Required | `false`          |
-| Default  | `null`           |
+|          |                                 |
+| -------- | ------------------------------- |
+| Type     | `string \| PageParamFn \| null` |
+| Required | `false`                         |
+| Default  | `null`                          |
 
 ### suspense
 
@@ -288,7 +306,7 @@ mutationKey: (props) => [JSON.stringify(props.node.operationId), ...mutationKeyT
 
 ### 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).
+Routes every hook through a custom 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).
 
 |          |                                         |
 | -------- | --------------------------------------- |
@@ -297,7 +315,7 @@ Routes every hook through your own function that returns extra options such as `
 
 #### customOptions.importPath
 
-Module of your custom-options hook, imported as a named import. It resolves from the generated hooks folder. When the module does not exist yet, Kubb writes a starter file there, but only when `importPath` stays inside the plugin's output folder. For a path outside it, create the module yourself.
+Module of the custom-options hook, imported as a named import. The path resolves from the generated hooks folder. When the module does not exist yet, Kubb writes a starter file there, but only when `importPath` stays inside the plugin's output folder. The starter file imports `HookOptions` from the generated `HookOptions.ts` file. A module outside the output folder is never created.
 
 |          |                                    |
 | -------- | ---------------------------------- |
@@ -306,7 +324,7 @@ Module of your custom-options hook, imported as a named import. It resolves from
 
 #### customOptions.name
 
-Exported name of your custom-options hook.
+Exported name of the custom-options hook.
 
 |          |                          |
 | -------- | ------------------------ |

package/docs/overview.md

@@ -12,12 +12,12 @@ The plugin ships no HTTP client. Each helper calls a function generated by a cli
 
 ## Options worth knowing
 
-- `client` picks `fetch` or `axios` when both client plugins are registered. A single client is detected automatically.
+- `client` picks `fetch`, `axios`, or `client` when more than one client plugin is registered. A single client plugin is detected automatically.
 - `hooks` adds the `use*` hooks on top of the option factories.
 - `suspense: {}` adds `useSuspenseQuery` hooks. It needs `hooks: true`.
 - `infinite` adds `useInfiniteQuery` hooks for pagination. It needs `hooks: true` and covers the operations that take the query parameter named in `infinite.queryParam`, which defaults to `'id'`.
-- `query` and `mutation` set which HTTP methods become queries (`GET`) and mutations (`POST`, `PUT`, `PATCH`, `DELETE`). They also set where the TanStack Query runtime is imported from. Set either to `false` to skip those helpers.
-- `customOptions: { importPath }` routes every hook through your own function that returns extra options. It needs `hooks: true`. Kubb creates a starter file at `importPath`, resolved from the generated hooks folder, when none exists and the path stays inside the plugin's output folder.
+- `query` and `mutation` set which HTTP methods become queries (`GET`, `QUERY`) and mutations (`POST`, `PUT`, `PATCH`, `DELETE`). They also set where the TanStack Query runtime is imported from. Set either to `false` to skip those helpers.
+- `customOptions: { importPath }` routes every hook through your own function that returns extra options. It needs `hooks: true`. `importPath` resolves from the generated hooks folder. Kubb creates a starter file there when none exists and the path stays inside the plugin's output folder.
 
 See [Options](https://kubb.dev/extensions/kubb-labs/plugin-react-query/options) for every option and its default.
 
@@ -27,6 +27,7 @@ The config below generates `useQuery` and `useMutation` hooks that call the Fetc
 
 ```typescript [kubb.config.ts]
 import { defineConfig } from 'kubb/config'
+import { adapterOas } from '@kubb/adapter-oas'
 import { pluginTs } from '@kubb/plugin-ts'
 import { pluginFetch } from '@kubb/plugin-fetch'
 import { pluginReactQuery } from '@kubb/plugin-react-query'
@@ -34,6 +35,7 @@ import { pluginReactQuery } from '@kubb/plugin-react-query'
 export default defineConfig({
   input: './petStore.yaml',
   output: { path: './src/gen' },
+  adapter: adapterOas({ integerType: 'number' }),
   plugins: [
     pluginTs(),
     pluginFetch(),

package/kubb-extension.json

@@ -17,8 +17,7 @@
       "github": "stijnvanhulle"
     }
   ],
-  "dependencies": ["plugin-ts"],
-  "optionalDependencies": ["plugin-zod"],
+  "optionalDependencies": ["plugin-ts", "plugin-zod"],
   "compatibility": {
     "kubb": ">=5.18.4",
     "node": ">=22.22"
@@ -97,7 +96,7 @@
       "key": "client",
       "path": ["client"],
       "label": "Client",
-      "description": "HTTP client the generated hooks call. Only needed to disambiguate when both plugin-fetch and plugin-axios are enabled",
+      "description": "HTTP client the generated hooks call. Only needed to disambiguate when more than one of plugin-fetch, plugin-axios and plugin-client is enabled",
       "type": "select",
       "default": null,
       "choices": [
@@ -112,6 +111,10 @@
         {
           "label": "axios",
           "value": "axios"
+        },
+        {
+          "label": "client",
+          "value": "client"
         }
       ]
     },
@@ -192,9 +195,9 @@
       "key": "queryMethods",
       "path": ["query", "methods"],
       "label": "Query Methods",
-      "description": "Comma-separated HTTP methods treated as queries (default: GET)",
+      "description": "Comma-separated HTTP methods treated as queries (default: GET, QUERY)",
       "type": "list",
-      "default": ["GET"],
+      "default": ["GET", "QUERY"],
       "itemCase": "upper"
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/plugin-react-query",
-  "version": "5.10.0",
+  "version": "5.10.2",
   "description": "Generate type-safe TanStack Query (React Query) hooks with Kubb. Covers useQuery, useMutation, useInfiniteQuery, and queryOptions with full TypeScript support.",
   "keywords": [
     "code-generation",
@@ -81,17 +81,17 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@kubb/kit": "^5.18.6",
-    "@kubb/plugin-ts": "^5.5.0",
-    "@kubb/renderer-jsx": "^5.18.6"
+    "@kubb/kit": "^5.19.0",
+    "@kubb/plugin-ts": "^5.5.2",
+    "@kubb/renderer-jsx": "^5.19.0"
   },
   "devDependencies": {
     "@internals/client": "0.0.0",
     "@internals/shared": "0.0.0",
     "@internals/tanstack-query": "0.0.0",
     "@internals/utils": "0.0.0",
-    "@kubb/plugin-client": "6.0.0",
-    "@tanstack/react-query": "^5.106.1"
+    "@kubb/plugin-client": "6.0.2",
+    "@tanstack/react-query": "^5.107.1"
   },
   "peerDependencies": {
     "@tanstack/react-query": "^5.82.0"