@kubb/plugin-vue-query 5.3.0 → 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/docs/overview.md

@@ -0,0 +1,41 @@
+# Vue Query
+
+Generates TanStack Query helpers for Vue from your OpenAPI spec. By default you get `queryOptions` factories with their query and mutation keys. Set `hooks: true` to also get `useQuery`, `useInfiniteQuery`, and `useMutation` composables with reactive parameters.
+
+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/vue-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*` 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

@@ -0,0 +1,215 @@
+{
+  "$schema": "https://kubb.dev/schemas/kubb-extension.json",
+  "kind": "plugin",
+  "name": "plugin-vue-query",
+  "export": "pluginVueQuery",
+  "displayName": "Vue Query",
+  "description": "Generates TanStack Query composables for Vue from your OpenAPI spec, so every read and write is a typed useQuery, useInfiniteQuery, or useMutation.",
+  "category": "framework",
+  "icon": {
+    "light": "https://kubb.dev/feature/tanstack.svg"
+  },
+  "tags": ["vue-query", "tanstack-query", "vue", "composables", "data-fetching", "codegen", "openapi"],
+  "docs": "https://kubb.dev/extensions/kubb-labs/plugin-vue-query",
+  "maintainers": [
+    {
+      "name": "Stijn Van Hulle",
+      "github": "stijnvanhulle"
+    }
+  ],
+  "dependencies": ["plugin-ts"],
+  "compatibility": {
+    "kubb": ">=5.8.3",
+    "node": ">=22"
+  },
+  "role": "consumer",
+  "options": [
+    {
+      "key": "outputPath",
+      "path": ["output", "path"],
+      "label": "Output Path",
+      "description": "Output folder for generated files",
+      "type": "text",
+      "default": "hooks"
+    },
+    {
+      "key": "barrel",
+      "path": ["output", "barrel"],
+      "label": "Barrel",
+      "description": "How index.ts barrel files are generated",
+      "type": "select",
+      "default": {
+        "type": "named"
+      },
+      "choices": [
+        {
+          "label": "named",
+          "value": {
+            "type": "named"
+          }
+        },
+        {
+          "label": "named (nested)",
+          "value": {
+            "type": "named",
+            "nested": true
+          }
+        },
+        {
+          "label": "all",
+          "value": {
+            "type": "all"
+          }
+        },
+        {
+          "label": "all (nested)",
+          "value": {
+            "type": "all",
+            "nested": true
+          }
+        },
+        {
+          "label": "false (disabled)",
+          "value": false
+        }
+      ]
+    },
+    {
+      "key": "outputMode",
+      "path": ["output", "mode"],
+      "label": "Output Mode",
+      "description": "How the plugin consolidates its code into files. File mode writes everything into a single file, so the output path must include a file extension and cannot be grouped.",
+      "type": "select",
+      "default": "directory",
+      "choices": [
+        {
+          "label": "directory (one file per schema)",
+          "value": "directory"
+        },
+        {
+          "label": "file (single file)",
+          "value": "file"
+        }
+      ]
+    },
+    {
+      "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",
+      "type": "select",
+      "default": null,
+      "choices": [
+        {
+          "label": "auto-detect",
+          "value": null
+        },
+        {
+          "label": "fetch",
+          "value": "fetch"
+        },
+        {
+          "label": "axios",
+          "value": "axios"
+        }
+      ]
+    },
+    {
+      "key": "group",
+      "path": ["group"],
+      "label": "Group",
+      "description": "Group generated operations by OpenAPI tag or path",
+      "type": "select",
+      "default": null,
+      "choices": [
+        {
+          "label": "none",
+          "value": null
+        },
+        {
+          "label": "by tag",
+          "value": {
+            "type": "tag"
+          }
+        },
+        {
+          "label": "by path",
+          "value": {
+            "type": "path"
+          }
+        }
+      ]
+    },
+    {
+      "key": "excludeTags",
+      "path": ["exclude"],
+      "label": "Exclude Tags",
+      "description": "Comma-separated OpenAPI tags to exclude from generation",
+      "type": "list",
+      "item": {
+        "type": "tag",
+        "pattern": "$item"
+      }
+    },
+    {
+      "key": "includeTags",
+      "path": ["include"],
+      "label": "Include Tags",
+      "description": "Comma-separated OpenAPI tags to include. Only operations with these tags are generated",
+      "type": "list",
+      "item": {
+        "type": "tag",
+        "pattern": "$item"
+      }
+    },
+    {
+      "key": "hooks",
+      "path": ["hooks"],
+      "label": "Hooks",
+      "description": "Generate use* functions instead of only queryOptions and mutation helpers",
+      "type": "boolean",
+      "default": false
+    },
+    {
+      "key": "infiniteQueryParam",
+      "path": ["infinite", "queryParam"],
+      "label": "Infinite Query Param",
+      "description": "Enable infinite queries, set the pageParam key (e.g. \"id\"). Leave empty to disable.",
+      "type": "text"
+    },
+    {
+      "key": "queryMethods",
+      "path": ["query", "methods"],
+      "label": "Query Methods",
+      "description": "Comma-separated HTTP methods treated as queries (default: GET)",
+      "type": "list",
+      "default": ["GET"],
+      "itemCase": "upper"
+    },
+    {
+      "key": "queryImportPath",
+      "path": ["query", "importPath"],
+      "label": "Query Import Path",
+      "description": "Module specifier the generated query hook imports from",
+      "type": "text",
+      "default": "@tanstack/vue-query"
+    },
+    {
+      "key": "mutationMethods",
+      "path": ["mutation", "methods"],
+      "label": "Mutation Methods",
+      "description": "Comma-separated HTTP methods treated as mutations (default: POST, PUT, PATCH, DELETE)",
+      "type": "list",
+      "default": ["POST", "PUT", "PATCH", "DELETE"],
+      "itemCase": "upper"
+    },
+    {
+      "key": "mutationImportPath",
+      "path": ["mutation", "importPath"],
+      "label": "Mutation Import Path",
+      "description": "Module specifier the generated mutation hook imports from",
+      "type": "text",
+      "default": "@tanstack/vue-query"
+    }
+  ]
+}