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

package/dist/index.d.ts

@@ -119,7 +119,51 @@ type Infinite = {
    * @default 0
    */
   initialPageParam?: unknown;
+  /**
+   * Whether `initialPageParam` was explicitly configured rather than defaulted.
+   * When omitted or false, the default previous page threshold remains 1 (legacy 1-based default).
+   */
+  hasExplicitInitialPageParam?: boolean;
+  /**
+   * Source of TanStack Query's `getNextPageParam`, inlined verbatim as a function expression. Use it
+   * when the next page has to be computed rather than read from a field. Takes precedence over
+   * `nextParam` and `cursorParam`.
+   *
+   * Note: Because functions are inlined verbatim into generated code via `.toString()`, they cannot
+   * reference local closures or external variables from the config file.
+   *
+   * @example
+   * `'(lastPage) => (lastPage.hasNext ? lastPage.number + 1 : undefined)'`
+   * // or with definePageParam:
+   * `definePageParam<MyResponse, number>((lastPage) => (lastPage.hasNext ? lastPage.number + 1 : undefined))`
+   */
+  getNextPageParam?: string | PageParamFn | null;
+  /**
+   * Source of TanStack Query's `getPreviousPageParam`, inlined verbatim as a function expression.
+   * Takes precedence over `previousParam` and `cursorParam`.
+   *
+   * Note: Because functions are inlined verbatim into generated code via `.toString()`, they cannot
+   * reference local closures or external variables from the config file.
+   *
+   * @example
+   * `'(firstPage) => (firstPage.number > 0 ? firstPage.number - 1 : undefined)'`
+   * // or with definePageParam:
+   * `definePageParam<MyResponse, number>((firstPage) => (firstPage.number > 0 ? firstPage.number - 1 : undefined))`
+   */
+  getPreviousPageParam?: string | PageParamFn | null;
 };
+type PageParamFn<TPage = any, TParam = any> = (page: TPage, allPages: Array<TPage>, pageParam: TParam, allPageParams: Array<TParam>) => TParam | undefined | null;
+//#endregion
+//#region ../../internals/tanstack-query/src/utils.d.ts
+/**
+ * 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.
+ */
+export declare function definePageParam<TPage = any, TParam = any>(fn: PageParamFn<TPage, TParam>): string;
 //#endregion
 //#region src/types.d.ts
 /**
@@ -506,5 +550,5 @@ export declare const pluginReactQuery: import("kubb/kit").PluginFactory<PluginRe
  */
 export declare const resolverReactQuery: ResolverReactQuery;
 //#endregion
-export { type PluginReactQuery, type ResolverReactQuery, pluginReactQuery as default };
+export { type PageParamFn, type PluginReactQuery, type ResolverReactQuery, pluginReactQuery as default };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,5 +1,5 @@
 import "./rolldown-runtime-C0LytTxp.js";
-import { Resolver, Url, ast, createResolver, defineGenerator, definePlugin } from "kubb/kit";
+import { Resolver, Url, addGenerator, ast, createResolver, defineGenerator, definePlugin, setMacros, setResolver, useConfig } from "kubb/kit";
 import path from "node:path";
 import { createFunctionParameter, createFunctionParameters, createObjectBindingPattern, createTypeLiteral, functionPrinter, pluginTsName } from "@kubb/plugin-ts";
 import { File, Function, Type, jsxRenderer } from "kubb/jsx";
@@ -324,7 +324,7 @@ function createGroupConfig(group) {
 }
 //#endregion
 //#region package.json
-var version = "5.3.0-canary.20261012T181005";
+var version = "5.3.0";
 //#endregion
 //#region ../../internals/client/src/resolveClient.ts
 /**
@@ -664,21 +664,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);
@@ -736,7 +775,7 @@ function buildQueryKeyParams(node, options) {
 //#region ../../internals/tanstack-query/src/components/InfiniteQueryOptions.tsx
 const declarationPrinter$7 = functionPrinter({ mode: "declaration" });
 const callPrinter$3 = 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,
@@ -760,18 +799,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);
@@ -1522,8 +1568,7 @@ const infiniteQueryGenerator = 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 (!ast.isHttpOperationNode(node)) return null;
@@ -1533,6 +1578,8 @@ const infiniteQueryGenerator = defineGenerator({
 		const tsResolver = driver.getResolver(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 },
@@ -1646,7 +1693,10 @@ const infiniteQueryGenerator = 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
 				}),
@@ -2000,8 +2050,7 @@ const suspenseInfiniteQueryGenerator = 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 (!ast.isHttpOperationNode(node)) return null;
@@ -2041,12 +2090,16 @@ const suspenseInfiniteQueryGenerator = 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
 			})
@@ -2120,7 +2173,10 @@ const suspenseInfiniteQueryGenerator = 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
 				}),
@@ -2389,23 +2445,23 @@ const pluginReactQuery = definePlugin({
 	meta: {
 		name: pluginReactQueryName,
 		version,
-		compatibility: { kubb: ">=5.7.0" }
+		compatibility: { kubb: ">=5.8.0" }
 	},
 	dependencies: { [pluginTsName]: {} },
-	setup(options, kubb) {
+	setup(options) {
 		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;
 		const resolver = userResolver ? Resolver.merge(resolverReactQuery, userResolver) : resolverReactQuery;
-		kubb.setResolver(resolver);
-		if (userMacros?.length) kubb.setMacros(userMacros);
-		kubb.addGenerator(queryGenerator, suspenseQueryGenerator, infiniteQueryGenerator, suspenseInfiniteQueryGenerator, mutationGenerator, hookOptionsGenerator, customHookOptionsFileGenerator);
+		setResolver(resolver);
+		if (userMacros?.length) setMacros(userMacros);
+		addGenerator(queryGenerator, suspenseQueryGenerator, infiniteQueryGenerator, suspenseInfiniteQueryGenerator, mutationGenerator, hookOptionsGenerator, customHookOptionsFileGenerator);
 		return {
 			output,
 			client: resolveContractClient({
 				client,
-				plugins: kubb.config.plugins
+				plugins: useConfig().plugins
 			}),
 			queryKey,
 			query: resolveQueryConfig(query, { importPath: "@tanstack/react-query" }),
@@ -2427,6 +2483,6 @@ const pluginReactQuery = definePlugin({
 	}
 });
 //#endregion
-export { pluginReactQuery as default, pluginReactQuery, pluginReactQueryName, resolverReactQuery };
+export { pluginReactQuery as default, pluginReactQuery, definePageParam, pluginReactQueryName, resolverReactQuery };
 
 //# sourceMappingURL=index.js.map