@kubb/plugin-vue-query 5.0.0-beta.64 → 5.0.0-beta.73

package/dist/index.d.ts

@@ -1,6 +1,433 @@
-import { t as __name } from "./chunk-C0LytTxp.js";
-import { n as Options, r as PluginVueQuery } from "./types-C6a_58nb.js";
-
+import { t as __name } from "./rolldown-runtime-C0LytTxp.js";
+import { Exclude, Group, Include, Output, OutputOptions, Override, PluginFactoryOptions, Resolver, ast } from "@kubb/core";
+//#region ../../internals/client/src/types.d.ts
+/**
+ * Validator applied to request and response bodies using schemas from `@kubb/plugin-zod`.
+ * - `false`: no validation.
+ * - `'zod'`: validates success (2xx) response bodies only.
+ * - `{ request?: 'zod'; response?: 'zod' }`: opt in per direction. `request` validates the request
+ *   body and query parameters before the call; `response` validates the success response body.
+ */
+type ParserOptions = false | 'zod' | {
+  request?: 'zod';
+  response?: 'zod';
+};
+/**
+ * How the class-based SDK groups operations.
+ * - `'tag'`: one class per tag, optionally composed into a root client.
+ * - `'flat'`: one class with every operation as a direct method.
+ */
+type Mode = 'tag' | 'flat';
+/**
+ * The resolver shared by the client plugins. Functions and files use camelCase; URL helpers get
+ * a `get<Operation>Url` name.
+ */
+type ResolverClient = Resolver & {
+  /**
+   * Resolves the function name for a raw operation name.
+   *
+   * @example
+   * `resolver.resolveName('show pet by id') // -> 'showPetById'`
+   */
+  resolveName(this: ResolverClient, name: string): string;
+  /**
+   * Resolves the output file name for a generated client module.
+   */
+  resolvePathName(this: ResolverClient, name: string, type?: 'file' | 'function' | 'type' | 'const'): string;
+  /**
+   * Resolves the generated class name for class-based clients.
+   */
+  resolveClassName(this: ResolverClient, name: string): string;
+  /**
+   * Resolves the generated class name for a tag-based client group. The default appends a
+   * `Client` suffix (tag `pet` becomes `PetClient`) so the class never collides with the schema
+   * model of the same name in the barrel.
+   *
+   * @example
+   * `resolver.resolveGroupName('pet') // -> 'PetClient'`
+   */
+  resolveGroupName(this: ResolverClient, name: string): string;
+  /**
+   * Resolves the property name a tag client is exposed under on the composed root SDK
+   * (`new PetStore(config).pet`).
+   */
+  resolveClientPropertyName(this: ResolverClient, name: string): string;
+};
+/**
+ * The shared options surface for the client plugins. Deliberately small: there is one
+ * response contract and one grouped options object. Each plugin extends this with its own
+ * `transport` field.
+ */
+type Options$1 = OutputOptions & {
+  /**
+   * Skip operations matching at least one entry in the list.
+   */
+  exclude?: Array<Exclude>;
+  /**
+   * Restrict generation to operations matching at least one entry in the list.
+   */
+  include?: Array<Include>;
+  /**
+   * Apply a different options object to operations matching a pattern.
+   */
+  override?: Array<Override<ResolvedOptions$1>>;
+  /**
+   * Base URL prepended to every request. When omitted, falls back to the adapter's server URL.
+   */
+  baseURL?: string;
+  /**
+   * Validate request and response bodies with schemas from `@kubb/plugin-zod`.
+   *
+   * @default false
+   */
+  parser?: ParserOptions;
+  /**
+   * Generates a class-based SDK instead of the standalone functions. Each tag client is an instance
+   * class whose constructor takes a client config and builds its own client, so every environment is
+   * a separate instance. Leave `sdk` unset to keep the standalone per-operation functions (the
+   * default), which is also what query plugins consume.
+   *
+   * @example Instance class per tag
+   * ```ts
+   * pluginFetch({ sdk: {} })
+   * // const api = new PetClient({ baseURL: 'https://api.example.com' })
+   * // await api.getPetById({ path: { petId: 1 } })
+   * ```
+   * @example Composed root that instantiates every tag client from one config
+   * ```ts
+   * pluginFetch({ sdk: { name: 'petStore' } })
+   * // class PetStore {
+   * //   readonly pet: PetClient
+   * //   readonly store: StoreClient
+   * //   constructor(config = {}) { ... }
+   * // }
+   * // const api = new PetStore({ baseURL })
+   * // await api.pet.getPetById({ path: { petId: 1 } })
+   * ```
+   * @example Flat class with every operation as a direct method
+   * ```ts
+   * pluginFetch({ sdk: { name: 'petStore', mode: 'flat' } })
+   * // const api = new PetStore({ baseURL })
+   * // await api.getPetById({ path: { petId: 1 } })
+   * ```
+   */
+  sdk?: {
+    /**
+     * How the SDK groups operations.
+     * - `'tag'`: one class per tag. With `name`, a composed root instantiates every tag client.
+     * - `'flat'`: one class named by `name`, with every operation as a direct method.
+     *
+     * @default 'tag'
+     */
+    mode?: Mode;
+    /**
+     * Name of the generated entry point, also the file name. With `mode: 'tag'` it emits a
+     * composed root class that instantiates every tag client from one shared config. With
+     * `mode: 'flat'` it names the single class.
+     */
+    name?: string;
+  };
+  /**
+   * Override how names and file paths are built. Methods you omit fall back to the default resolver.
+   */
+  resolver?: Partial<ResolverClient> & ThisType<ResolverClient>;
+  /**
+   * Macros applied to each operation node before code is printed.
+   */
+  macros?: Array<ast.Macro>;
+};
+/**
+ * The resolved options after defaults are applied.
+ */
+type ResolvedOptions$1 = {
+  output: Output;
+  exclude: Array<Exclude>;
+  include: Array<Include> | undefined;
+  override: Array<Override<ResolvedOptions$1>>;
+  group: Group | null;
+  baseURL: Options$1['baseURL'];
+  parser: NonNullable<Options$1['parser']>;
+  sdk: {
+    mode: Mode;
+    name: string | undefined;
+  } | undefined;
+  resolver: ResolverClient;
+};
+//#endregion
+//#region ../../internals/client/src/resolveClient.d.ts
+/**
+ * Resolves which client plugin a consumer (react-query, vue-query, swr, mcp) should call for an
+ * operation, shared so the selection rules and diagnostics stay in one place.
+ *
+ * Every client runtime lives in a dedicated client plugin, so a consumer always calls a registered
+ * contract client plugin (plugin-fetch or plugin-axios) and never emits its own inline client:
+ *
+ * - `contract` — a registered contract client plugin owns the `<op>` functions and the consumer
+ *   imports and calls them.
+ * - `error` — no client plugin is registered, several are registered without a selector, or the
+ *   requested one is missing.
+ *
+ * The `client` string selects explicitly (`'fetch'` / `'axios'`); when it is unset a lone registered
+ * contract client plugin is picked up automatically.
+ */
+/**
+ * The client selector accepted by a consumer's `client` option. Both call a registered contract
+ * client plugin.
+ */
+type ClientSelector = 'fetch' | 'axios';
+//#endregion
+//#region src/types.d.ts
+type Transformer = (props: {
+  node: ast.OperationNode;
+  casing: 'camelcase' | undefined;
+}) => Array<unknown>;
+/**
+ * Resolver for Vue Query that provides naming methods for hook functions.
+ */
+type ResolverVueQuery = Resolver & {
+  /**
+   * Resolves the base function name for an operation.
+   */
+  resolveName(this: ResolverVueQuery, name: string): string;
+  /**
+   * Resolves the output file name for a hook module.
+   */
+  resolvePathName(this: ResolverVueQuery, name: string, type?: 'file' | 'function' | 'type' | 'const'): string;
+  /**
+   * Resolves a query hook function name.
+   */
+  resolveQueryName(this: ResolverVueQuery, node: ast.OperationNode): string;
+  /**
+   * Resolves an infinite query hook function name.
+   */
+  resolveInfiniteQueryName(this: ResolverVueQuery, node: ast.OperationNode): string;
+  /**
+   * Resolves a mutation hook function name.
+   */
+  resolveMutationName(this: ResolverVueQuery, node: ast.OperationNode): string;
+  /**
+   * Resolves the query options helper name.
+   */
+  resolveQueryOptionsName(this: ResolverVueQuery, node: ast.OperationNode): string;
+  /**
+   * Resolves the infinite query options helper name.
+   */
+  resolveInfiniteQueryOptionsName(this: ResolverVueQuery, node: ast.OperationNode): string;
+  /**
+   * Resolves the query key helper name.
+   */
+  resolveQueryKeyName(this: ResolverVueQuery, node: ast.OperationNode): string;
+  /**
+   * Resolves the infinite query key helper name.
+   */
+  resolveInfiniteQueryKeyName(this: ResolverVueQuery, node: ast.OperationNode): string;
+  /**
+   * Resolves the mutation key helper name.
+   */
+  resolveMutationKeyName(this: ResolverVueQuery, node: ast.OperationNode): string;
+  /**
+   * Resolves the query key type name.
+   */
+  resolveQueryKeyTypeName(this: ResolverVueQuery, node: ast.OperationNode): string;
+  /**
+   * Resolves the infinite query key type name.
+   */
+  resolveInfiniteQueryKeyTypeName(this: ResolverVueQuery, node: ast.OperationNode): string;
+  /**
+   * Resolves the mutation type name.
+   */
+  resolveMutationTypeName(this: ResolverVueQuery, node: ast.OperationNode): string;
+  /**
+   * Resolves the client function name generated inline by query hooks.
+   */
+  resolveClientName(this: ResolverVueQuery, node: ast.OperationNode): string;
+  /**
+   * Resolves the client function name generated inline by infinite query hooks.
+   */
+  resolveInfiniteClientName(this: ResolverVueQuery, node: ast.OperationNode): string;
+};
+/**
+ * Builds the `queryKey` used by each generated query composable.
+ *
+ * @note String values are inlined verbatim into generated code. Wrap literal
+ * strings in `JSON.stringify(...)`.
+ */
+type QueryKey = Transformer;
+/**
+ * Builds the `mutationKey` used by each generated mutation composable.
+ *
+ * @note String values are inlined verbatim into generated code. Wrap literal
+ * strings in `JSON.stringify(...)`.
+ */
+type MutationKey = Transformer;
+type Query = {
+  /**
+   * HTTP methods treated as queries.
+   *
+   * @default ['get']
+   */
+  methods?: Array<string>;
+  /**
+   * Module specifier used in the `import { useQuery } from '...'` statement at
+   * the top of every generated composable file.
+   *
+   * @default '@tanstack/vue-query'
+   */
+  importPath?: string;
+};
+type Mutation = {
+  /**
+   * HTTP methods treated as mutations.
+   *
+   * @default ['post', 'put', 'delete']
+   */
+  methods?: Array<string>;
+  /**
+   * Module specifier used in the `import { useMutation } from '...'` statement
+   * at the top of every generated composable file.
+   *
+   * @default '@tanstack/vue-query'
+   */
+  importPath?: string;
+};
+type Infinite = {
+  /**
+   * Name of the query parameter that holds the page cursor.
+   *
+   * @default 'id'
+   */
+  queryParam?: string;
+  /**
+   * Path to the cursor field on the response. Leave undefined when the cursor
+   * is not known.
+   *
+   * @deprecated Use `nextParam` and `previousParam` for richer pagination control.
+   */
+  cursorParam?: string | null;
+  /**
+   * Path to the next-page cursor on the response. Supports dot notation
+   * (`'pagination.next.id'`) or array form.
+   */
+  nextParam?: string | Array<string> | null;
+  /**
+   * Path to the previous-page cursor on the response. Supports dot notation
+   * or array form.
+   */
+  previousParam?: string | Array<string> | null;
+  /**
+   * Initial value for `pageParam` on the first fetch.
+   *
+   * @default 0
+   */
+  initialPageParam?: unknown;
+};
+/**
+ * Where the generated composables are written and how they are exported, plus the optional
+ * `group` strategy. The `group` option organizes `output.mode: 'directory'` output into per-tag or per-path subdirectories.
+ *
+ * @default { path: 'hooks', barrel: { type: 'named' } }
+ */
+type Options = OutputOptions & {
+  /**
+   * Selects the HTTP client the generated composables call. Every client plugin speaks the `RequestResult`
+   * contract, so the composables call a contract `<op>` that takes one grouped `options` object.
+   *
+   * - `'fetch'` / `'axios'` calls the `@kubb/plugin-fetch` / `@kubb/plugin-axios` functions. When a
+   *   single client plugin (plugin-fetch or plugin-axios) is registered it is
+   *   auto-detected, so the string is only needed to disambiguate several client plugins.
+   *
+   * A client plugin must be registered. The composables always call its `<op>`.
+   */
+  client?: ClientSelector;
+  /**
+   * Skip operations matching at least one entry in the list.
+   */
+  exclude?: Array<Exclude>;
+  /**
+   * Restrict generation to operations matching at least one entry in the list.
+   */
+  include?: Array<Include>;
+  /**
+   * Apply a different options object to operations matching a pattern.
+   */
+  override?: Array<Override<ResolvedOptions>>;
+  /**
+   * Enables `useInfiniteQuery` composables for cursor- or page-based pagination.
+   * Pass an object to configure how the cursor is read; pass `false` to skip.
+   *
+   * @default false
+   */
+  infinite?: Partial<Infinite> | false;
+  /**
+   * Custom `queryKey` builder.
+   */
+  queryKey?: QueryKey;
+  /**
+   * Configures query composables. Set to `false` to skip composable generation
+   * and emit only `queryOptions(...)` helpers.
+   */
+  query?: Partial<Query> | false;
+  /**
+   * Custom `mutationKey` builder.
+   */
+  mutationKey?: MutationKey;
+  /**
+   * Configures mutation composables. Set to `false` to skip mutation generation.
+   */
+  mutation?: Partial<Mutation> | false;
+  /**
+   * Validator applied to response bodies before they reach the caller.
+   * - `'client'` — no validation.
+   * - `'zod'` — pipes responses through schemas from `@kubb/plugin-zod`.
+   */
+  parser?: Options$1['parser'];
+  /**
+   * Override how composable names and file paths are built.
+   */
+  resolver?: Partial<ResolverVueQuery> & ThisType<ResolverVueQuery>;
+  /**
+   * Macros applied to each operation node before printing.
+   */
+  macros?: Array<ast.Macro>;
+};
+/**
+ * The resolved client strategy for the generated composables, computed once during setup. The
+ * composables always import and call a registered contract client plugin's `<op>`.
+ */
+type ResolvedClient = {
+  kind: 'contract';
+  pluginName: string;
+};
+type ResolvedOptions = {
+  output: Output;
+  group: Group | null;
+  exclude: NonNullable<Options['exclude']>;
+  include: Options['include'];
+  override: NonNullable<Options['override']>;
+  /**
+   * The resolved contract client the generators import and call.
+   */
+  client: ResolvedClient;
+  parser: NonNullable<Options['parser']>;
+  /**
+   * Only used for infinite
+   */
+  infinite: NonNullable<Infinite> | false;
+  queryKey: QueryKey | null;
+  query: NonNullable<Required<Query>> | false;
+  mutationKey: MutationKey | null;
+  mutation: NonNullable<Required<Mutation>> | false;
+  resolver: ResolverVueQuery;
+};
+type PluginVueQuery = PluginFactoryOptions<'plugin-vue-query', Options, ResolvedOptions, ResolverVueQuery>;
+declare global {
+  namespace Kubb {
+    interface PluginRegistry {
+      'plugin-vue-query': PluginVueQuery;
+    }
+  }
+}
+//#endregion
 //#region src/plugin.d.ts
 /**
  * Canonical plugin name for `@kubb/plugin-vue-query`. Used for driver lookups