@kubb/plugin-react-query 5.3.0-canary.20261012T190229 → 5.3.1

package/OVERVIEW.md

@@ -0,0 +1,20 @@
+# React Query
+
+Generates TanStack Query helpers for React from your OpenAPI spec. By default you get `queryOptions` and `mutationOptions` factories with their cache keys. Set `hooks: true` to also get `useQuery`, `useSuspenseQuery`, `useInfiniteQuery`, and `useMutation` hooks.
+
+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/react-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*` hooks on top of the option factories.
+- `suspense` adds `useSuspenseQuery` hooks.
+- `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.
+- `customOptions` routes every hook through your own function that returns extra options.

package/dist/index.cjs

@@ -350,8 +350,14 @@ function createGroupConfig(group) {
 	};
 }
 //#endregion
+//#region kubb-extension.json
+var compatibility = {
+	"kubb": ">=5.8.0",
+	"node": ">=22"
+};
+//#endregion
 //#region package.json
-var version = "5.3.0-canary.20261012T190229";
+var version = "5.3.1";
 //#endregion
 //#region ../../internals/client/src/resolveClient.ts
 /**
@@ -691,21 +697,60 @@ function classifyOperation(node, { query, mutation }) {
 	};
 }
 /**
+* Helper to define a typed page param function for `infinite.getNextPageParam` or
+* `infinite.getPreviousPageParam`. Serializes the function to a string for inlining in generated code.
+*
+* Note: Because the function is inlined verbatim into the generated file via `.toString()`,
+* it must be self-contained and cannot reference local closures or external variables from
+* the config file.
+*/
+function definePageParam(fn) {
+	return fn.toString();
+}
+/**
 * Applies the shared infinite-query defaults during plugin setup: a falsy value disables infinite
 * queries, and an object merges over `queryParam: 'id'` and `initialPageParam: 0` with the cursor
 * paths cleared.
 */
 function resolveInfiniteConfig(infinite) {
 	if (!infinite) return false;
+	const hasExplicitInitialPageParam = infinite.hasExplicitInitialPageParam ?? infinite.initialPageParam !== void 0;
+	const getNextPageParam = infinite.getNextPageParam ? typeof infinite.getNextPageParam === "function" ? infinite.getNextPageParam.toString() : infinite.getNextPageParam : null;
+	const getPreviousPageParam = infinite.getPreviousPageParam ? typeof infinite.getPreviousPageParam === "function" ? infinite.getPreviousPageParam.toString() : infinite.getPreviousPageParam : null;
 	return {
 		queryParam: "id",
 		initialPageParam: 0,
+		hasExplicitInitialPageParam,
 		cursorParam: null,
 		nextParam: null,
 		previousParam: null,
-		...infinite
+		getNextPageParam,
+		getPreviousPageParam,
+		...infinite,
+		...getNextPageParam ? { getNextPageParam } : {},
+		...getPreviousPageParam ? { getPreviousPageParam } : {}
 	};
 }
+/**
+* Whether the infinite hook for `node` should be generated: the operation takes the configured
+* `queryParam`.
+*/
+function matchesInfinite(node, infinite) {
+	if (!infinite.queryParam) return false;
+	return getOperationParameters(node).query.some((param) => param.name.replace(/\?$/, "") === infinite.queryParam);
+}
+/**
+* Warning for an infinite hook that falls back to the built-in page params on a response that
+* isn't an array. Those params only stop on an empty array, so `hasNextPage` never turns false.
+*/
+function getDefaultPageParamsWarning(node, infinite) {
+	if (!(infinite.getNextPageParam == null && infinite.getPreviousPageParam == null && infinite.nextParam == null && infinite.previousParam == null && !infinite.cursorParam)) return null;
+	const content = getPrimarySuccessResponse(node)?.content;
+	let resolved = (content?.find((item) => item.contentType?.includes("json")) ?? content?.[0])?.schema;
+	while (resolved?.type === "ref" || resolved?.type === "intersection" && resolved.members?.length === 1) resolved = resolved.type === "ref" ? resolved.schema : resolved.members?.[0];
+	if (!resolved || resolved.type === "array") return null;
+	return `${node.operationId}: the default infinite page params expect an array response and never end for this one. Set \`infinite.getNextPageParam\` (or \`nextParam\`) to read the next page from the response.`;
+}
 function matchesPattern(node, ov) {
 	const { type, pattern } = ov;
 	const matches = (value) => typeof pattern === "string" ? value === pattern : pattern.test(value);
@@ -763,7 +808,7 @@ function buildQueryKeyParams(node, options) {
 //#region ../../internals/tanstack-query/src/components/InfiniteQueryOptions.tsx
 const declarationPrinter$7 = (0, _kubb_plugin_ts.functionPrinter)({ mode: "declaration" });
 const callPrinter$3 = (0, _kubb_plugin_ts.functionPrinter)({ mode: "call" });
-function InfiniteQueryOptions({ name, clientName, initialPageParam, cursorParam, nextParam, previousParam, node, tsResolver, queryParam, queryKeyName, queryKeyType = "typeof queryKey", memberTypeWrapper, unwrapName, returnType = "full" }) {
+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);
 	const { queryParamsTypeName, pageParamType } = resolvePageParamType(node, {
 		resolver: tsResolver,
@@ -787,18 +832,25 @@ function InfiniteQueryOptions({ name, clientName, initialPageParam, cursorParam,
 		signal: true,
 		unwrapName
 	}), { returnType });
-	const hasNewParams = nextParam != null || previousParam != null;
-	const [getNextPageParamExpr, getPreviousPageParamExpr] = (() => {
-		if (hasNewParams) {
-			const nextAccessor = nextParam ? getNestedAccessor(nextParam, "lastPage") : null;
-			const prevAccessor = previousParam ? getNestedAccessor(previousParam, "firstPage") : null;
-			return [nextAccessor ? `getNextPageParam: (lastPage) => ${nextAccessor}` : null, prevAccessor ? `getPreviousPageParam: (firstPage) => ${prevAccessor}` : null];
-		}
-		if (cursorParam) return [`getNextPageParam: (lastPage) => lastPage['${cursorParam}']`, `getPreviousPageParam: (firstPage) => firstPage['${cursorParam}']`];
-		return ["getNextPageParam: (lastPage, _allPages, lastPageParam) => Array.isArray(lastPage) && lastPage.length === 0 ? undefined : lastPageParam + 1", "getPreviousPageParam: (_firstPage, _allPages, firstPageParam) => firstPageParam <= 1 ? undefined : firstPageParam - 1"];
+	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";
+	})();
+	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 (serializedGetNextPageParam || nextParam) return null;
+		return `getPreviousPageParam: (_firstPage, _allPages, firstPageParam) => firstPageParam <= ${defaultPreviousThreshold} ? undefined : firstPageParam - 1`;
 	})();
 	const queryOptionsArr = [
-		`initialPageParam: ${typeof initialPageParam === "string" ? JSON.stringify(initialPageParam) : initialPageParam}`,
+		`initialPageParam: ${initialPageParamLiteral}`,
 		getNextPageParamExpr,
 		getPreviousPageParamExpr
 	].filter(Boolean);
@@ -1549,8 +1601,7 @@ const infiniteQueryGenerator = (0, kubb_kit.defineGenerator)({
 		});
 		const infiniteOptions = infinite && typeof infinite === "object" ? infinite : null;
 		if (!isQuery || isMutation || !infiniteOptions || !hooks) return false;
-		const queryParamKeys = getOperationParameters(operationNode).query.map((p) => p.name);
-		return infiniteOptions.queryParam ? queryParamKeys.includes(infiniteOptions.queryParam) || queryParamKeys.includes(`${infiniteOptions.queryParam}?`) : false;
+		return matchesInfinite(operationNode, infiniteOptions);
 	},
 	operation(node, ctx) {
 		if (!kubb_kit.ast.isHttpOperationNode(node)) return null;
@@ -1560,6 +1611,8 @@ const infiniteQueryGenerator = (0, kubb_kit.defineGenerator)({
 		const tsResolver = driver.getResolver(_kubb_plugin_ts.pluginTsName);
 		const infiniteOptions = infinite && typeof infinite === "object" ? infinite : null;
 		if (!infiniteOptions) return null;
+		const pageParamsWarning = getDefaultPageParamsWarning(node, infiniteOptions);
+		if (pageParamsWarning) ctx.warn(pageParamsWarning);
 		const importPath = query ? query.importPath : "@tanstack/react-query";
 		const contractOp = resolveClientOperation({
 			clientPlugin: { pluginName: client.pluginName },
@@ -1673,7 +1726,10 @@ const infiniteQueryGenerator = (0, kubb_kit.defineGenerator)({
 					cursorParam: infiniteOptions.cursorParam,
 					nextParam: infiniteOptions.nextParam,
 					previousParam: infiniteOptions.previousParam,
+					getNextPageParam: infiniteOptions.getNextPageParam,
+					getPreviousPageParam: infiniteOptions.getPreviousPageParam,
 					initialPageParam: infiniteOptions.initialPageParam,
+					hasExplicitInitialPageParam: infiniteOptions.hasExplicitInitialPageParam,
 					queryParam: infiniteOptions.queryParam,
 					returnType: contractOp.returnType
 				}),
@@ -2027,8 +2083,7 @@ const suspenseInfiniteQueryGenerator = (0, kubb_kit.defineGenerator)({
 		});
 		const infiniteOptions = infinite && typeof infinite === "object" ? infinite : null;
 		if (!isQuery || isMutation || !suspense || !infiniteOptions || !hooks) return false;
-		const queryParamKeys = getOperationParameters(operationNode).query.map((p) => p.name);
-		return infiniteOptions.queryParam ? queryParamKeys.includes(infiniteOptions.queryParam) || queryParamKeys.includes(`${infiniteOptions.queryParam}?`) : false;
+		return matchesInfinite(operationNode, infiniteOptions);
 	},
 	operation(node, ctx) {
 		if (!kubb_kit.ast.isHttpOperationNode(node)) return null;
@@ -2068,12 +2123,16 @@ const suspenseInfiniteQueryGenerator = (0, kubb_kit.defineGenerator)({
 				group: pluginTs.options?.group
 			})
 		};
-		const rawQueryParams = getOperationParameters(node).query;
-		const queryParamsTypeName = rawQueryParams.length > 0 && tsResolver.param.query(node, rawQueryParams[0]) !== tsResolver.param.name(node, rawQueryParams[0]) ? tsResolver.param.query(node, rawQueryParams[0]) : null;
+		const { queryParamsTypeName } = resolvePageParamType(node, {
+			resolver: tsResolver,
+			initialPageParam: infiniteOptions.initialPageParam,
+			queryParam: infiniteOptions.queryParam
+		});
 		const importedTypeNames = [
 			tsResolver.response.options(node),
 			queryParamsTypeName,
 			...resolveOperationTypeNames(node, tsResolver, {
+				exclude: [queryKeyTypeName],
 				order: "body-response-first",
 				includeParams: false
 			})
@@ -2147,7 +2206,10 @@ const suspenseInfiniteQueryGenerator = (0, kubb_kit.defineGenerator)({
 					cursorParam: infiniteOptions.cursorParam,
 					nextParam: infiniteOptions.nextParam,
 					previousParam: infiniteOptions.previousParam,
+					getNextPageParam: infiniteOptions.getNextPageParam,
+					getPreviousPageParam: infiniteOptions.getPreviousPageParam,
 					initialPageParam: infiniteOptions.initialPageParam,
+					hasExplicitInitialPageParam: infiniteOptions.hasExplicitInitialPageParam,
 					queryParam: infiniteOptions.queryParam,
 					returnType: contractOp.returnType
 				}),
@@ -2416,7 +2478,7 @@ const pluginReactQuery = (0, kubb_kit.definePlugin)({
 	meta: {
 		name: pluginReactQueryName,
 		version,
-		compatibility: { kubb: ">=5.8.0" }
+		compatibility
 	},
 	dependencies: { [_kubb_plugin_ts.pluginTsName]: {} },
 	setup(options) {
@@ -2455,6 +2517,7 @@ const pluginReactQuery = (0, kubb_kit.definePlugin)({
 });
 //#endregion
 exports.default = pluginReactQuery;
+exports.definePageParam = definePageParam;
 exports.pluginReactQuery = pluginReactQuery;
 exports.pluginReactQueryName = pluginReactQueryName;
 exports.resolverReactQuery = resolverReactQuery;