@kubb/plugin-react-query 5.9.0-canary.20261029T145027 → 5.9.0

package/dist/index.d.cts

@@ -415,6 +415,11 @@ type Options = OutputOptions & {
    * A client plugin must be registered. The hooks always call its `<op>`.
    */
   client?: ClientSelector;
+  /**
+   * Shape of the value the hooks resolve to: `'data'` is the success body, `'full'` the client's whole `RequestResult` so a hook can read response headers. `'full'` needs a client plugin whose own `returnType` is `'full'` or `'plain'`.
+   * @default 'data'
+   */
+  returnType?: 'data' | 'full';
   /**
    * Skip operations matching at least one entry in the list.
    */
@@ -502,6 +507,7 @@ type ResolvedOptions = {
    * The resolved contract client the generators import and call.
    */
   client: ResolvedClient;
+  returnType?: 'data' | 'full';
   /**
    * Resolved infinite query configuration, or `false` when infinite queries are disabled.
    */

package/dist/index.d.ts

@@ -415,6 +415,11 @@ type Options = OutputOptions & {
    * A client plugin must be registered. The hooks always call its `<op>`.
    */
   client?: ClientSelector;
+  /**
+   * Shape of the value the hooks resolve to: `'data'` is the success body, `'full'` the client's whole `RequestResult` so a hook can read response headers. `'full'` needs a client plugin whose own `returnType` is `'full'` or `'plain'`.
+   * @default 'data'
+   */
+  returnType?: 'data' | 'full';
   /**
    * Skip operations matching at least one entry in the list.
    */
@@ -502,6 +507,7 @@ type ResolvedOptions = {
    * The resolved contract client the generators import and call.
    */
   client: ResolvedClient;
+  returnType?: 'data' | 'full';
   /**
    * Resolved infinite query configuration, or `false` when infinite queries are disabled.
    */

package/dist/index.js

@@ -483,7 +483,7 @@ var compatibility = {
 	"node": ">=22.22"
 };
 // package.json
-var version = "5.9.0-canary.20261029T145027";
+var version = "5.9.0";
 // ../../internals/client/src/resolveOperationTypes.ts
 /**
 * A `plugin-ts` shaped resolver whose operation type names point at the types `pluginZod({ inferred })`
@@ -732,8 +732,16 @@ function resolveClientOperation(options) {
 * `pluginZod({ inferred: 'codec' })`), banner and footer.
 */
 function resolveHookFile(node, ctx, options) {
-	const { name, output, group, contractOp, keyTypeName, extraTypeNames = [] } = options;
+	const { name, output, group, contractOp, keyTypeName, extraTypeNames = [], returnType = "data" } = options;
 	const { config, root, resolver } = ctx;
+	if (returnType !== "data" && contractOp.returnType === "data") throw new Diagnostics.Error({
+		code: Diagnostics.code.invalidPluginOptions,
+		severity: "error",
+		message: `Option \`returnType\` is '${returnType}' for ${node.operationId}, but the client plugin has \`returnType: 'data'\` and only returns the response body.`,
+		help: "Set the client plugin's `returnType` to 'full', or set the hook plugin's `returnType` to 'data'.",
+		location: { kind: "config" },
+		plugin: resolver.pluginName
+	});
 	const types = resolveOperationTypes(ctx.driver, resolver.pluginName);
 	const tsResolver = types.resolver;
 	const file = resolver.file({
@@ -752,9 +760,10 @@ function resolveHookFile(node, ctx, options) {
 	});
 	const importedTypeNames = [
 		tsResolver.response.options(node),
+		tsResolver.response.responses(node),
 		...extraTypeNames,
 		...resolveOperationTypeNames(node, tsResolver, {
-			exclude: keyTypeName ? [keyTypeName] : void 0,
+			exclude: [keyTypeName, returnType !== "data" ? tsResolver.response.response(node) : null].filter((name) => Boolean(name)),
 			order: "body-response-first",
 			includeParams: false
 		})
@@ -769,6 +778,7 @@ function resolveHookFile(node, ctx, options) {
 		tsResolver,
 		contractOp,
 		importedTypeNames,
+		returnType,
 		banner: resolver.default.banner(ctx.meta, {
 			output,
 			config,
@@ -799,7 +809,11 @@ function HookFile({ hook, imports, children }) {
 				path: contractOp.path
 			}),
 			/* @__PURE__ */ jsx(File.Import, {
-				name: ["RequestConfig", "ResponseErrorConfig"],
+				name: [
+					"RequestConfig",
+					"ResponseErrorConfig",
+					"RequestResult"
+				],
 				root: contractOp.clientPathIsFile ? file.path : void 0,
 				path: contractOp.clientPath,
 				isTypeOnly: true
@@ -929,11 +943,12 @@ function buildClientCall(node, options) {
 }
 /**
 * Builds the query/mutation body that resolves a `buildClientCall` expression down to the bare
-* success body. `returnType` mirrors the registered client plugin's own `returnType` option: with
+* success body. `clientReturnType` mirrors the registered client plugin's own `returnType` option: with
 * `'data'` the call already resolves to the bare body, so it is returned directly; with `'full'`
 * (the default) the call carries `unwrap()`, so the body calls it instead of destructuring `data`
 * off the full result by hand. With `'plain'` (plugin-client) the call resolves to the user's
-* `RequestResult`, so the body awaits it and reads `data`.
+* `RequestResult`, so the body awaits it and reads `data`. With `returnType` `'full'` the body
+* resolves to the whole `RequestResult`; `resolveHookFile` rejects that for a client that already stripped it.
 *
 * @example
 * ```ts
@@ -942,22 +957,24 @@ function buildClientCall(node, options) {
 * ```
 */
 function buildCallResultBody(call, options = {}) {
-	const { returnType = "full" } = options;
-	if (returnType === "data") return `return await ${call}`;
-	if (returnType === "plain") return `return (await ${call}).data`;
+	const { clientReturnType = "full", returnType = "data" } = options;
+	if (returnType !== "data" || clientReturnType === "data") return `return ${call}`;
+	if (clientReturnType === "plain") return `return (await ${call}).data`;
 	return `return ${call}.unwrap()`;
 }
 /**
 * Builds the `TData` / `TError` type expressions shared by every generated hook, joining the resolved
 * success responses into `TData` and wrapping the error responses in `ResponseErrorConfig<...>`.
+* With `returnType` `'full'`, `TData` is the client's `RequestResult` over the operation's responses record.
 */
-function buildResponseTypes(node, resolver) {
-	return resolver.memo(`responseTypes:${node.method}\0${node.path}`, () => {
+function buildResponseTypes(node, resolver, options = {}) {
+	const { returnType = "data" } = options;
+	return resolver.memo(`responseTypes:${returnType}:${node.method}\0${node.path}`, () => {
 		const successNames = resolveSuccessNames(node, resolver);
 		const responseName = successNames.length > 0 ? successNames.join(" | ") : resolver.response.response(node);
 		const errorNames = resolveErrorNames(node, resolver);
 		return {
-			TData: responseName,
+			TData: returnType !== "data" ? `RequestResult<${resolver.response.responses(node)}, true>` : responseName,
 			TError: `ResponseErrorConfig<${errorNames.length > 0 ? errorNames.join(" | ") : "Error"}>`
 		};
 	});
@@ -1186,8 +1203,9 @@ function buildResolvedRequestParams(node) {
 // ../../internals/tanstack-query/src/components/InfiniteQueryOptions.tsx
 const declarationPrinter$6 = functionPrinter({ mode: "declaration" });
 const callPrinter$3 = functionPrinter({ mode: "call" });
-function InfiniteQueryOptions({ name, clientName, initialPageParam, hasExplicitInitialPageParam, cursorParam, nextParam, previousParam, getNextPageParam, getPreviousPageParam, node, tsResolver, queryParam, queryKeyName, queryKeyType = "typeof queryKey", memberTypeWrapper, unwrapName, returnType = "full" }) {
-	const { TData: queryFnDataType, TError: errorType } = buildResponseTypes(node, tsResolver);
+function InfiniteQueryOptions({ name, clientName, initialPageParam, hasExplicitInitialPageParam, cursorParam, nextParam, previousParam, getNextPageParam, getPreviousPageParam, node, tsResolver, queryParam, queryKeyName, queryKeyType = "typeof queryKey", memberTypeWrapper, unwrapName, clientReturnType, returnType }) {
+	const { TData: queryFnDataType, TError: errorType } = buildResponseTypes(node, tsResolver, { returnType });
+	const dataSuffix = returnType === "data" ? "" : ".data";
 	const { queryParamsTypeName, pageParamType } = resolvePageParamType(node, {
 		resolver: tsResolver,
 		initialPageParam,
@@ -1209,21 +1227,24 @@ function InfiniteQueryOptions({ name, clientName, initialPageParam, hasExplicitI
 		clientName,
 		signal: true,
 		unwrapName
-	}), { returnType });
+	}), {
+		clientReturnType,
+		returnType
+	});
 	const initialPageParamLiteral = typeof initialPageParam === "string" || typeof initialPageParam === "object" && initialPageParam !== null ? JSON.stringify(initialPageParam) : String(initialPageParam === void 0 ? 0 : initialPageParam);
 	const serializedGetNextPageParam = typeof getNextPageParam === "function" ? getNextPageParam.toString() : getNextPageParam;
 	const getNextPageParamExpr = (() => {
 		if (serializedGetNextPageParam) return `getNextPageParam: ${serializedGetNextPageParam}`;
-		if (nextParam) return `getNextPageParam: (lastPage) => ${getNestedAccessor(nextParam, "lastPage")}`;
-		if (cursorParam) return `getNextPageParam: (lastPage) => lastPage['${cursorParam}']`;
-		return "getNextPageParam: (lastPage, _allPages, lastPageParam) => Array.isArray(lastPage) && lastPage.length === 0 ? undefined : lastPageParam + 1";
+		if (nextParam) return `getNextPageParam: (lastPage) => ${getNestedAccessor(nextParam, `lastPage${dataSuffix}`)}`;
+		if (cursorParam) return `getNextPageParam: (lastPage) => lastPage${dataSuffix}['${cursorParam}']`;
+		return `getNextPageParam: (lastPage, _allPages, lastPageParam) => Array.isArray(lastPage${dataSuffix}) && lastPage${dataSuffix}.length === 0 ? undefined : lastPageParam + 1`;
 	})();
 	const serializedGetPreviousPageParam = typeof getPreviousPageParam === "function" ? getPreviousPageParam.toString() : getPreviousPageParam;
 	const defaultPreviousThreshold = hasExplicitInitialPageParam ? initialPageParamLiteral : "1";
 	const getPreviousPageParamExpr = (() => {
 		if (serializedGetPreviousPageParam) return `getPreviousPageParam: ${serializedGetPreviousPageParam}`;
-		if (previousParam) return `getPreviousPageParam: (firstPage) => ${getNestedAccessor(previousParam, "firstPage")}`;
-		if (cursorParam) return `getPreviousPageParam: (firstPage) => firstPage['${cursorParam}']`;
+		if (previousParam) return `getPreviousPageParam: (firstPage) => ${getNestedAccessor(previousParam, `firstPage${dataSuffix}`)}`;
+		if (cursorParam) return `getPreviousPageParam: (firstPage) => firstPage${dataSuffix}['${cursorParam}']`;
 		if (serializedGetNextPageParam || nextParam) return null;
 		return `getPreviousPageParam: (_firstPage, _allPages, firstPageParam) => firstPageParam <= ${defaultPreviousThreshold} ? undefined : firstPageParam - 1`;
 	})();
@@ -1663,7 +1684,7 @@ function buildHookTypes({ node, tsResolver, infinite, suspense, TData, TError, q
 				`TPageParam = ${pageParamType}`
 			],
 			observerOptionsType: `${observerOptionsName}<TQueryFnData, TError, TData, TQueryKey, TPageParam>`,
-			returnType: `${resultTypeName}<TData, TError> & { queryKey: TQueryKey }`
+			resultType: `${resultTypeName}<TData, TError> & { queryKey: TQueryKey }`
 		};
 	}
 	return {
@@ -1684,15 +1705,15 @@ function buildHookTypes({ node, tsResolver, infinite, suspense, TData, TError, q
 			"TQueryData",
 			"TQueryKey"
 		]).join(", ")}>`,
-		returnType: `${resultTypeName}<TData, ${TError}> & { queryKey: TQueryKey }`
+		resultType: `${resultTypeName}<TData, ${TError}> & { queryKey: TQueryKey }`
 	};
 }
-function Query({ name, queryKeyTypeName, queryOptionsName, queryKeyName, node, tsResolver, customOptions, suspense, infinite }) {
-	const { TData, TError } = buildResponseTypes(node, tsResolver);
+function Query({ name, queryKeyTypeName, queryOptionsName, queryKeyName, node, tsResolver, customOptions, suspense, infinite, returnType }) {
+	const { TData, TError } = buildResponseTypes(node, tsResolver, { returnType });
 	const prefix = suspense ? "UseSuspense" : "Use";
 	const hookName = `${suspense ? "useSuspense" : "use"}${infinite ? "InfiniteQuery" : "Query"}`;
 	const observerOptionsName = OBSERVER_OPTIONS_NAMES[infinite ? "infinite" : "plain"][suspense ? "suspense" : "standard"];
-	const { generics, observerOptionsType, returnType } = buildHookTypes({
+	const { generics, observerOptionsType, resultType } = buildHookTypes({
 		node,
 		tsResolver,
 		infinite,
@@ -1736,7 +1757,7 @@ function Query({ name, queryKeyTypeName, queryOptionsName, queryKeyName, node, t
         ...${queryOptionsName}(${queryOptionsArgs}),${customOptions ? "\n        ...customOptions," : ""}
         ...resolvedOptions,
         queryKey,
-       } as unknown as ${castType}, queryClient) as ${returnType}
+       } as unknown as ${castType}, queryClient) as ${resultType}
 
        queryResult.queryKey = queryKey as TQueryKey
 
@@ -1748,8 +1769,8 @@ function Query({ name, queryKeyTypeName, queryOptionsName, queryKeyName, node, t
 // src/components/QueryOptions.tsx
 const declarationPrinter$2 = functionPrinter({ mode: "declaration" });
 const callPrinter$2 = functionPrinter({ mode: "call" });
-function QueryOptions({ name, clientName, node, tsResolver, queryKeyName, returnType = "full" }) {
-	const { TData, TError } = buildResponseTypes(node, tsResolver);
+function QueryOptions({ name, clientName, node, tsResolver, queryKeyName, clientReturnType, returnType }) {
+	const { TData, TError } = buildResponseTypes(node, tsResolver, { returnType });
 	const queryKeyParamsNode = buildQueryKeyParams(node, { resolver: tsResolver });
 	const queryKeyParamsCall = callPrinter$2.print(queryKeyParamsNode) ?? "";
 	const paramsNode = buildQueryOptionsParams(node, { resolver: tsResolver });
@@ -1757,7 +1778,10 @@ function QueryOptions({ name, clientName, node, tsResolver, queryKeyName, return
 	const queryFnBody = buildCallResultBody(buildClientCall(node, {
 		clientName,
 		signal: true
-	}), { returnType });
+	}), {
+		clientReturnType,
+		returnType
+	});
 	return /* @__PURE__ */ jsx(File.Source, {
 		name,
 		isExportable: true,
@@ -1844,6 +1868,7 @@ function createQueryGenerator({ name, variant }) {
 				output,
 				group,
 				contractOp,
+				returnType: ctx.options.returnType,
 				keyTypeName: queryKeyTypeName,
 				extraTypeNames: infiniteOptions ? [resolvePageParamType(node, {
 					resolver: tsResolver,
@@ -1890,7 +1915,8 @@ function createQueryGenerator({ name, variant }) {
 							initialPageParam: infiniteOptions.initialPageParam,
 							hasExplicitInitialPageParam: infiniteOptions.hasExplicitInitialPageParam,
 							queryParam: infiniteOptions.queryParam,
-							returnType: contractOp.returnType
+							clientReturnType: contractOp.returnType,
+							returnType: hook.returnType
 						})
 					] }) : /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(File.Import, {
 						name: ["queryOptions"],
@@ -1901,7 +1927,8 @@ function createQueryGenerator({ name, variant }) {
 						queryKeyName,
 						node,
 						tsResolver: hook.tsResolver,
-						returnType: contractOp.returnType
+						clientReturnType: contractOp.returnType,
+						returnType: hook.returnType
 					})] }),
 					(variant !== "query" || query && hooks) && /* @__PURE__ */ jsxs(Fragment, { children: [
 						/* @__PURE__ */ jsx(File.Import, {
@@ -1925,6 +1952,7 @@ function createQueryGenerator({ name, variant }) {
 							node,
 							tsResolver: hook.tsResolver,
 							customOptions,
+							returnType: hook.returnType,
 							suspense,
 							infinite: infiniteOptions ? {
 								initialPageParam: infiniteOptions.initialPageParam,
@@ -1959,8 +1987,8 @@ function buildMutationConfigParamsNode(node) {
 		default: "{}"
 	})] });
 }
-function MutationOptions({ name, clientName, node, tsResolver, mutationKeyName, returnType = "full" }) {
-	const { TData, TError } = buildResponseTypes(node, tsResolver);
+function MutationOptions({ name, clientName, node, tsResolver, mutationKeyName, clientReturnType, returnType }) {
+	const { TData, TError } = buildResponseTypes(node, tsResolver, { returnType });
 	const configParamsNode = buildMutationConfigParamsNode(node);
 	const paramsSignature = declarationPrinter$1.print(configParamsNode) ?? "";
 	const groupedParam = buildGroupedRequestParam(node, {
@@ -1975,8 +2003,11 @@ function MutationOptions({ name, clientName, node, tsResolver, mutationKeyName,
 		clientName,
 		signal: false,
 		withContentType: true,
+		returnType: clientReturnType
+	}), {
+		clientReturnType,
 		returnType
-	}), { returnType });
+	});
 	return /* @__PURE__ */ jsx(File.Source, {
 		name,
 		isExportable: true,
@@ -2002,8 +2033,8 @@ function MutationOptions({ name, clientName, node, tsResolver, mutationKeyName,
 const declarationPrinter = functionPrinter({ mode: "declaration" });
 const callPrinter = functionPrinter({ mode: "call" });
 function buildMutationParamsNode(node, options) {
-	const { resolver } = options;
-	const { TData, TError } = buildResponseTypes(node, resolver);
+	const { resolver, returnType } = options;
+	const { TData, TError } = buildResponseTypes(node, resolver, { returnType });
 	return buildHookParams(node, {
 		resolver,
 		withRequest: false,
@@ -2018,18 +2049,21 @@ function buildMutationParamsNode(node, options) {
 }`
 	});
 }
-function Mutation({ name, mutationOptionsName, node, tsResolver, mutationKeyName, customOptions }) {
-	const { TData, TError } = buildResponseTypes(node, tsResolver);
+function Mutation({ name, mutationOptionsName, node, tsResolver, mutationKeyName, customOptions, returnType }) {
+	const { TData, TError } = buildResponseTypes(node, tsResolver, { returnType });
 	const generics = [
 		TData,
 		TError,
 		resolveMutationRequestType(node, tsResolver),
 		"TContext"
 	].join(", ");
-	const returnType = `UseMutationResult<${generics}>`;
+	const resultType = `UseMutationResult<${generics}>`;
 	const mutationOptionsConfigNode = buildMutationConfigParamsNode(node);
 	const mutationOptionsParamsCall = callPrinter.print(mutationOptionsConfigNode) ?? "";
-	const paramsNode = buildMutationParamsNode(node, { resolver: tsResolver });
+	const paramsNode = buildMutationParamsNode(node, {
+		resolver: tsResolver,
+		returnType
+	});
 	const paramsSignature = declarationPrinter.print(paramsNode) ?? "";
 	return /* @__PURE__ */ jsx(File.Source, {
 		name,
@@ -2052,7 +2086,7 @@ function Mutation({ name, mutationOptionsName, node, tsResolver, mutationKeyName
           ...baseOptions,${customOptions ? "\n          ...customOptions," : ""}
           mutationKey,
           ...mutationOptions,
-        }, queryClient) as ${returnType}
+        }, queryClient) as ${resultType}
     `
 		})
 	});
@@ -2096,7 +2130,8 @@ const mutationGenerator = defineGenerator({
 			name: mutationHookName,
 			output,
 			group,
-			contractOp
+			contractOp,
+			returnType: ctx.options.returnType
 		});
 		const { tsResolver } = hook;
 		return /* @__PURE__ */ jsxs(HookFile, {
@@ -2121,7 +2156,8 @@ const mutationGenerator = defineGenerator({
 					mutationKeyName,
 					node,
 					tsResolver,
-					returnType: contractOp.returnType
+					clientReturnType: contractOp.returnType,
+					returnType: hook.returnType
 				}),
 				mutation && hooks && /* @__PURE__ */ jsxs(Fragment, { children: [
 					/* @__PURE__ */ jsx(File.Import, {
@@ -2143,7 +2179,8 @@ const mutationGenerator = defineGenerator({
 						mutationKeyName,
 						node,
 						tsResolver,
-						customOptions
+						customOptions,
+						returnType: hook.returnType
 					})
 				] })
 			]
@@ -2278,7 +2315,7 @@ const pluginReactQuery = defineExtension({
 		const { output = {
 			path: "hooks",
 			barrel: { type: "named" }
-		}, group, exclude = [], include, override = [], suspense = false, infinite = false, mutation = {}, query = {}, mutationKey = mutationKeyTransformer, queryKey = queryKeyTransformer, customOptions, hooks = false, client, resolver: userResolver, macros: userMacros } = options;
+		}, group, exclude = [], include, override = [], suspense = false, infinite = false, mutation = {}, query = {}, mutationKey = mutationKeyTransformer, queryKey = queryKeyTransformer, customOptions, hooks = false, client, returnType = "data", resolver: userResolver, macros: userMacros } = options;
 		const resolver = userResolver ? Resolver.merge(resolverReactQuery, userResolver) : resolverReactQuery;
 		setResolver(resolver);
 		if (userMacros?.length) setMacros(userMacros);
@@ -2290,6 +2327,7 @@ const pluginReactQuery = defineExtension({
 				client,
 				plugins: useConfig().plugins
 			}),
+			returnType,
 			queryKey,
 			query: resolveQueryConfig(query, { importPath: "@tanstack/react-query" }),
 			mutationKey,