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

package/OVERVIEW.md

@@ -0,0 +1,18 @@
+# Vue Query
+
+Generates TanStack Query helpers for Vue from your OpenAPI spec. By default you get `queryOptions` factories with their query and mutation keys. Set `hooks: true` to also get `useQuery`, `useInfiniteQuery`, and `useMutation` composables with reactive parameters.
+
+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/vue-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*` composables on top of the option factories.
+- `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.

package/dist/index.cjs

@@ -352,8 +352,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/tanstack-query/src/utils.ts
 /**
@@ -571,22 +577,61 @@ 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.`;
+}
+/**
 * The request groups a query key is built from, matching `buildQueryKeyParams`. Headers are
 * deliberately absent: they do not identify a cache entry, so the key factory takes no parameter
 * for an operation that only carries headers.
@@ -600,7 +645,7 @@ const queryKeyGroupOrder = [
 //#region ../../internals/tanstack-query/src/components/InfiniteQueryOptions.tsx
 const declarationPrinter$7 = (0, _kubb_plugin_ts.functionPrinter)({ mode: "declaration" });
 const callPrinter$4 = (0, _kubb_plugin_ts.functionPrinter)({ mode: "call" });
-function InfiniteQueryOptions$1({ name, clientName, initialPageParam, cursorParam, nextParam, previousParam, node, tsResolver, queryParam, queryKeyName, queryKeyType = "typeof queryKey", memberTypeWrapper, unwrapName, returnType = "full" }) {
+function InfiniteQueryOptions$1({ 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,
@@ -624,18 +669,25 @@ function InfiniteQueryOptions$1({ name, clientName, initialPageParam, cursorPara
 		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);
@@ -1225,21 +1277,28 @@ function Query({ name, queryKeyTypeName, queryOptionsName, queryKeyName, node, t
 const infiniteQueryGenerator = (0, kubb_kit.defineGenerator)({
 	name: "vue-query-infinite",
 	renderer: kubb_jsx.jsxRenderer,
+	match(node, ctx) {
+		const operationNode = node;
+		if (!kubb_kit.ast.isHttpOperationNode(operationNode)) return false;
+		const { query, mutation, infinite, hooks } = ctx.options;
+		const { isQuery, isMutation } = classifyOperation(operationNode, {
+			query,
+			mutation
+		});
+		const infiniteOptions = infinite && typeof infinite === "object" ? infinite : null;
+		if (!isQuery || isMutation || !infiniteOptions || !hooks) return false;
+		return matchesInfinite(operationNode, infiniteOptions);
+	},
 	operation(node, ctx) {
 		if (!kubb_kit.ast.isHttpOperationNode(node)) return null;
 		const { config, driver, resolver, root } = ctx;
-		const { output, query, mutation, infinite, client, group, hooks } = ctx.options;
+		const { output, query, infinite, client, group } = ctx.options;
+		const infiniteOptions = infinite && typeof infinite === "object" ? infinite : null;
+		if (!infiniteOptions) return null;
+		const pageParamsWarning = getDefaultPageParamsWarning(node, infiniteOptions);
+		if (pageParamsWarning) ctx.warn(pageParamsWarning);
 		const pluginTs = ctx.requirePlugin(_kubb_plugin_ts.pluginTsName);
 		const tsResolver = driver.getResolver(_kubb_plugin_ts.pluginTsName);
-		const { isQuery, isMutation } = classifyOperation(node, {
-			query,
-			mutation
-		});
-		const infiniteOptions = infinite && typeof infinite === "object" ? infinite : null;
-		if (!isQuery || isMutation || !infiniteOptions || !hooks) return null;
-		const normalizeKey = (key) => key.replace(/\?$/, "");
-		const queryParamKeys = getOperationParameters(node).query.map((p) => p.name);
-		if (!(infiniteOptions.queryParam ? queryParamKeys.some((k) => normalizeKey(k) === infiniteOptions.queryParam) : false)) return null;
 		const importPath = query ? query.importPath : "@tanstack/vue-query";
 		const contractOp = resolveClientOperation({
 			clientPlugin: { pluginName: client.pluginName },
@@ -1358,7 +1417,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
 				}),
@@ -1741,7 +1803,7 @@ const pluginVueQuery = (0, kubb_kit.definePlugin)({
 	meta: {
 		name: pluginVueQueryName,
 		version,
-		compatibility: { kubb: ">=5.8.0" }
+		compatibility
 	},
 	dependencies: { [_kubb_plugin_ts.pluginTsName]: {} },
 	setup(options) {
@@ -1775,6 +1837,7 @@ const pluginVueQuery = (0, kubb_kit.definePlugin)({
 });
 //#endregion
 exports.default = pluginVueQuery;
+exports.definePageParam = definePageParam;
 exports.pluginVueQuery = pluginVueQuery;
 exports.pluginVueQueryName = pluginVueQueryName;
 exports.resolverVueQuery = resolverVueQuery;