@kubb/plugin-vue-query 5.3.1 → 5.3.2

package/docs/guides/calling-operations.md

@@ -0,0 +1,132 @@
+# Call operations
+
+`@kubb/plugin-vue-query` can generate a typed TanStack Query composable for each operation. `GET` operations get query composables such as `useGetPetById`, and `POST`, `PUT`, `PATCH`, and `DELETE` operations get mutation composables such as `useUpdatePetWithForm`. Each composable calls the client function from `@kubb/plugin-fetch` or `@kubb/plugin-axios`.
+
+> [!IMPORTANT]
+> By default the plugin emits only the factory helpers (`queryOptions`, `queryKey`, `mutationKey`). Set [`hooks: true`](https://kubb.dev/extensions/kubb-labs/plugin-vue-query/options#hooks) in the plugin options to also generate the `use*` composables shown below.
+
+## Queries
+
+A query composable takes grouped request parameters as its first argument. Parameters accept a value, ref, or getter. See [reactive parameters](#refetch-when-parameters-change).
+
+```typescript [usage.ts]
+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`:
+
+```typescript
+import { useFindPetsByTags } from './gen/hooks/useFindPetsByTags'
+
+useFindPetsByTags(
+  { query: { tags: ['dog'] } },
+  {
+    query: { staleTime: 60_000 },
+    client: { baseURL: 'https://api.example.com/v1' },
+  },
+)
+```
+
+## Factories
+
+Every query operation also exports a `queryOptions` factory and a `queryKey` helper for prefetching and invalidation. The key is `[{ url }, query]`, built from the operation path and its query params:
+
+```typescript
+import { useQueryClient } from '@tanstack/vue-query'
+import { findPetsByTagsQueryKey, findPetsByTagsQueryOptions } from './gen/hooks/useFindPetsByTags'
+
+const queryClient = useQueryClient()
+
+await queryClient.prefetchQuery(findPetsByTagsQueryOptions({ query: { tags: ['dog'] } }))
+queryClient.invalidateQueries({ queryKey: findPetsByTagsQueryKey({ query: { tags: ['dog'] } }) })
+```
+
+Mutations export a `mutationKey` helper next to the composable.
+
+## Mutations
+
+A mutation composable 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/vue-query'
+import { useUpdatePetWithForm } from './gen/hooks/useUpdatePetWithForm'
+
+const queryClient = useQueryClient()
+
+const { mutate } = useUpdatePetWithForm({
+  mutation: { onSuccess: () => queryClient.invalidateQueries() },
+})
+
+mutate({ path: { petId: 1n }, query: { name: 'Fluffy' } })
+```
+
+## Errors and transport
+
+Each generated composable 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 { pluginVueQuery } from '@kubb/plugin-vue-query'
+
+pluginVueQuery({
+  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 { pluginVueQuery } from '@kubb/plugin-vue-query'
+
+pluginVueQuery({
+  hooks: true,
+  infinite: {
+    queryParam: 'page',
+    initialPageParam: 0,
+    nextParam: 'pagination.next.cursor',
+  },
+})
+```
+
+```typescript [usage.ts]
+import { useInfiniteQuery } from '@tanstack/vue-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.
+
+## Refetch when parameters change
+
+Enable `hooks: true`, then pass a ref or getter to a generated composable. Parameters accept `MaybeRefOrGetter`. A getter tracks its reactive dependencies.
+
+```typescript [usage.ts]
+import { ref } from 'vue'
+import { useFindPetsByTags } from './gen/hooks/useFindPetsByTags'
+
+const tags = ref(['dog'])
+const { data, error, isLoading } = useFindPetsByTags({
+  query: () => ({ tags: tags.value }),
+})
+
+tags.value = ['cat']
+```
+
+Changing `tags.value` updates the query key and fetches the corresponding resource.

package/docs/options.md

@@ -0,0 +1,271 @@
+# Options
+
+Pass these options to `pluginVueQuery()`. 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 composables call.                   | Auto-detected                                                                        |
+| [`infinite`](#infinite)                                                   | Add `useInfiniteQuery` composables for paginated reads.                | `false`                                                                              |
+| [`query`](#query)                                                         | Configure or disable query composables.                                | `{ methods: ['GET'], importPath: '@tanstack/vue-query' }`                            |
+| [`queryKey`](#querykey)                                                   | Build the `queryKey` for each query composable.                        | Built-in `queryKeyTransformer`                                                       |
+| [`mutation`](#mutation)                                                   | Configure or disable mutation composables.                             | `{ methods: ['POST', 'PUT', 'PATCH', 'DELETE'], importPath: '@tanstack/vue-query' }` |
+| [`mutationKey`](#mutationkey)                                             | Build the `mutationKey` for each mutation composable.                  | Built-in `mutationKeyTransformer`                                                    |
+| [`hooks`](#hooks)                                                         | Emit `use*` composables on top of the factory helpers.                 | `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.                              | `resolverVueQuery`                                                                   |
+| [`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 composables 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`                      |
+
+```typescript [infinite: {}, hooks: true]
+export function getPetsInfiniteQueryOptions(/* ... */) {
+  return infiniteQueryOptions({ queryKey, queryFn, initialPageParam, getNextPageParam })
+}
+
+export function useGetPetsInfiniteQuery(/* ... */) {
+  return useInfiniteQuery(getPetsInfiniteQueryOptions(/* ... */))
+}
+```
+
+#### infinite.queryParam
+
+Name of the query parameter that holds 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, such as `'(lastPage) => (lastPage.hasNext ? lastPage.number + 1 : undefined)'`. 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`           |
+
+Without `getNextPageParam`, `nextParam` or `cursorParam`, the composable 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`           |
+
+### query
+
+Decides which operations are treated as queries. The plugin generates a `queryOptions` factory for each match 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/vue-query' }` |
+
+#### query.methods
+
+HTTP methods treated as queries. A matching operation generates a `queryOptions` factory instead of a mutation.
+
+|          |                 |
+| -------- | --------------- |
+| Type     | `Array<string>` |
+| Required | `false`         |
+| Default  | `['GET']`       |
+
+#### query.importPath
+
+Module specifier for the generated `import { queryOptions } from '...'`.
+
+|          |                         |
+| -------- | ----------------------- |
+| Type     | `string`                |
+| Required | `false`                 |
+| Default  | `'@tanstack/vue-query'` |
+
+### queryKey
+
+Builds the `queryKey` for each query composable. The callback receives the operation `node`, the active `casing` and the `variant` (`'query'` or `'infiniteQuery'`) and returns the key array. Strings are copied into the generated code as written, so wrap a string literal in `JSON.stringify(...)`. The default adds `infinite: true` to infinite keys so they never share a cache entry with the plain query.
+
+|          |                                                        |
+| -------- | ------------------------------------------------------ |
+| Type     | `(props: { node, casing, variant }) => Array<unknown>` |
+| Required | `false`                                                |
+| Default  | Built-in `queryKeyTransformer`                         |
+
+::code-group
+
+```typescript [queryKey builder]
+queryKey: ({ node, variant }) => [JSON.stringify({ variant, operationId: node.operationId })]
+```
+
+```typescript [Generated output]
+export const getUserByNameQueryKey = () => [{ variant: 'query', operationId: 'getUserByName' }] as const
+```
+
+::
+
+### mutation
+
+Decides which operations are treated as mutations. The plugin generates a `mutationKey` helper for each match by default. Pass `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/vue-query' }` |
+
+#### mutation.methods
+
+HTTP methods treated as mutations. A matching operation generates mutation output instead of a query.
+
+|          |                                      |
+| -------- | ------------------------------------ |
+| Type     | `Array<string>`                      |
+| Required | `false`                              |
+| Default  | `['POST', 'PUT', 'PATCH', 'DELETE']` |
+
+#### mutation.importPath
+
+Module specifier for the generated `import { useMutation } from '...'`, emitted when [`hooks`](#hooks) is set.
+
+|          |                         |
+| -------- | ----------------------- |
+| Type     | `string`                |
+| Required | `false`                 |
+| Default  | `'@tanstack/vue-query'` |
+
+### mutationKey
+
+Builds the `mutationKey` for each mutation composable, useful for batching invalidations. It takes the same props as `queryKey` with `variant: 'mutation'` and inlines strings the same way, so wrap literals in `JSON.stringify(...)`.
+
+|          |                                                        |
+| -------- | ------------------------------------------------------ |
+| Type     | `(props: { node, casing, variant }) => Array<unknown>` |
+| Required | `false`                                                |
+| Default  | Built-in `mutationKeyTransformer`                      |
+
+### hooks
+
+Controls whether `use*` composables are emitted. The default `false` writes only the `queryOptions`, `queryKey`, and `mutationKey` factory helpers. Set `true` to also generate `useQuery`, `useInfiniteQuery`, and `useMutation`.
+
+|          |           |
+| -------- | --------- |
+| Type     | `boolean` |
+| Required | `false`   |
+| Default  | `false`   |
+
+### resolver
+
+Overrides generated file and symbol names. Omitted members keep `resolverVueQuery`. 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<ResolverVueQuery>` |
+| Required | `false`                           |
+
+::code-collapse{name="ResolverVueQuery patch members"}
+
+```typescript [Partial override]
+type ResolverVueQueryPatch = {
+  // plus the shared name, file, and imports members
+  query?: {
+    name?(node: OperationNode): string
+    optionsName?(node: OperationNode): string
+    keyName?(node: OperationNode): string
+    keyTypeName?(node: OperationNode): string
+    clientName?(node: OperationNode): string
+  }
+  infiniteQuery?: { /* same members as query */ }
+  mutation?: {
+    name?(node: OperationNode): string
+    keyName?(node: OperationNode): string
+    typeName?(node: OperationNode): string
+  }
+}
+```
+
+::

package/{OVERVIEW.md → docs/overview.md}

@@ -16,3 +16,26 @@ The plugin ships no HTTP client. Each helper calls a function generated by a cli
 - `hooks` adds the `use*` composables on top of the option factories.
 - `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.
+
+## Example
+
+```typescript [kubb.config.ts]
+import { defineConfig } from 'kubb/config'
+import { pluginTs } from '@kubb/plugin-ts'
+import { pluginFetch } from '@kubb/plugin-fetch'
+import { pluginVueQuery } from '@kubb/plugin-vue-query'
+
+export default defineConfig({
+  input: './petStore.yaml',
+  output: { path: './src/gen' },
+  plugins: [
+    pluginTs(),
+    pluginFetch(),
+    pluginVueQuery({ hooks: true }),
+  ],
+})
+```
+
+## See also
+
+- [TanStack Query for Vue](https://tanstack.com/query/latest/docs/framework/vue/overview)

package/kubb-extension.json

@@ -10,9 +10,16 @@
     "light": "https://kubb.dev/feature/tanstack.svg"
   },
   "tags": ["vue-query", "tanstack-query", "vue", "composables", "data-fetching", "codegen", "openapi"],
-  "docs": "https://kubb.dev/plugins/plugin-vue-query",
+  "docs": "https://kubb.dev/extensions/kubb-labs/plugin-vue-query",
+  "maintainers": [
+    {
+      "name": "Stijn Van Hulle",
+      "github": "stijnvanhulle"
+    }
+  ],
+  "dependencies": ["plugin-ts"],
   "compatibility": {
-    "kubb": ">=5.8.0",
+    "kubb": ">=5.8.3",
     "node": ">=22"
   },
   "role": "consumer",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/plugin-vue-query",
-  "version": "5.3.1",
+  "version": "5.3.2",
   "description": "Generate type-safe TanStack Query (Vue Query) composables with Kubb. Covers useQuery, useMutation, useInfiniteQuery, and queryOptions with Vue 3 Composition API support.",
   "keywords": [
     "code-generation",
@@ -19,7 +19,7 @@
     "vue-query",
     "vue3"
   ],
-  "homepage": "https://kubb.dev/plugins/plugin-vue-query",
+  "homepage": "https://kubb.dev/extensions/kubb-labs/plugin-vue-query",
   "license": "MIT",
   "author": "stijnvanhulle",
   "repository": {
@@ -44,7 +44,7 @@
   "files": [
     "dist",
     "kubb-extension.json",
-    "OVERVIEW.md",
+    "docs",
     "!/**/**.test.**",
     "!/**/__tests__/**",
     "!/**/__snapshots__/**"
@@ -78,7 +78,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@kubb/plugin-ts": "^5.0.8"
+    "@kubb/plugin-ts": "^5.0.9"
   },
   "devDependencies": {
     "@internals/client": "0.0.0",
@@ -86,11 +86,11 @@
     "@internals/tanstack-query": "0.0.0",
     "@internals/utils": "0.0.0",
     "@tanstack/vue-query": "^5.104.1",
-    "kubb": "^5.8.1"
+    "kubb": "^5.8.3"
   },
   "peerDependencies": {
     "@tanstack/vue-query": "^5.0.0",
-    "kubb": "^5.8.1"
+    "kubb": "^5.8.3"
   },
   "peerDependenciesMeta": {
     "@tanstack/vue-query": {