@kubb/plugin-react-query 5.0.0-beta.4 → 5.0.0-beta.56

package/dist/types-X7D0NSvJ.d.ts

@@ -0,0 +1,396 @@
+import { t as __name } from "./chunk-C0LytTxp.js";
+import { Exclude, Generator, Group, Include, Output, OutputOptions, Override, PluginFactoryOptions, Resolver, ast } from "@kubb/core";
+import { ClientImportPath, PluginClient } from "@kubb/plugin-client";
+import { PluginTs, ResolverTs } from "@kubb/plugin-ts";
+import { KubbReactNode } from "@kubb/renderer-jsx/types";
+
+//#region ../../internals/tanstack-query/src/types.d.ts
+type ParamsCasing = 'camelcase' | undefined;
+type Transformer = (props: {
+  node: ast.OperationNode;
+  casing: ParamsCasing;
+}) => unknown[];
+//#endregion
+//#region ../../internals/tanstack-query/src/components/MutationKey.d.ts
+type Props$1 = {
+  name: string;
+  node: ast.OperationNode;
+  paramsCasing: 'camelcase' | undefined;
+  pathParamsType: 'object' | 'inline';
+  transformer: Transformer | null | undefined;
+};
+declare function MutationKey$1({
+  name,
+  paramsCasing,
+  node,
+  transformer
+}: Props$1): KubbReactNode;
+//#endregion
+//#region ../../internals/tanstack-query/src/components/QueryKey.d.ts
+type Props = {
+  name: string;
+  typeName: string;
+  node: ast.OperationNode;
+  tsResolver: PluginTs['resolver'];
+  paramsCasing: 'camelcase' | undefined;
+  pathParamsType: 'object' | 'inline';
+  transformer: Transformer | null | undefined;
+};
+declare function QueryKey$1({
+  name,
+  node,
+  tsResolver,
+  paramsCasing,
+  pathParamsType,
+  typeName,
+  transformer
+}: Props): KubbReactNode;
+//#endregion
+//#region src/types.d.ts
+/**
+ * Resolver for React Query that provides naming methods for hook functions.
+ */
+type ResolverReactQuery = Resolver & {
+  /**
+   * Resolves the base function name for an operation.
+   *
+   * @example Resolving base operation names
+   * `resolver.resolveName('show pet by id') // -> 'showPetById'`
+   */
+  resolveName(this: ResolverReactQuery, name: string): string;
+  /**
+   * Resolves the output file name for a hook module.
+   */
+  resolvePathName(this: ResolverReactQuery, name: string, type?: 'file' | 'function' | 'type' | 'const'): string;
+  /**
+   * Resolves a query hook function name.
+   */
+  resolveQueryName(this: ResolverReactQuery, node: ast.OperationNode): string;
+  /**
+   * Resolves a suspense query hook function name.
+   */
+  resolveSuspenseQueryName(this: ResolverReactQuery, node: ast.OperationNode): string;
+  /**
+   * Resolves an infinite query hook function name.
+   */
+  resolveInfiniteQueryName(this: ResolverReactQuery, node: ast.OperationNode): string;
+  /**
+   * Resolves a suspense infinite query hook function name.
+   */
+  resolveSuspenseInfiniteQueryName(this: ResolverReactQuery, node: ast.OperationNode): string;
+  /**
+   * Resolves a mutation hook function name.
+   */
+  resolveMutationName(this: ResolverReactQuery, node: ast.OperationNode): string;
+  /**
+   * Resolves the query options helper name.
+   */
+  resolveQueryOptionsName(this: ResolverReactQuery, node: ast.OperationNode): string;
+  /**
+   * Resolves the suspense query options helper name.
+   */
+  resolveSuspenseQueryOptionsName(this: ResolverReactQuery, node: ast.OperationNode): string;
+  /**
+   * Resolves the infinite query options helper name.
+   */
+  resolveInfiniteQueryOptionsName(this: ResolverReactQuery, node: ast.OperationNode): string;
+  /**
+   * Resolves the suspense infinite query options helper name.
+   */
+  resolveSuspenseInfiniteQueryOptionsName(this: ResolverReactQuery, node: ast.OperationNode): string;
+  /**
+   * Resolves the mutation options helper name.
+   */
+  resolveMutationOptionsName(this: ResolverReactQuery, node: ast.OperationNode): string;
+  /**
+   * Resolves the query key helper name.
+   */
+  resolveQueryKeyName(this: ResolverReactQuery, node: ast.OperationNode): string;
+  /**
+   * Resolves the suspense query key helper name.
+   */
+  resolveSuspenseQueryKeyName(this: ResolverReactQuery, node: ast.OperationNode): string;
+  /**
+   * Resolves the infinite query key helper name.
+   */
+  resolveInfiniteQueryKeyName(this: ResolverReactQuery, node: ast.OperationNode): string;
+  /**
+   * Resolves the suspense infinite query key helper name.
+   */
+  resolveSuspenseInfiniteQueryKeyName(this: ResolverReactQuery, node: ast.OperationNode): string;
+  /**
+   * Resolves the mutation key helper name.
+   */
+  resolveMutationKeyName(this: ResolverReactQuery, node: ast.OperationNode): string;
+  /**
+   * Resolves the query key type name.
+   */
+  resolveQueryKeyTypeName(this: ResolverReactQuery, node: ast.OperationNode): string;
+  /**
+   * Resolves the suspense query key type name.
+   */
+  resolveSuspenseQueryKeyTypeName(this: ResolverReactQuery, node: ast.OperationNode): string;
+  /**
+   * Resolves the infinite query key type name.
+   */
+  resolveInfiniteQueryKeyTypeName(this: ResolverReactQuery, node: ast.OperationNode): string;
+  /**
+   * Resolves the suspense infinite query key type name.
+   */
+  resolveSuspenseInfiniteQueryKeyTypeName(this: ResolverReactQuery, node: ast.OperationNode): string;
+  /**
+   * Resolves the mutation type name.
+   */
+  resolveMutationTypeName(this: ResolverReactQuery, node: ast.OperationNode): string;
+  /**
+   * Resolves the client function name generated inline by query hooks.
+   */
+  resolveClientName(this: ResolverReactQuery, node: ast.OperationNode): string;
+  /**
+   * Resolves the client function name generated inline by suspense query hooks.
+   */
+  resolveSuspenseClientName(this: ResolverReactQuery, node: ast.OperationNode): string;
+  /**
+   * Resolves the client function name generated inline by infinite query hooks.
+   */
+  resolveInfiniteClientName(this: ResolverReactQuery, node: ast.OperationNode): string;
+  /**
+   * Resolves the client function name generated inline by suspense infinite query hooks.
+   */
+  resolveSuspenseInfiniteClientName(this: ResolverReactQuery, node: ast.OperationNode): string;
+  /**
+   * Resolves the generated custom hook options map type name.
+   */
+  resolveHookOptionsName(this: ResolverReactQuery): string;
+  /**
+   * Resolves the helper function name used inside the custom hook options file.
+   */
+  resolveCustomHookOptionsName(this: ResolverReactQuery): string;
+};
+type Suspense = object;
+/**
+ * Builds the `queryKey` used by each generated query hook.
+ *
+ * @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 hook.
+ *
+ * @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. Operations using these methods produce
+   * `useQuery`-style hooks.
+   *
+   * @default ['get']
+   */
+  methods?: Array<string>;
+  /**
+   * Module specifier used in the `import { useQuery } from '...'` statement at
+   * the top of every generated hook file. Useful for routing through a wrapper
+   * that injects a default `queryClient`.
+   *
+   * @default '@tanstack/react-query'
+   */
+  importPath?: string;
+};
+type Mutation = {
+  /**
+   * HTTP methods treated as mutations. Operations using these methods produce
+   * `useMutation`-style hooks.
+   *
+   * @default ['post', 'put', 'delete']
+   */
+  methods?: Array<string>;
+  /**
+   * Module specifier used in the `import { useMutation } from '...'` statement
+   * at the top of every generated hook file.
+   *
+   * @default '@tanstack/react-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 (`['pagination', 'next', 'id']`).
+   */
+  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;
+};
+type CustomOptions = {
+  /**
+   * Module specifier of your custom-options hook. Imported as
+   * `import ${name} from '${importPath}'`.
+   */
+  importPath: string;
+  /**
+   * Exported function name of your custom-options hook.
+   *
+   * @default 'useCustomHookOptions'
+   */
+  name?: string;
+};
+/**
+ * Where the generated hooks 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 & {
+  /**
+   * HTTP client used inside every generated hook. Mirrors a subset of
+   * `pluginClient` options.
+   */
+  client?: ClientImportPath & Pick<PluginClient['options'], 'clientType' | 'dataReturnType' | 'baseURL' | 'bundle' | 'paramsCasing'>;
+  /**
+   * 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>>;
+  /**
+   * Rename parameter properties in the generated hooks.
+   *
+   * @note Must match the value of `paramsCasing` on `@kubb/plugin-ts`.
+   */
+  paramsCasing?: 'camelcase';
+  /**
+   * How operation parameters appear in the generated hook signature.
+   * - `'inline'` — positional arguments.
+   * - `'object'` — single destructured object argument.
+   *
+   * @default 'inline'
+   */
+  paramsType?: 'object' | 'inline';
+  /**
+   * How URL path parameters are arranged inside the inline argument list.
+   *
+   * @default 'inline'
+   */
+  pathParamsType?: PluginClient['options']['pathParamsType'];
+  /**
+   * Enables `useInfiniteQuery` hooks 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;
+  /**
+   * Adds `useSuspenseQuery` hooks alongside the regular `useQuery` ones.
+   * Pass an empty object (`{}`) to enable. TanStack Query v5+ only.
+   */
+  suspense?: Partial<Suspense> | false;
+  /**
+   * Custom `queryKey` builder. Use to add a version namespace, swap to
+   * operation IDs, or shape keys to match an existing invalidation strategy.
+   */
+  queryKey?: QueryKey;
+  /**
+   * Configures query hooks. Set to `false` to skip generating hooks entirely
+   * and emit only `queryOptions(...)` helpers.
+   */
+  query?: Partial<Query> | false;
+  /**
+   * Custom `mutationKey` builder. Useful when you batch invalidations or read
+   * mutation state via `useMutationState`.
+   */
+  mutationKey?: MutationKey;
+  /**
+   * Configures mutation hooks. Set to `false` to skip mutation generation.
+   */
+  mutation?: Partial<Mutation> | false;
+  /**
+   * Wires every generated hook through a user-supplied function that returns
+   * extra options (`onSuccess`, `onError`, `select`, ...). Also emits a
+   * `HookOptions` type so the wrapper stays in sync with generated hooks.
+   */
+  customOptions?: CustomOptions;
+  /**
+   * Validator applied to response bodies before they reach the caller.
+   * - `'client'` — no validation. Trusts the API.
+   * - `'zod'` — pipes responses through schemas from `@kubb/plugin-zod`.
+   */
+  parser?: PluginClient['options']['parser'];
+  /**
+   * Override how hook names and file paths are built. Methods you omit fall
+   * back to the default `resolverReactQuery`.
+   */
+  resolver?: Partial<ResolverReactQuery> & ThisType<ResolverReactQuery>;
+  /**
+   * AST visitor applied to each operation node before printing.
+   */
+  transformer?: ast.Visitor;
+  /**
+   * Custom generators that run alongside the built-in React Query generators.
+   */
+  generators?: Array<Generator<PluginReactQuery>>;
+};
+type ResolvedOptions = {
+  output: Output;
+  group: Group | null;
+  exclude: NonNullable<Options['exclude']>;
+  include: Options['include'];
+  override: NonNullable<Options['override']>;
+  client: Pick<PluginClient['options'], 'client' | 'clientType' | 'dataReturnType' | 'importPath' | 'baseURL' | 'bundle' | 'paramsCasing'>;
+  parser: NonNullable<Options['parser']>;
+  pathParamsType: NonNullable<Options['pathParamsType']>;
+  paramsCasing: Options['paramsCasing'];
+  paramsType: NonNullable<Options['paramsType']>;
+  /**
+   * Only used for infinite
+   */
+  infinite: NonNullable<Infinite> | false;
+  suspense: Suspense | false;
+  queryKey: QueryKey | null;
+  query: NonNullable<Required<Query>> | false;
+  mutationKey: MutationKey | null;
+  mutation: NonNullable<Required<Mutation>> | false;
+  customOptions: NonNullable<Required<CustomOptions>> | null;
+  resolver: ResolverReactQuery;
+};
+type PluginReactQuery = PluginFactoryOptions<'plugin-react-query', Options, ResolvedOptions, ResolverReactQuery>;
+declare global {
+  namespace Kubb {
+    interface PluginRegistry {
+      'plugin-react-query': PluginReactQuery;
+    }
+  }
+}
+//#endregion
+export { MutationKey$1 as a, QueryKey$1 as i, Options as n, PluginReactQuery as r, Infinite as t };
+//# sourceMappingURL=types-X7D0NSvJ.d.ts.map

package/package.json

@@ -1,25 +1,22 @@
 {
   "name": "@kubb/plugin-react-query",
-  "version": "5.0.0-beta.4",
-  "description": "React Query hooks generator plugin for Kubb, creating type-safe API client hooks from OpenAPI specifications for React applications.",
+  "version": "5.0.0-beta.56",
+  "description": "Generate type-safe TanStack Query (React Query) hooks from your OpenAPI specification. Covers useQuery, useMutation, useInfiniteQuery, and queryOptions with full TypeScript support.",
   "keywords": [
-    "api-client",
-    "code-generator",
+    "code-generation",
     "codegen",
     "data-fetching",
     "hooks",
     "kubb",
-    "oas",
     "openapi",
-    "plugins",
     "react",
-    "react-hooks",
     "react-query",
-    "sdk-generator",
     "swagger",
+    "tanstack",
     "tanstack-query",
-    "type-safe",
-    "typescript"
+    "typescript",
+    "use-mutation",
+    "use-query"
   ],
   "license": "MIT",
   "author": "stijnvanhulle",
@@ -31,7 +28,6 @@
   "files": [
     "src",
     "dist",
-    "extension.yaml",
     "!/**/**.test.**",
     "!/**/__tests__/**",
     "!/**/__snapshots__/**"
@@ -71,37 +67,32 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@kubb/core": "5.0.0-beta.4",
-    "@kubb/renderer-jsx": "5.0.0-beta.4",
-    "remeda": "^2.34.0",
-    "@kubb/plugin-client": "5.0.0-beta.4",
-    "@kubb/plugin-ts": "5.0.0-beta.4",
-    "@kubb/plugin-zod": "5.0.0-beta.4"
+    "@kubb/ast": "5.0.0-beta.55",
+    "@kubb/core": "5.0.0-beta.55",
+    "@kubb/renderer-jsx": "5.0.0-beta.55",
+    "@kubb/plugin-client": "5.0.0-beta.56",
+    "@kubb/plugin-ts": "5.0.0-beta.56",
+    "@kubb/plugin-zod": "5.0.0-beta.56"
   },
   "devDependencies": {
+    "@internals/shared": "0.0.0",
     "@internals/tanstack-query": "0.0.0",
     "@internals/utils": "0.0.0"
   },
   "peerDependencies": {
-    "@kubb/renderer-jsx": "5.0.0-beta.4"
+    "@kubb/renderer-jsx": "5.0.0-beta.55"
   },
-  "size-limit": [
-    {
-      "path": "./dist/*.js",
-      "limit": "510 KiB",
-      "gzip": true
-    }
-  ],
   "engines": {
     "node": ">=22"
   },
   "scripts": {
-    "build": "tsdown && size-limit",
-    "clean": "npx rimraf ./dist",
+    "build": "tsdown",
+    "clean": "node -e \"require('node:fs').rmSync('./dist', {recursive:true,force:true})\"",
     "lint": "oxlint .",
     "lint:fix": "oxlint --fix .",
     "release": "pnpm publish --no-git-check",
     "release:canary": "bash ../../.github/canary.sh && node ../../scripts/build.js canary && pnpm publish --no-git-check",
+    "release:stage": "pnpm stage publish --no-git-check",
     "start": "tsdown --watch",
     "test": "vitest --passWithNoTests",
     "typecheck": "tsc -p ./tsconfig.json --noEmit --emitDeclarationOnly false"

package/src/components/InfiniteQuery.tsx

@@ -1,11 +1,12 @@
+import { getOperationParameters } from '@internals/shared'
 import { ast } from '@kubb/core'
 import type { ResolverTs } from '@kubb/plugin-ts'
 import { functionPrinter } from '@kubb/plugin-ts'
 import { File, Function } from '@kubb/renderer-jsx'
 import type { KubbReactNode } from '@kubb/renderer-jsx/types'
 import type { Infinite, PluginReactQuery } from '../types.ts'
-import { getComments, resolveErrorNames } from '../utils.ts'
-import { QueryKey } from './QueryKey.tsx'
+import { getEnabledParamNames, markParamsOptional } from '@internals/tanstack-query'
+import { buildQueryKeyParams, buildStatusUnionType, getComments, resolveErrorNames, resolveSuccessNames } from '../utils.ts'
 import { getQueryOptionsParams } from './QueryOptions.tsx'
 
 type Props = {
@@ -27,7 +28,7 @@ type Props = {
 const declarationPrinter = functionPrinter({ mode: 'declaration' })
 const callPrinter = functionPrinter({ mode: 'call' })
 
-function getParams(
+function buildInfiniteQueryParamsNode(
   node: ast.OperationNode,
   options: {
     paramsType: PluginReactQuery['resolvedOptions']['paramsType']
@@ -39,7 +40,7 @@ function getParams(
   },
 ): ast.FunctionParametersNode {
   const { paramsType, paramsCasing, pathParamsType, resolver, pageParamGeneric } = options
-  const requestName = node.requestBody?.content?.[0]?.schema ? resolver.resolveDataName(node) : undefined
+  const requestName = node.requestBody?.content?.[0]?.schema ? resolver.resolveDataName(node) : null
 
   const optionsParam = ast.createFunctionParameter({
     name: 'options',
@@ -77,10 +78,11 @@ export function InfiniteQuery({
   queryParam,
   customOptions,
 }: Props): KubbReactNode {
-  const responseName = tsResolver.resolveResponseName(node)
+  const successNames = resolveSuccessNames(node, tsResolver)
+  const responseName = successNames.length > 0 ? successNames.join(' | ') : tsResolver.resolveResponseName(node)
   const errorNames = resolveErrorNames(node, tsResolver)
 
-  const responseType = dataReturnType === 'data' ? responseName : `ResponseConfig<${responseName}>`
+  const responseType = dataReturnType === 'data' ? responseName : buildStatusUnionType(node, tsResolver)
   const errorType = `ResponseErrorConfig<${errorNames.length > 0 ? errorNames.join(' | ') : 'Error'}>`
 
   const isInitialPageParamDefined = initialPageParam !== undefined && initialPageParam !== null
@@ -98,17 +100,17 @@ export function InfiniteQuery({
           ? 'boolean'
           : 'unknown'
 
-  const rawQueryParams = node.parameters.filter((p) => p.in === 'query')
+  const rawQueryParams = getOperationParameters(node).query
   const queryParamsTypeName =
     rawQueryParams.length > 0
       ? (() => {
           const groupName = tsResolver.resolveQueryParamsName(node, rawQueryParams[0]!)
           const individualName = tsResolver.resolveParamName(node, rawQueryParams[0]!)
-          return groupName !== individualName ? groupName : undefined
+          return groupName !== individualName ? groupName : null
         })()
-      : undefined
+      : null
 
-  const queryParamType = queryParam && queryParamsTypeName ? `${queryParamsTypeName}['${queryParam}']` : undefined
+  const queryParamType = queryParam && queryParamsTypeName ? `${queryParamsTypeName}['${queryParam}']` : null
   const pageParamType = queryParamType ? (isInitialPageParamDefined ? `NonNullable<${queryParamType}>` : queryParamType) : fallbackPageParamType
 
   const returnType = 'UseInfiniteQueryResult<TData, TError> & { queryKey: TQueryKey }'
@@ -120,13 +122,24 @@ export function InfiniteQuery({
     `TPageParam = ${pageParamType}`,
   ]
 
-  const queryKeyParamsNode = QueryKey.getParams(node, { pathParamsType, paramsCasing, resolver: tsResolver })
+  const queryKeyParamsNode = buildQueryKeyParams(node, { pathParamsType, paramsCasing, resolver: tsResolver })
   const queryKeyParamsCall = callPrinter.print(queryKeyParamsNode) ?? ''
+  const enabledNames = getEnabledParamNames(queryKeyParamsNode)
 
   const queryOptionsParamsNode = getQueryOptionsParams(node, { paramsType, paramsCasing, pathParamsType, resolver: tsResolver })
   const queryOptionsParamsCall = callPrinter.print(queryOptionsParamsNode) ?? ''
 
-  const paramsNode = getParams(node, { paramsType, paramsCasing, pathParamsType, dataReturnType, resolver: tsResolver, pageParamGeneric: 'TPageParam' })
+  const paramsNode = markParamsOptional(
+    buildInfiniteQueryParamsNode(node, {
+      paramsType,
+      paramsCasing,
+      pathParamsType,
+      dataReturnType,
+      resolver: tsResolver,
+      pageParamGeneric: 'TPageParam',
+    }),
+    enabledNames,
+  )
   const paramsSignature = declarationPrinter.print(paramsNode) ?? ''
 
   return (
@@ -135,11 +148,10 @@ export function InfiniteQuery({
         {`
        const { query: queryConfig = {}, client: config = {} } = options ?? {}
        const { client: queryClient, ...resolvedOptions } = queryConfig
-       const queryKey = resolvedOptions?.queryKey ?? ${queryKeyName}(${queryKeyParamsCall})
-       ${customOptions ? `const customOptions = ${customOptions.name}({ hookName: '${name}', operationId: '${node.operationId}' })` : ''}
+       const queryKey = resolvedOptions?.queryKey ?? ${queryKeyName}(${queryKeyParamsCall})${customOptions ? `\n       const customOptions = ${customOptions.name}({ hookName: '${name}', operationId: '${node.operationId}' })` : ''}
 
        const query = useInfiniteQuery({
-        ...${queryOptionsName}(${queryOptionsParamsCall}),${customOptions ? '\n...customOptions,' : ''}
+        ...${queryOptionsName}(${queryOptionsParamsCall}),${customOptions ? '\n        ...customOptions,' : ''}
         ...resolvedOptions,
         queryKey,
        } as unknown as InfiniteQueryObserverOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, queryClient) as ${returnType}
@@ -152,5 +164,3 @@ export function InfiniteQuery({
     </File.Source>
   )
 }
-
-InfiniteQuery.getParams = getParams