@kubb/plugin-vue-query 5.0.0-alpha.9 → 5.0.0-beta.10

package/extension.yaml

@@ -0,0 +1,732 @@
+$schema: https://kubb.dev/schemas/extension.json
+kind: plugin
+id: plugin-vue-query
+name: Vue Query
+description: Generate Vue Query composables from OpenAPI specifications.
+category: framework
+type: official
+npmPackage: '@kubb/plugin-vue-query'
+docsPath: /plugins/plugin-vue-query
+repo: https://github.com/kubb-labs/plugins
+maintainers:
+  - name: Stijn Van Hulle
+    github: stijnvanhulle
+compatibility:
+  kubb: '>=5.0.0'
+  node: '>=22'
+tags:
+  - vue-query
+  - tanstack-query
+  - vue
+  - composables
+  - data-fetching
+  - codegen
+  - openapi
+dependencies:
+  - plugin-ts
+  - plugin-client
+resources:
+  documentation: https://kubb.dev/plugins/plugin-vue-query
+  repository: https://github.com/kubb-labs/plugins
+  issues: https://github.com/kubb-labs/plugins/issues
+  changelog: https://github.com/kubb-labs/plugins/blob/main/packages/plugin-vue-query/CHANGELOG.md
+  codesandbox: https://codesandbox.io/p/github/kubb-labs/plugins/main/examples/vue-query
+featured: false
+icon:
+  light: https://kubb.dev/feature/tanstack.svg
+intro: |
+  # @kubb/plugin-vue-query
+
+  Generate type-safe Vue Query composables from your OpenAPI schema for data fetching, caching, and synchronization.
+options:
+  - name: output
+    type: Output
+    required: false
+    default: "{ path: 'hooks', barrel: { type: 'named' } }"
+    description: Specify the export location for the files and define the behavior of the output.
+    properties:
+      - name: path
+        type: string
+        required: true
+        description: Output directory or file for the generated code, relative to the global `output.path`.
+        tip: |
+          if `output.path` is a file, `group` cannot be used.
+        default: "'hooks'"
+      - name: barrel
+        type: "{ type: 'named' | 'all', nested?: boolean } | false"
+        required: false
+        default: "{ type: 'named' }"
+        description: "Configure barrel file export strategy. Use `type` to control named vs. wildcard exports; set `nested: true` to generate hierarchical barrels in subdirectories."
+        examples:
+          - name: all
+            files:
+              - lang: typescript
+                code: |
+                  export * from './gen/petService.ts'
+                twoslash: false
+          - name: named
+            files:
+              - lang: typescript
+                code: |
+                  export { PetService } from './gen/petService.ts'
+                twoslash: false
+          - name: 'false'
+            files:
+              - lang: typescript
+                code: ''
+                twoslash: false
+      - name: banner
+        type: 'string | ((node: RootNode) => string)'
+        required: false
+        description: Add a banner comment at the top of every generated file. Accepts a static string or a function that receives the `RootNode` and returns a string.
+      - name: footer
+        type: 'string | ((node: RootNode) => string)'
+        required: false
+        description: Add a footer comment at the end of every generated file. Accepts a static string or a function that receives the `RootNode` and returns a string.
+      - name: override
+        type: boolean
+        required: false
+        default: 'false'
+        description: Whether Kubb overrides existing external files that can be generated if they already exist.
+  - name: group
+    type: Group
+    required: false
+    description: |
+      Grouping combines files in a folder based on a specific `type`.
+    examples:
+      - name: kubb.config.ts
+        files:
+          - lang: typescript
+            code: |
+              group: {
+                type: 'tag',
+                name({ group }) {
+                  return `${group}Controller`
+                }
+              }
+            twoslash: false
+    body: |
+      With the configuration above, the generator emits:
+
+      ```text
+      .
+      ├── src/
+      │   └── petController/
+      │   │   ├── addPet.ts
+      │   │   └── getPet.ts
+      │   └── storeController/
+      │       ├── createStore.ts
+      │       └── getStoreById.ts
+      ├── petStore.yaml
+      ├── kubb.config.ts
+      └── package.json
+      ```
+    properties:
+      - name: type
+        type: "'tag'"
+        required: true
+        description: Specify the property to group files by. Required when `group` is defined.
+        note: |
+          `Required: true*` means this is required only when the `group` option is used. The `group` option itself is optional.
+        body: |
+          - `'tag'`: Uses the first tag from `operation.getTags().at(0)?.name`
+      - name: name
+        type: '(context: GroupContext) => string'
+        required: false
+        default: (ctx) => `${ctx.group}Controller`
+        description: Return the name of a group based on the group name. This is used for file and identifier generation.
+  - name: client
+    type: ClientImportPath & { clientType?, dataReturnType?, baseURL?, bundle?, paramsCasing? }
+    required: false
+    description: Client configuration for HTTP request generation.
+    properties:
+      - name: importPath
+        type: string
+        required: false
+        description: Path to the client used for API calls. Supports both relative and absolute paths.
+        details:
+          - title: When to use `importPath`
+            body: |
+              Use `importPath` when you want to:
+
+              - **Customize the HTTP client**: Provide your own client implementation with custom configurations (e.g., baseURL, headers, interceptors)
+              - **Add authentication**: Include authentication tokens or other security mechanisms in your client
+              - **Override default behavior**: Replace the default Kubb client with your own implementation
+          - title: Default behavior
+            body: |
+              When `importPath` is not specified:
+
+              - If `bundle: false` (default): Uses `@kubb/plugin-client/clients/${client}` where client is either `axios` or `fetch`.
+              - If `bundle: true`: Bundles the client into `.kubb/fetch.ts`.
+          - title: Import structure
+            body: 'Generated code imports the client as a default import and the runtime types as named type imports:'
+            codeBlock:
+              lang: typescript
+              code: |-
+                /**
+                 * Generated by Kubb (https://kubb.dev/).
+                 * Do not edit manually.
+                 */
+                import client from '${client.importPath}'
+                import type { RequestConfig, ResponseErrorConfig } from '${client.importPath}'
+                // ... rest of generated file
+        important: |
+          When using `importPath` with query plugins such as `@kubb/plugin-react-query` or `@kubb/plugin-vue-query`, the generated hooks also import a `Client` type alongside `RequestConfig` and `ResponseErrorConfig` from the custom module. Your custom client module **must** export all three types — if any is missing, TypeScript will report an unresolvable import error.
+        codeBlock:
+          lang: typescript
+          title: client.ts
+          code: |
+            export type RequestConfig<TData = unknown> = {
+              url?: string
+              method: 'GET' | 'PUT' | 'PATCH' | 'POST' | 'DELETE'
+              params?: object
+              data?: TData | FormData
+              responseType?: 'arraybuffer' | 'blob' | 'document' | 'json' | 'text' | 'stream'
+              signal?: AbortSignal
+              headers?: HeadersInit
+            }
+
+            export type ResponseConfig<TData = unknown> = {
+              data: TData
+              status: number
+              statusText: string
+            }
+
+            export type ResponseErrorConfig<TError = unknown> = TError
+
+            // The Client type alias is required when using query plugins
+            export type Client = <TData, _TError = unknown, TVariables = unknown>(
+              config: RequestConfig<TVariables>
+            ) => Promise<ResponseConfig<TData>>
+
+            export const client: Client = async (config) => { /* ... */ }
+            export default client
+        examples:
+          - name: kubb.config.ts
+            files:
+              - lang: typescript
+                code: |
+                  import { defineConfig } from 'kubb'
+                  import { pluginClient } from '@kubb/plugin-client'
+
+                  export default defineConfig({
+                    // ...
+                    plugins: [
+                      pluginClient({
+                        importPath: './src/client.ts', // Path to your custom client
+                      }),
+                    ],
+                  })
+                twoslash: false
+        tip: |
+          Learn more about defining a custom client [here](https://kubb.dev/plugins/plugin-client#importpath).
+      - name: dataReturnType
+        type: "'data' | 'full'"
+        required: false
+        default: "'data'"
+        description: |
+          Return type used when calling the client.
+
+          - `'data'` returns `ResponseConfig['data']`.
+          - `'full'` returns the full `ResponseConfig`.
+        examples:
+          - name: data
+            files:
+              - lang: typescript
+                code: |
+                  export async function getPetById<TData>(
+                    petId: GetPetByIdPathParams,
+                  ): Promise<ResponseConfig<TData>['data']> {
+                    ...
+                  }
+                twoslash: false
+          - name: full
+            files:
+              - lang: typescript
+                code: |
+                  export async function getPetById<TData>(
+                    petId: GetPetByIdPathParams,
+                  ): Promise<ResponseConfig<TData>> {
+                    ...
+                  }
+                twoslash: false
+      - name: baseURL
+        type: string
+        required: false
+        description: Sets a custom base URL for all generated calls. When not set, the base URL is automatically taken from the OAS spec via the adapter (e.g. the `servers[0].url` field).
+      - name: clientType
+        type: "'function' | 'class'"
+        required: false
+        default: "'function'"
+        description: Specify whether to use function-based or class-based clients.
+        warning: |
+          This plugin is only compatible with `clientType: 'function'` (the default). If `clientType: 'class'` is detected, the plugin will automatically generate its own inline function-based client instead of importing from `@kubb/plugin-client`.
+      - name: bundle
+        type: boolean
+        required: false
+        default: 'false'
+        description: Controls whether the HTTP client runtime is copied into the generated `.kubb` directory.
+        body: |
+          - `true` adds a `.kubb/fetch.ts` file containing the selected client template (fetch or axios). Generated clients remain self-contained.
+          - `false` keeps generated clients slim by importing the shared runtime from `@kubb/plugin-client/clients/{client}`.
+          - Override this behavior by providing a custom `client.importPath`.
+  - name: paramsType
+    type: "'object' | 'inline'"
+    required: false
+    default: "'inline'"
+    description: Defines how parameters are passed to generated functions. Switch between object-style parameters and inline parameters.
+    tip: |
+      When `paramsType` is set to `'object'`, `pathParams` will also be set to `'object'`.
+    body: |
+      - `'object'` returns params and pathParams as an object.
+      - `'inline'` returns params as comma-separated params.
+    examples:
+      - name: object
+        files:
+          - lang: typescript
+            code: |
+              export async function deletePet(
+                {
+                  petId,
+                  headers,
+                }: {
+                  petId: DeletePetPathParams['petId']
+                  headers?: DeletePetHeaderParams
+                },
+                config: Partial<RequestConfig> = {},
+              ) {
+                ...
+              }
+            twoslash: false
+      - name: inline
+        files:
+          - lang: typescript
+            code: |
+              export async function deletePet(
+                petId: DeletePetPathParams['petId'],
+                headers?: DeletePetHeaderParams,
+                config: Partial<RequestConfig> = {}
+              ){
+                ...
+              }
+            twoslash: false
+  - name: paramsCasing
+    type: "'camelcase'"
+    required: false
+    description: Transform parameter names to a specific casing format for path, query, and header parameters in generated client code.
+    important: |
+      When using `paramsCasing`, ensure that `@kubb/plugin-ts` also has the same `paramsCasing` setting. This option automatically maps transformed parameter names back to their original API names in HTTP requests.
+    body: |
+      - `'camelcase'` transforms parameter names to camelCase.
+    examples:
+      - name: With paramsCasing camelcase
+        files:
+          - lang: typescript
+            code: |
+              // Function parameters use camelCase
+              export async function deletePet(
+                petId: DeletePetPathParams['petId'],  // ✓ camelCase
+                headers?: DeletePetHeaderParams,
+                config: Partial<RequestConfig> = {}
+              ) {
+                // Automatically maps back to original name for the API
+                const pet_id = petId
+
+                return fetch({
+                  method: 'DELETE',
+                  url: `/pet/${pet_id}`,  // Uses original API parameter name
+                  ...
+                })
+              }
+            twoslash: false
+      - name: Without paramsCasing
+        files:
+          - lang: typescript
+            code: |
+              // Parameters use original API naming
+              export async function deletePet(
+                pet_id: DeletePetPathParams['pet_id'],  // Original naming
+                headers?: DeletePetHeaderParams,
+                config: Partial<RequestConfig> = {}
+              ) {
+                return fetch({
+                  method: 'DELETE',
+                  url: `/pet/${pet_id}`,
+                  ...
+                })
+              }
+            twoslash: false
+    tip: |
+      The client automatically generates mapping code to convert camelCase parameter names back to the original API format. You write code with developer-friendly camelCase names, but HTTP requests use the exact parameter names from your OpenAPI specification.
+  - name: pathParamsType
+    type: "'object' | 'inline'"
+    required: false
+    default: "'inline'"
+    description: Defines how pathParams are passed to generated functions.
+    body: |
+      - `'object'` returns pathParams as an object.
+      - `'inline'` returns pathParams as comma-separated params.
+    examples:
+      - name: object
+        files:
+          - lang: typescript
+            code: |
+              export async function getPetById(
+                { petId }: GetPetByIdPathParams,
+              ) {
+                ...
+              }
+            twoslash: false
+      - name: inline
+        files:
+          - lang: typescript
+            code: |
+              export async function getPetById(
+                petId: GetPetByIdPathParams,
+              ) {
+                ...
+              }
+            twoslash: false
+  - name: parser
+    type: "'client' | 'zod'"
+    required: false
+    default: "'client'"
+    description: Parser used before returning data.
+    body: |
+      - `'zod'` uses `@kubb/plugin-zod` to parse data.
+      - `'client'` returns data without parsing.
+  - name: infinite
+    type: Infinite | false
+    required: false
+    default: 'false'
+    description: |
+      Generate an `infiniteQuery` composable for paginated queries. Pass `false` to disable.
+    typeDefinition: |
+      type Infinite = {
+        /**
+         * Specify the params key used for `pageParam`.
+         * @default `'id'`
+         */
+        queryParam: string
+        /**
+         * Which field of the data will be used, set it to undefined when no cursor is known.
+         * @deprecated Use `nextParam` and `previousParam` instead for more flexible pagination handling.
+         */
+        cursorParam?: string | undefined
+        /**
+         * Which field of the data will be used to get the cursor for the next page.
+         * Supports dot notation (e.g. 'pagination.next.id') or array path (e.g. ['pagination', 'next', 'id']) to access nested fields.
+         */
+        nextParam?: string | string[] | undefined
+        /**
+         * Which field of the data will be used to get the cursor for the previous page.
+         * Supports dot notation (e.g. 'pagination.prev.id') or array path (e.g. ['pagination', 'prev', 'id']) to access nested fields.
+         */
+        previousParam?: string | string[] | undefined
+        /**
+         * The initial value, the value of the first page.
+         * @default `0`
+         */
+        initialPageParam: unknown
+      } | false
+    properties:
+      - name: queryParam
+        type: string
+        required: false
+        default: "'id'"
+        description: Specify the params key used for `pageParam`.
+      - name: initialPageParam
+        type: unknown
+        required: false
+        default: '0'
+        description: Specify the initial page param value.
+      - name: cursorParam
+        type: string | undefined
+        required: false
+        deprecated:
+          note: '`cursorParam` is deprecated. Use `nextParam` and `previousParam` instead for more flexible pagination handling.'
+        description: Which field of the data will be used, set it to undefined when no cursor is known.
+      - name: nextParam
+        type: string | string[] | undefined
+        required: false
+        description: |
+          Which field of the data will be used to get the cursor for the next page.
+
+          Supports dot notation (e.g. `'pagination.next.id'`) or array path (e.g. `['pagination', 'next', 'id']`) to access nested fields.
+      - name: previousParam
+        type: string | string[] | undefined
+        required: false
+        description: |
+          Which field of the data will be used to get the cursor for the previous page.
+
+          Supports dot notation (e.g. `'pagination.prev.id'`) or array path (e.g. `['pagination', 'prev', 'id']`) to access nested fields.
+  - name: queryKey
+    type: '(props: { operation: Operation; schemas: OperationSchemas }) => unknown[]'
+    required: false
+    description: |
+      Customize the queryKey that will be used for the query.
+
+      The function receives an object with:
+      - `operation`: The OpenAPI operation object with methods like `getTags()`, `getOperationId()`, etc.
+      - `schemas`: An object containing operation schemas including `pathParams`, `queryParams`, `request`, `response`, etc.
+    warning: |
+      When using a string you need to use `JSON.stringify`.
+    details:
+      - title: Using tags and path parameters
+        body: |-
+          Generate a queryKey with operation tags and path parameters:
+
+          For a GET operation with tags `["user"]` and path parameter `username`, this generates:
+        codeBlock:
+          - lang: typescript
+            code: |-
+              import { defineConfig } from 'kubb'
+              import { pluginVueQuery } from '@kubb/plugin-vue-query'
+
+              export default defineConfig({
+                // ...
+                plugins: [
+                  pluginVueQuery({
+                    queryKey: ({ operation, schemas }) => {
+                      const tags = operation.getTags().map(tag => JSON.stringify(tag.name))
+                      const pathParams = schemas.pathParams?.keys || []
+                      return [...tags, ...pathParams]
+                    },
+                  }),
+                ],
+              })
+          - lang: typescript
+            code: |-
+              export const getUserByNameQueryKey = ({ username }: { username: GetUserByNamePathParams["username"] }) =>
+                ['user', username] as const
+      - title: Using the default transformer
+        body: |-
+          You can extend the default queryKey transformer:
+
+          This prepends a version to the default queryKey:
+        codeBlock:
+          - lang: typescript
+            code: |-
+              import { defineConfig } from 'kubb'
+              import { pluginVueQuery } from '@kubb/plugin-vue-query'
+              import { QueryKey } from '@kubb/plugin-vue-query/components'
+
+              export default defineConfig({
+                // ...
+                plugins: [
+                  pluginVueQuery({
+                    queryKey: (props) => {
+                      const defaultKeys = QueryKey.getTransformer(props)
+                      return [JSON.stringify('v5'), ...defaultKeys]
+                    },
+                  }),
+                ],
+              })
+          - lang: typescript
+            code: |-
+              export const findPetsByTagsQueryKey = (params?: FindPetsByTagsQueryParams) =>
+                ['v5', { url: '/pet/findByTags' }, ...(params ? [params] : [])] as const
+      - title: Using operation ID
+        body: 'Create a simple queryKey using the operation ID:'
+        codeBlock:
+          lang: typescript
+          code: |-
+            import { defineConfig } from 'kubb'
+            import { pluginVueQuery } from '@kubb/plugin-vue-query'
+
+            export default defineConfig({
+              // ...
+              plugins: [
+                pluginVueQuery({
+                  queryKey: ({ operation }) => {
+                    return [JSON.stringify(operation.getOperationId())]
+                  },
+                }),
+              ],
+            })
+      - title: Conditional keys based on parameters
+        body: 'Include query parameters when they exist:'
+        codeBlock:
+          lang: typescript
+          code: |-
+            import { defineConfig } from 'kubb'
+            import { pluginVueQuery } from '@kubb/plugin-vue-query'
+
+            export default defineConfig({
+              // ...
+              plugins: [
+                pluginVueQuery({
+                  queryKey: ({ operation, schemas }) => {
+                    const keys = [JSON.stringify(operation.getOperationId())]
+
+                    // Add path parameter values (without quotes, so they reference the variables)
+                    if (schemas.pathParams?.keys) {
+                      keys.push(...schemas.pathParams.keys)
+                    }
+
+                    // Add query params conditionally (the string gets embedded as code)
+                    if (schemas.queryParams?.name) {
+                      keys.push('...(params ? [params] : [])')
+                    }
+
+                    return keys
+                  },
+                }),
+              ],
+            })
+  - name: query
+    type: Query
+    required: false
+    description: |
+      Override some `useQuery` behaviors.
+
+      To disable the creation of hooks pass `false`, this will result in only creating `queryOptions`.
+    typeDefinition: |
+      type Query = {
+        methods: Array<HttpMethod>
+        importPath?: string
+      } | false
+    properties:
+      - name: methods
+        type: Array<HttpMethod>
+        required: false
+        default: "['get']"
+        description: Define which HttpMethods can be used for queries.
+      - name: importPath
+        type: string
+        required: false
+        default: "'@tanstack/vue-query'"
+        description: |
+          Path to the `useQuery` that will be used to do the `useQuery` functionality.
+
+          It will be used as `import { useQuery } from '${hook.importPath}'`. It allows both relative and absolute paths. The path will be applied as is, so relative paths should be based on the file being generated.
+  - name: mutation
+    type: Mutation
+    required: false
+    description: |
+      Override some `useMutation` behaviors.
+
+      To disable queries pass `false`.
+    typeDefinition: |
+      type Mutation = {
+        methods: Array<HttpMethod>
+        importPath?: string
+      } | false
+    properties:
+      - name: methods
+        type: Array<HttpMethod>
+        required: false
+        default: "['post', 'put', 'delete']"
+        description: Define which HttpMethods can be used for mutations.
+      - name: importPath
+        type: string
+        required: false
+        default: "'@tanstack/vue-query'"
+        description: |
+          Path to the `useMutation` that will be used to do the `useMutation` functionality.
+
+          It will be used as `import { useMutation } from '${hook.importPath}'`. It allows both relative and absolute paths. The path will be applied as is, so relative paths should be based on the file being generated.
+  - name: mutationKey
+    type: '(props: { operation: Operation; schemas: OperationSchemas }) => unknown[]'
+    required: false
+    description: Customize the mutationKey.
+    warning: |
+      When using a string you need to use `JSON.stringify`.
+  - name: include
+    type: Array<Include>
+    required: false
+    description: Array containing include parameters to include tags, operations, methods, paths, or content types.
+    codeBlock:
+      lang: typescript
+      title: Include
+      code: |
+        export type Include = {
+          type: 'tag' | 'operationId' | 'path' | 'method' | 'contentType'
+          pattern: string | RegExp
+        }
+  - name: exclude
+    type: Array<Exclude>
+    required: false
+    description: Array containing exclude parameters to exclude or skip tags, operations, methods, paths, or content types.
+    codeBlock:
+      lang: typescript
+      title: Exclude
+      code: |
+        export type Exclude = {
+          type: 'tag' | 'operationId' | 'path' | 'method' | 'contentType'
+          pattern: string | RegExp
+        }
+  - name: override
+    type: Array<Override>
+    required: false
+    description: Array containing override parameters to override `options` based on tags, operations, methods, paths, or content types.
+    codeBlock:
+      lang: typescript
+      title: Override
+      code: |
+        export type Override = {
+          type: 'tag' | 'operationId' | 'path' | 'method' | 'contentType'
+          pattern: string | RegExp
+          options: PluginOptions
+        }
+  - name: generators
+    type: Array<Generator<PluginVueQuery>>
+    required: false
+    experimental: true
+    description: |
+      Define additional generators next to the built-in generators.
+
+      See [Generators](https://kubb.dev/docs/5.x/guides/creating-plugins) for more information on how to use generators.
+  - name: resolver
+    type: Partial<ResolverVueQuery>
+    required: false
+    description: Override individual resolver methods to customize naming conventions.
+  - name: transformer
+    type: ast.Visitor
+    required: false
+    description: Single AST visitor applied to each node before printing.
+examples:
+  - name: kubb.config.ts
+    files:
+      - lang: typescript
+        code: |
+          import { defineConfig } from 'kubb'
+          import { pluginTs } from '@kubb/plugin-ts'
+          import { pluginVueQuery } from '@kubb/plugin-vue-query'
+
+          export default defineConfig({
+            input: {
+              path: './petStore.yaml',
+            },
+            output: {
+              path: './src/gen',
+            },
+            plugins: [
+              pluginTs(),
+              pluginVueQuery({
+                output: {
+                  path: './hooks',
+                },
+                group: {
+                  type: 'tag',
+                  name: ({ group }) => `${group}Hooks`,
+                },
+                client: {
+                  dataReturnType: 'full',
+                },
+                mutation: {
+                  methods: ['post', 'put', 'delete'],
+                },
+                infinite: {
+                  queryParam: 'next_page',
+                  initialPageParam: 0,
+                  cursorParam: 'nextCursor',
+                },
+                query: {
+                  methods: ['get'],
+                  importPath: '@tanstack/vue-query',
+                },
+              }),
+            ],
+          })
+        twoslash: false