@kizunajs/tanstack-query 2.0.0-beta.0

package/LICENSE.MD

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Sondre Ørland
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,33 @@
+# @kizunajs/tanstack-query
+
+`@kizunajs/tanstack-query` provides `new KizunaTanstackQuery()`, which builds TanStack Query options from a Kizuna api. Query keys, caching, and invalidation come from the routes you already wrote.
+
+## Installation
+
+```sh
+pnpm add @kizunajs/tanstack-query
+```
+
+## Usage
+
+```ts
+import { useQuery } from '@tanstack/react-query';
+import { KizunaTanstackQuery } from '@kizunajs/tanstack-query';
+import { apiClient } from './api-client';
+
+const api = new KizunaTanstackQuery(apiClient);
+
+const { data } = useQuery(
+    api.users.getUser.queryOptions({
+        input: {
+            params: {
+                id: '1',
+            },
+        },
+    })
+);
+```
+
+## Documentation
+
+[TanStack Query client](https://kizunajs.com/docs/clients/tanstack-query)

package/dist/index.cjs

@@ -0,0 +1,186 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _tanstack_query_core = require("@tanstack/query-core");
+let kizunajs = require("kizunajs");
+let _kizunajs_fetch = require("@kizunajs/fetch");
+//#region src/errors.ts
+/**
+* Thrown when a route returns a status the api does not declare. Declared
+* statuses come back as `data` instead.
+*/
+var UndeclaredResponseError = class extends Error {
+	status;
+	body;
+	headers;
+	constructor(routeKey, status, body, headers) {
+		super(`${routeKey} responded ${status}, which its api does not declare.`);
+		this.name = "UndeclaredResponseError";
+		this.status = status;
+		this.body = body;
+		this.headers = headers;
+	}
+};
+/**
+* Narrows an `error` from a query or mutation to {@link UndeclaredResponseError}.
+*/
+const isUndeclaredResponseError = (error) => error instanceof UndeclaredResponseError;
+/**
+* Thrown by `streamOptions` when a streamed route answers a declared status that
+* does not stream, such as its `400`. The query has nothing to accumulate.
+*/
+var NonStreamResponseError = class extends Error {
+	status;
+	body;
+	headers;
+	constructor(routeKey, status, body, headers) {
+		super(`${routeKey} responded ${status}, which is not its streamed status.`);
+		this.name = "NonStreamResponseError";
+		this.status = status;
+		this.body = body;
+		this.headers = headers;
+	}
+};
+const isNonStreamResponseError = (error) => error instanceof NonStreamResponseError;
+//#endregion
+//#region src/keys.ts
+const withoutFetchOptions = (input) => {
+	if (typeof input !== "object" || input === null) return input;
+	const { fetchOptions: _fetchOptions, ...rest } = input;
+	return Object.keys(rest).length === 0 ? void 0 : rest;
+};
+const buildQueryKey = (segments, input, type) => {
+	const hashable = withoutFetchOptions(input);
+	return hashable === void 0 ? [segments, { type }] : [segments, {
+		input: hashable,
+		type
+	}];
+};
+const buildPathKey = (segments) => [segments];
+//#endregion
+//#region src/proxy.ts
+const declaresStatus = (route, status) => {
+	if (Object.hasOwn(route.responses, String(status))) return true;
+	return status === 400 && ("body" in route || "query" in route);
+};
+const withSignal = (args, signal) => {
+	if (signal === void 0) return args;
+	const { fetchOptions, ...rest } = args ?? {};
+	return {
+		...rest,
+		fetchOptions: {
+			...fetchOptions,
+			signal: fetchOptions?.signal ?? signal
+		}
+	};
+};
+const runRoute = async (clientFn, route, routeKey, args, signal) => {
+	const result = await clientFn(withSignal(args, signal));
+	if (!declaresStatus(route, result.status)) throw new UndeclaredResponseError(routeKey, result.status, result.body, result.headers);
+	return result;
+};
+const isQueryMethod = (route) => route.method === "GET" || route.method === "HEAD";
+const buildProcedure = (segments, route, clientFn) => {
+	const routeKey = segments.join(".");
+	const call = (args) => clientFn(args);
+	if ((0, kizunajs.routeStreams)(route)) return {
+		streamOptions: (options) => {
+			const { input, refetchMode, ...rest } = options;
+			const skipped = input === _tanstack_query_core.skipToken;
+			return {
+				queryKey: buildQueryKey(segments, skipped ? void 0 : input, "stream"),
+				queryFn: skipped ? _tanstack_query_core.skipToken : (0, _tanstack_query_core.experimental_streamedQuery)({
+					streamFn: async ({ signal }) => {
+						const result = await runRoute(clientFn, route, routeKey, input, signal);
+						if (!(0, kizunajs.streamStatuses)(route).includes(result.status)) throw new NonStreamResponseError(routeKey, result.status, result.body, result.headers);
+						return result.body;
+					},
+					...refetchMode === void 0 ? {} : { refetchMode }
+				}),
+				...rest
+			};
+		},
+		streamKey: (options) => buildQueryKey(segments, options?.input, "stream"),
+		key: () => buildPathKey(segments),
+		call
+	};
+	if (!isQueryMethod(route)) return {
+		mutationOptions: (options) => ({
+			mutationKey: buildPathKey(segments),
+			mutationFn: (variables) => runRoute(clientFn, route, routeKey, variables, void 0),
+			...options
+		}),
+		mutationKey: () => buildPathKey(segments),
+		key: () => buildPathKey(segments),
+		call
+	};
+	return {
+		queryOptions: (options) => {
+			const { input, ...rest } = options;
+			const skipped = input === _tanstack_query_core.skipToken;
+			return {
+				queryKey: buildQueryKey(segments, skipped ? void 0 : input, "query"),
+				queryFn: skipped ? _tanstack_query_core.skipToken : ({ signal }) => runRoute(clientFn, route, routeKey, input, signal),
+				...rest
+			};
+		},
+		infiniteOptions: (options) => {
+			const { input, ...rest } = options;
+			const skipped = input === _tanstack_query_core.skipToken;
+			return {
+				queryKey: buildQueryKey(segments, skipped ? void 0 : input, "infinite"),
+				queryFn: skipped ? _tanstack_query_core.skipToken : ({ pageParam, signal }) => runRoute(clientFn, route, routeKey, input(pageParam), signal),
+				...rest
+			};
+		},
+		queryKey: (options) => buildQueryKey(segments, options?.input, "query"),
+		infiniteKey: (options) => buildQueryKey(segments, options?.input, "infinite"),
+		key: () => buildPathKey(segments),
+		call
+	};
+};
+/**
+* Walks the client itself. Each method carries the route it answers, so the
+* shape of the client is the shape of the proxy and nothing else is needed.
+*/
+const buildNode = (segments, clientNode) => {
+	const node = { key: () => buildPathKey(segments) };
+	for (const routeName of Object.keys(clientNode)) {
+		const child = clientNode[routeName];
+		const childSegments = [...segments, routeName];
+		const route = (0, _kizunajs_fetch.routeOf)(child);
+		if (route) node[routeName] = buildProcedure(childSegments, route, child);
+		else if (child && typeof child === "object") node[routeName] = buildNode(childSegments, child);
+	}
+	return node;
+};
+function buildQueryProxy(client) {
+	return buildNode([], client);
+}
+/**
+* Builds TanStack Query options from a fetch client. Every client method
+* carries the route it answers, so the client is the only argument.
+*
+* ```ts
+* import { useQuery } from '@tanstack/react-query';
+* import { KizunaTanstackQuery } from '@kizunajs/tanstack-query';
+* import { apiClient } from './api-client.js';
+*
+* const api = new KizunaTanstackQuery(apiClient);
+*
+* useQuery(
+*     api.users.listUsers.queryOptions({
+*         input: {
+*             query: {
+*                 page: 1,
+*             },
+*         },
+*     })
+* );
+* ```
+*/
+const KizunaTanstackQuery = buildQueryProxy;
+//#endregion
+exports.KizunaTanstackQuery = KizunaTanstackQuery;
+exports.NonStreamResponseError = NonStreamResponseError;
+exports.UndeclaredResponseError = UndeclaredResponseError;
+exports.isNonStreamResponseError = isNonStreamResponseError;
+exports.isUndeclaredResponseError = isUndeclaredResponseError;

package/dist/index.d.cts

@@ -0,0 +1,232 @@
+import { DataTag, DefaultError, InfiniteData, InfiniteQueryObserverOptions, MutationObserverOptions, QueryFunction, QueryFunctionContext, QueryObserverOptions, SkipToken } from "@tanstack/query-core";
+import { RouteDefinition, Routes, StreamResponseDefinition } from "kizunajs";
+import { Client, ClientArgs, ClientMethod, ClientResponse } from "@kizunajs/fetch";
+
+//#region src/types.d.ts
+type KizunaQueryKeyType = 'query' | 'infinite' | 'stream';
+/**
+ * `[segments, { input, type }]`, for example
+ * `[['users', 'getUser'], { input: { params: { id: '1' } }, type: 'query' }]`.
+ */
+type KizunaQueryKey = readonly [readonly string[], {
+  readonly input?: unknown;
+  readonly type: KizunaQueryKeyType;
+}];
+/**
+ * `[segments]`, the prefix every operation under a route or group matches.
+ */
+type KizunaPathKey = readonly [readonly string[]];
+type HasOptionalArgs<Args> = {} extends Args ? true : false;
+type CallFn<Args, Result> = HasOptionalArgs<Args> extends true ? (args?: Args) => Promise<Result> : (args: Args) => Promise<Result>;
+type QueryExtras<TQueryFnData, TError> = Omit<QueryObserverOptions<TQueryFnData, TError, unknown, TQueryFnData, KizunaQueryKey>, 'queryKey' | 'queryFn'>;
+type QueryInput<Args> = HasOptionalArgs<Args> extends true ? {
+  input?: Args | SkipToken;
+} : {
+  input: Args | SkipToken;
+};
+type QueryOptionsOut<U, TQueryFnData, TError> = Omit<NoInfer<U>, 'input'> & {
+  queryKey: DataTag<KizunaQueryKey, TQueryFnData, TError>;
+  queryFn: U extends {
+    input: SkipToken;
+  } ? SkipToken : (context: QueryFunctionContext<KizunaQueryKey>) => Promise<TQueryFnData>;
+};
+type QueryOptionsFn<Args, Result> = <U extends QueryInput<Args> & QueryExtras<Result, DefaultError>>(options: U) => QueryOptionsOut<U, Result, DefaultError>;
+type InfiniteExtras<TQueryFnData, TError, TPageParam> = Omit<InfiniteQueryObserverOptions<TQueryFnData, TError, unknown, KizunaQueryKey, TPageParam>, 'queryKey' | 'queryFn'>;
+type InfiniteOptionsOut<U, TQueryFnData, TError, TPageParam, Skipped extends boolean> = Omit<NoInfer<U>, 'input'> & {
+  queryKey: DataTag<KizunaQueryKey, InfiniteData<TQueryFnData, TPageParam>, TError>;
+  queryFn: Skipped extends true ? SkipToken : (context: QueryFunctionContext<KizunaQueryKey, TPageParam>) => Promise<TQueryFnData>;
+};
+interface InfiniteOptionsFn<Args, Result> {
+  <TPageParam, U extends InfiniteExtras<Result, DefaultError, TPageParam>>(options: {
+    input: (pageParam: TPageParam) => Args;
+  } & U): InfiniteOptionsOut<U, Result, DefaultError, TPageParam, false>;
+  <TPageParam, U extends InfiniteExtras<Result, DefaultError, TPageParam>>(options: {
+    input: SkipToken;
+  } & U): InfiniteOptionsOut<U, Result, DefaultError, TPageParam, true>;
+}
+type KeyFn<Args> = (options?: {
+  input?: Args;
+}) => KizunaQueryKey;
+/**
+ * A route whose method is `GET` or `HEAD`.
+ */
+interface QueryProcedure<Args, Result> {
+  /**
+   * Options for `useQuery`. `data` is the route's declared response union; an
+   * undeclared status throws.
+   */
+  queryOptions: QueryOptionsFn<Args, Result>;
+  /**
+   * Options for `useInfiniteQuery`. `input` is a function of the page parameter.
+   */
+  infiniteOptions: InfiniteOptionsFn<Args, Result>;
+  /**
+   * The query's full key.
+   */
+  queryKey: KeyFn<Args>;
+  /**
+   * The infinite query's full key.
+   */
+  infiniteKey: KeyFn<Args>;
+  /**
+   * The partial key matching every operation on this route.
+   */
+  key: () => KizunaPathKey;
+  /**
+   * Calls the route, bypassing the cache.
+   */
+  call: CallFn<Args, Result>;
+}
+type MutationVariables<Args> = HasOptionalArgs<Args> extends true ? void : Args;
+type MutationExtras<Args, Result, TError> = Omit<MutationObserverOptions<Result, TError, MutationVariables<Args>>, 'mutationKey' | 'mutationFn'>;
+type MutationOptionsFn<Args, Result> = <U extends MutationExtras<Args, Result, DefaultError> = MutationExtras<Args, Result, DefaultError>>(options?: U) => NoInfer<U> & {
+  mutationKey: KizunaPathKey;
+  mutationFn: (variables: MutationVariables<Args>) => Promise<Result>;
+};
+/**
+ * A route whose method is anything other than `GET` or `HEAD`.
+ */
+interface MutationProcedure<Args, Result> {
+  /**
+   * Options for `useMutation`. `mutate` takes the route's call arguments, or
+   * nothing when every argument is optional.
+   */
+  mutationOptions: MutationOptionsFn<Args, Result>;
+  /**
+   * The mutation's full key.
+   */
+  mutationKey: () => KizunaPathKey;
+  /**
+   * The partial key matching this route.
+   */
+  key: () => KizunaPathKey;
+  /**
+   * Calls the route, outside a mutation.
+   */
+  call: CallFn<Args, Result>;
+}
+/**
+ * Carried by the root and every group, for invalidating a whole group at once.
+ */
+interface PathProcedures {
+  key: () => KizunaPathKey;
+}
+/**
+ * The messages a streamed result yields, read off the `AsyncIterable` body the
+ * client hands back rather than off the route's declaration.
+ */
+type StreamMessageOfResult<Result> = Result extends {
+  body: AsyncIterable<infer Message>;
+} ? Message : never;
+type StreamExtras<TData, TError> = Omit<QueryObserverOptions<TData, TError, unknown, TData, KizunaQueryKey>, 'queryKey' | 'queryFn'> & {
+  /**
+   * What a refetch does with the messages already held: `'reset'` clears them
+   * first, `'append'` adds to them, `'replace'` swaps them in once the stream ends.
+   *
+   * @default 'reset'
+   */
+  refetchMode?: 'append' | 'reset' | 'replace';
+};
+type StreamOptionsOut<U, TData, TError> = Omit<NoInfer<U>, 'input' | 'refetchMode'> & {
+  queryKey: DataTag<KizunaQueryKey, TData, TError>;
+  queryFn: U extends {
+    input: SkipToken;
+  } ? SkipToken : QueryFunction<TData, KizunaQueryKey>;
+};
+type StreamOptionsFn<Args, Result> = <U extends QueryInput<Args> & StreamExtras<StreamMessageOfResult<Result>[], DefaultError>>(options: U) => StreamOptionsOut<U, StreamMessageOfResult<Result>[], DefaultError>;
+/**
+ * A route whose response streams. `data` is the list of messages received so
+ * far, growing as they arrive.
+ */
+interface StreamProcedure<Args, Result> {
+  /**
+   * Options for `useQuery`, over TanStack's `streamedQuery`. A status other than
+   * the streamed one throws `NonStreamResponseError`.
+   */
+  streamOptions: StreamOptionsFn<Args, Result>;
+  /**
+   * The stream query's full key.
+   */
+  streamKey: KeyFn<Args>;
+  key: () => KizunaPathKey;
+  call: CallFn<Args, Result>;
+}
+type HasStream<R extends RouteDefinition> = { [Status in keyof R['responses']]: R['responses'][Status] extends StreamResponseDefinition ? true : never }[keyof R['responses']] extends never ? false : true;
+/**
+ * Which factories a route gets: a streamed response takes `streamOptions`, a
+ * `GET` or `HEAD` takes the query factories, and everything else mutates.
+ */
+type ProcedureFor<Method, Streams, Args, Result> = Streams extends true ? StreamProcedure<Args, Result> : Method extends 'GET' | 'HEAD' ? QueryProcedure<Args, Result> : MutationProcedure<Args, Result>;
+type Procedure<R extends RouteDefinition, Codes extends string> = ProcedureFor<R['method'], HasStream<R>, ClientArgs<R>, ClientResponse<R, Codes>>;
+/**
+ * The route tree, each route carrying its query or mutation factories.
+ */
+type KizunaQueryProxy<T extends Routes, Codes extends string = never> = { [K in keyof T as K extends string ? K : never]: T[K] extends RouteDefinition ? Procedure<T[K], Codes> : T[K] extends Routes ? KizunaQueryProxy<T[K], Codes> & PathProcedures : never };
+/**
+ * The same tree, read off a generated client instead of off the routes. Each of
+ * its methods carries the method it calls and whether that response streams, so
+ * the client alone says which factories every route gets.
+ */
+type GeneratedQueryProxy<C> = { [K in keyof C as K extends string ? K : never]: C[K] extends ClientMethod<infer Method, infer Streams, infer Args, infer Result> ? ProcedureFor<Method, Streams, Args, Result> : C[K] extends object ? GeneratedQueryProxy<C[K]> & PathProcedures : never };
+interface KizunaTanstackQueryConstructor {
+  /**
+   * The client is the only argument: each of its methods carries the route it
+   * answers, so nothing has to hand over the api a second time.
+   */
+  new <T extends Routes, Codes extends string = never>(client: Client<T, Codes>): KizunaQueryProxy<T, Codes> & PathProcedures;
+  new <C extends object>(client: C): GeneratedQueryProxy<C> & PathProcedures;
+}
+//#endregion
+//#region src/proxy.d.ts
+/**
+ * Builds TanStack Query options from a fetch client. Every client method
+ * carries the route it answers, so the client is the only argument.
+ *
+ * ```ts
+ * import { useQuery } from '@tanstack/react-query';
+ * import { KizunaTanstackQuery } from '@kizunajs/tanstack-query';
+ * import { apiClient } from './api-client.js';
+ *
+ * const api = new KizunaTanstackQuery(apiClient);
+ *
+ * useQuery(
+ *     api.users.listUsers.queryOptions({
+ *         input: {
+ *             query: {
+ *                 page: 1,
+ *             },
+ *         },
+ *     })
+ * );
+ * ```
+ */
+declare const KizunaTanstackQuery: KizunaTanstackQueryConstructor;
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Thrown when a route returns a status the api does not declare. Declared
+ * statuses come back as `data` instead.
+ */
+declare class UndeclaredResponseError extends Error {
+  readonly status: number;
+  readonly body: unknown;
+  readonly headers: Record<string, string>;
+  constructor(routeKey: string, status: number, body: unknown, headers: Record<string, string>);
+}
+/**
+ * Narrows an `error` from a query or mutation to {@link UndeclaredResponseError}.
+ */
+declare const isUndeclaredResponseError: (error: unknown) => error is UndeclaredResponseError;
+/**
+ * Thrown by `streamOptions` when a streamed route answers a declared status that
+ * does not stream, such as its `400`. The query has nothing to accumulate.
+ */
+declare class NonStreamResponseError extends Error {
+  readonly status: number;
+  readonly body: unknown;
+  readonly headers: Record<string, string>;
+  constructor(routeKey: string, status: number, body: unknown, headers: Record<string, string>);
+}
+declare const isNonStreamResponseError: (error: unknown) => error is NonStreamResponseError;
+//#endregion
+export { type KizunaPathKey, type KizunaQueryKey, type KizunaQueryKeyType, type KizunaQueryProxy, KizunaTanstackQuery, type KizunaTanstackQueryConstructor, type MutationProcedure, NonStreamResponseError, type PathProcedures, type QueryProcedure, type StreamProcedure, UndeclaredResponseError, isNonStreamResponseError, isUndeclaredResponseError };

package/dist/index.d.mts

@@ -0,0 +1,232 @@
+import { DataTag, DefaultError, InfiniteData, InfiniteQueryObserverOptions, MutationObserverOptions, QueryFunction, QueryFunctionContext, QueryObserverOptions, SkipToken } from "@tanstack/query-core";
+import { RouteDefinition, Routes, StreamResponseDefinition } from "kizunajs";
+import { Client, ClientArgs, ClientMethod, ClientResponse } from "@kizunajs/fetch";
+
+//#region src/types.d.ts
+type KizunaQueryKeyType = 'query' | 'infinite' | 'stream';
+/**
+ * `[segments, { input, type }]`, for example
+ * `[['users', 'getUser'], { input: { params: { id: '1' } }, type: 'query' }]`.
+ */
+type KizunaQueryKey = readonly [readonly string[], {
+  readonly input?: unknown;
+  readonly type: KizunaQueryKeyType;
+}];
+/**
+ * `[segments]`, the prefix every operation under a route or group matches.
+ */
+type KizunaPathKey = readonly [readonly string[]];
+type HasOptionalArgs<Args> = {} extends Args ? true : false;
+type CallFn<Args, Result> = HasOptionalArgs<Args> extends true ? (args?: Args) => Promise<Result> : (args: Args) => Promise<Result>;
+type QueryExtras<TQueryFnData, TError> = Omit<QueryObserverOptions<TQueryFnData, TError, unknown, TQueryFnData, KizunaQueryKey>, 'queryKey' | 'queryFn'>;
+type QueryInput<Args> = HasOptionalArgs<Args> extends true ? {
+  input?: Args | SkipToken;
+} : {
+  input: Args | SkipToken;
+};
+type QueryOptionsOut<U, TQueryFnData, TError> = Omit<NoInfer<U>, 'input'> & {
+  queryKey: DataTag<KizunaQueryKey, TQueryFnData, TError>;
+  queryFn: U extends {
+    input: SkipToken;
+  } ? SkipToken : (context: QueryFunctionContext<KizunaQueryKey>) => Promise<TQueryFnData>;
+};
+type QueryOptionsFn<Args, Result> = <U extends QueryInput<Args> & QueryExtras<Result, DefaultError>>(options: U) => QueryOptionsOut<U, Result, DefaultError>;
+type InfiniteExtras<TQueryFnData, TError, TPageParam> = Omit<InfiniteQueryObserverOptions<TQueryFnData, TError, unknown, KizunaQueryKey, TPageParam>, 'queryKey' | 'queryFn'>;
+type InfiniteOptionsOut<U, TQueryFnData, TError, TPageParam, Skipped extends boolean> = Omit<NoInfer<U>, 'input'> & {
+  queryKey: DataTag<KizunaQueryKey, InfiniteData<TQueryFnData, TPageParam>, TError>;
+  queryFn: Skipped extends true ? SkipToken : (context: QueryFunctionContext<KizunaQueryKey, TPageParam>) => Promise<TQueryFnData>;
+};
+interface InfiniteOptionsFn<Args, Result> {
+  <TPageParam, U extends InfiniteExtras<Result, DefaultError, TPageParam>>(options: {
+    input: (pageParam: TPageParam) => Args;
+  } & U): InfiniteOptionsOut<U, Result, DefaultError, TPageParam, false>;
+  <TPageParam, U extends InfiniteExtras<Result, DefaultError, TPageParam>>(options: {
+    input: SkipToken;
+  } & U): InfiniteOptionsOut<U, Result, DefaultError, TPageParam, true>;
+}
+type KeyFn<Args> = (options?: {
+  input?: Args;
+}) => KizunaQueryKey;
+/**
+ * A route whose method is `GET` or `HEAD`.
+ */
+interface QueryProcedure<Args, Result> {
+  /**
+   * Options for `useQuery`. `data` is the route's declared response union; an
+   * undeclared status throws.
+   */
+  queryOptions: QueryOptionsFn<Args, Result>;
+  /**
+   * Options for `useInfiniteQuery`. `input` is a function of the page parameter.
+   */
+  infiniteOptions: InfiniteOptionsFn<Args, Result>;
+  /**
+   * The query's full key.
+   */
+  queryKey: KeyFn<Args>;
+  /**
+   * The infinite query's full key.
+   */
+  infiniteKey: KeyFn<Args>;
+  /**
+   * The partial key matching every operation on this route.
+   */
+  key: () => KizunaPathKey;
+  /**
+   * Calls the route, bypassing the cache.
+   */
+  call: CallFn<Args, Result>;
+}
+type MutationVariables<Args> = HasOptionalArgs<Args> extends true ? void : Args;
+type MutationExtras<Args, Result, TError> = Omit<MutationObserverOptions<Result, TError, MutationVariables<Args>>, 'mutationKey' | 'mutationFn'>;
+type MutationOptionsFn<Args, Result> = <U extends MutationExtras<Args, Result, DefaultError> = MutationExtras<Args, Result, DefaultError>>(options?: U) => NoInfer<U> & {
+  mutationKey: KizunaPathKey;
+  mutationFn: (variables: MutationVariables<Args>) => Promise<Result>;
+};
+/**
+ * A route whose method is anything other than `GET` or `HEAD`.
+ */
+interface MutationProcedure<Args, Result> {
+  /**
+   * Options for `useMutation`. `mutate` takes the route's call arguments, or
+   * nothing when every argument is optional.
+   */
+  mutationOptions: MutationOptionsFn<Args, Result>;
+  /**
+   * The mutation's full key.
+   */
+  mutationKey: () => KizunaPathKey;
+  /**
+   * The partial key matching this route.
+   */
+  key: () => KizunaPathKey;
+  /**
+   * Calls the route, outside a mutation.
+   */
+  call: CallFn<Args, Result>;
+}
+/**
+ * Carried by the root and every group, for invalidating a whole group at once.
+ */
+interface PathProcedures {
+  key: () => KizunaPathKey;
+}
+/**
+ * The messages a streamed result yields, read off the `AsyncIterable` body the
+ * client hands back rather than off the route's declaration.
+ */
+type StreamMessageOfResult<Result> = Result extends {
+  body: AsyncIterable<infer Message>;
+} ? Message : never;
+type StreamExtras<TData, TError> = Omit<QueryObserverOptions<TData, TError, unknown, TData, KizunaQueryKey>, 'queryKey' | 'queryFn'> & {
+  /**
+   * What a refetch does with the messages already held: `'reset'` clears them
+   * first, `'append'` adds to them, `'replace'` swaps them in once the stream ends.
+   *
+   * @default 'reset'
+   */
+  refetchMode?: 'append' | 'reset' | 'replace';
+};
+type StreamOptionsOut<U, TData, TError> = Omit<NoInfer<U>, 'input' | 'refetchMode'> & {
+  queryKey: DataTag<KizunaQueryKey, TData, TError>;
+  queryFn: U extends {
+    input: SkipToken;
+  } ? SkipToken : QueryFunction<TData, KizunaQueryKey>;
+};
+type StreamOptionsFn<Args, Result> = <U extends QueryInput<Args> & StreamExtras<StreamMessageOfResult<Result>[], DefaultError>>(options: U) => StreamOptionsOut<U, StreamMessageOfResult<Result>[], DefaultError>;
+/**
+ * A route whose response streams. `data` is the list of messages received so
+ * far, growing as they arrive.
+ */
+interface StreamProcedure<Args, Result> {
+  /**
+   * Options for `useQuery`, over TanStack's `streamedQuery`. A status other than
+   * the streamed one throws `NonStreamResponseError`.
+   */
+  streamOptions: StreamOptionsFn<Args, Result>;
+  /**
+   * The stream query's full key.
+   */
+  streamKey: KeyFn<Args>;
+  key: () => KizunaPathKey;
+  call: CallFn<Args, Result>;
+}
+type HasStream<R extends RouteDefinition> = { [Status in keyof R['responses']]: R['responses'][Status] extends StreamResponseDefinition ? true : never }[keyof R['responses']] extends never ? false : true;
+/**
+ * Which factories a route gets: a streamed response takes `streamOptions`, a
+ * `GET` or `HEAD` takes the query factories, and everything else mutates.
+ */
+type ProcedureFor<Method, Streams, Args, Result> = Streams extends true ? StreamProcedure<Args, Result> : Method extends 'GET' | 'HEAD' ? QueryProcedure<Args, Result> : MutationProcedure<Args, Result>;
+type Procedure<R extends RouteDefinition, Codes extends string> = ProcedureFor<R['method'], HasStream<R>, ClientArgs<R>, ClientResponse<R, Codes>>;
+/**
+ * The route tree, each route carrying its query or mutation factories.
+ */
+type KizunaQueryProxy<T extends Routes, Codes extends string = never> = { [K in keyof T as K extends string ? K : never]: T[K] extends RouteDefinition ? Procedure<T[K], Codes> : T[K] extends Routes ? KizunaQueryProxy<T[K], Codes> & PathProcedures : never };
+/**
+ * The same tree, read off a generated client instead of off the routes. Each of
+ * its methods carries the method it calls and whether that response streams, so
+ * the client alone says which factories every route gets.
+ */
+type GeneratedQueryProxy<C> = { [K in keyof C as K extends string ? K : never]: C[K] extends ClientMethod<infer Method, infer Streams, infer Args, infer Result> ? ProcedureFor<Method, Streams, Args, Result> : C[K] extends object ? GeneratedQueryProxy<C[K]> & PathProcedures : never };
+interface KizunaTanstackQueryConstructor {
+  /**
+   * The client is the only argument: each of its methods carries the route it
+   * answers, so nothing has to hand over the api a second time.
+   */
+  new <T extends Routes, Codes extends string = never>(client: Client<T, Codes>): KizunaQueryProxy<T, Codes> & PathProcedures;
+  new <C extends object>(client: C): GeneratedQueryProxy<C> & PathProcedures;
+}
+//#endregion
+//#region src/proxy.d.ts
+/**
+ * Builds TanStack Query options from a fetch client. Every client method
+ * carries the route it answers, so the client is the only argument.
+ *
+ * ```ts
+ * import { useQuery } from '@tanstack/react-query';
+ * import { KizunaTanstackQuery } from '@kizunajs/tanstack-query';
+ * import { apiClient } from './api-client.js';
+ *
+ * const api = new KizunaTanstackQuery(apiClient);
+ *
+ * useQuery(
+ *     api.users.listUsers.queryOptions({
+ *         input: {
+ *             query: {
+ *                 page: 1,
+ *             },
+ *         },
+ *     })
+ * );
+ * ```
+ */
+declare const KizunaTanstackQuery: KizunaTanstackQueryConstructor;
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Thrown when a route returns a status the api does not declare. Declared
+ * statuses come back as `data` instead.
+ */
+declare class UndeclaredResponseError extends Error {
+  readonly status: number;
+  readonly body: unknown;
+  readonly headers: Record<string, string>;
+  constructor(routeKey: string, status: number, body: unknown, headers: Record<string, string>);
+}
+/**
+ * Narrows an `error` from a query or mutation to {@link UndeclaredResponseError}.
+ */
+declare const isUndeclaredResponseError: (error: unknown) => error is UndeclaredResponseError;
+/**
+ * Thrown by `streamOptions` when a streamed route answers a declared status that
+ * does not stream, such as its `400`. The query has nothing to accumulate.
+ */
+declare class NonStreamResponseError extends Error {
+  readonly status: number;
+  readonly body: unknown;
+  readonly headers: Record<string, string>;
+  constructor(routeKey: string, status: number, body: unknown, headers: Record<string, string>);
+}
+declare const isNonStreamResponseError: (error: unknown) => error is NonStreamResponseError;
+//#endregion
+export { type KizunaPathKey, type KizunaQueryKey, type KizunaQueryKeyType, type KizunaQueryProxy, KizunaTanstackQuery, type KizunaTanstackQueryConstructor, type MutationProcedure, NonStreamResponseError, type PathProcedures, type QueryProcedure, type StreamProcedure, UndeclaredResponseError, isNonStreamResponseError, isUndeclaredResponseError };

package/dist/index.mjs

@@ -0,0 +1,181 @@
+import { experimental_streamedQuery, skipToken } from "@tanstack/query-core";
+import { routeStreams, streamStatuses } from "kizunajs";
+import { routeOf } from "@kizunajs/fetch";
+//#region src/errors.ts
+/**
+* Thrown when a route returns a status the api does not declare. Declared
+* statuses come back as `data` instead.
+*/
+var UndeclaredResponseError = class extends Error {
+	status;
+	body;
+	headers;
+	constructor(routeKey, status, body, headers) {
+		super(`${routeKey} responded ${status}, which its api does not declare.`);
+		this.name = "UndeclaredResponseError";
+		this.status = status;
+		this.body = body;
+		this.headers = headers;
+	}
+};
+/**
+* Narrows an `error` from a query or mutation to {@link UndeclaredResponseError}.
+*/
+const isUndeclaredResponseError = (error) => error instanceof UndeclaredResponseError;
+/**
+* Thrown by `streamOptions` when a streamed route answers a declared status that
+* does not stream, such as its `400`. The query has nothing to accumulate.
+*/
+var NonStreamResponseError = class extends Error {
+	status;
+	body;
+	headers;
+	constructor(routeKey, status, body, headers) {
+		super(`${routeKey} responded ${status}, which is not its streamed status.`);
+		this.name = "NonStreamResponseError";
+		this.status = status;
+		this.body = body;
+		this.headers = headers;
+	}
+};
+const isNonStreamResponseError = (error) => error instanceof NonStreamResponseError;
+//#endregion
+//#region src/keys.ts
+const withoutFetchOptions = (input) => {
+	if (typeof input !== "object" || input === null) return input;
+	const { fetchOptions: _fetchOptions, ...rest } = input;
+	return Object.keys(rest).length === 0 ? void 0 : rest;
+};
+const buildQueryKey = (segments, input, type) => {
+	const hashable = withoutFetchOptions(input);
+	return hashable === void 0 ? [segments, { type }] : [segments, {
+		input: hashable,
+		type
+	}];
+};
+const buildPathKey = (segments) => [segments];
+//#endregion
+//#region src/proxy.ts
+const declaresStatus = (route, status) => {
+	if (Object.hasOwn(route.responses, String(status))) return true;
+	return status === 400 && ("body" in route || "query" in route);
+};
+const withSignal = (args, signal) => {
+	if (signal === void 0) return args;
+	const { fetchOptions, ...rest } = args ?? {};
+	return {
+		...rest,
+		fetchOptions: {
+			...fetchOptions,
+			signal: fetchOptions?.signal ?? signal
+		}
+	};
+};
+const runRoute = async (clientFn, route, routeKey, args, signal) => {
+	const result = await clientFn(withSignal(args, signal));
+	if (!declaresStatus(route, result.status)) throw new UndeclaredResponseError(routeKey, result.status, result.body, result.headers);
+	return result;
+};
+const isQueryMethod = (route) => route.method === "GET" || route.method === "HEAD";
+const buildProcedure = (segments, route, clientFn) => {
+	const routeKey = segments.join(".");
+	const call = (args) => clientFn(args);
+	if (routeStreams(route)) return {
+		streamOptions: (options) => {
+			const { input, refetchMode, ...rest } = options;
+			const skipped = input === skipToken;
+			return {
+				queryKey: buildQueryKey(segments, skipped ? void 0 : input, "stream"),
+				queryFn: skipped ? skipToken : experimental_streamedQuery({
+					streamFn: async ({ signal }) => {
+						const result = await runRoute(clientFn, route, routeKey, input, signal);
+						if (!streamStatuses(route).includes(result.status)) throw new NonStreamResponseError(routeKey, result.status, result.body, result.headers);
+						return result.body;
+					},
+					...refetchMode === void 0 ? {} : { refetchMode }
+				}),
+				...rest
+			};
+		},
+		streamKey: (options) => buildQueryKey(segments, options?.input, "stream"),
+		key: () => buildPathKey(segments),
+		call
+	};
+	if (!isQueryMethod(route)) return {
+		mutationOptions: (options) => ({
+			mutationKey: buildPathKey(segments),
+			mutationFn: (variables) => runRoute(clientFn, route, routeKey, variables, void 0),
+			...options
+		}),
+		mutationKey: () => buildPathKey(segments),
+		key: () => buildPathKey(segments),
+		call
+	};
+	return {
+		queryOptions: (options) => {
+			const { input, ...rest } = options;
+			const skipped = input === skipToken;
+			return {
+				queryKey: buildQueryKey(segments, skipped ? void 0 : input, "query"),
+				queryFn: skipped ? skipToken : ({ signal }) => runRoute(clientFn, route, routeKey, input, signal),
+				...rest
+			};
+		},
+		infiniteOptions: (options) => {
+			const { input, ...rest } = options;
+			const skipped = input === skipToken;
+			return {
+				queryKey: buildQueryKey(segments, skipped ? void 0 : input, "infinite"),
+				queryFn: skipped ? skipToken : ({ pageParam, signal }) => runRoute(clientFn, route, routeKey, input(pageParam), signal),
+				...rest
+			};
+		},
+		queryKey: (options) => buildQueryKey(segments, options?.input, "query"),
+		infiniteKey: (options) => buildQueryKey(segments, options?.input, "infinite"),
+		key: () => buildPathKey(segments),
+		call
+	};
+};
+/**
+* Walks the client itself. Each method carries the route it answers, so the
+* shape of the client is the shape of the proxy and nothing else is needed.
+*/
+const buildNode = (segments, clientNode) => {
+	const node = { key: () => buildPathKey(segments) };
+	for (const routeName of Object.keys(clientNode)) {
+		const child = clientNode[routeName];
+		const childSegments = [...segments, routeName];
+		const route = routeOf(child);
+		if (route) node[routeName] = buildProcedure(childSegments, route, child);
+		else if (child && typeof child === "object") node[routeName] = buildNode(childSegments, child);
+	}
+	return node;
+};
+function buildQueryProxy(client) {
+	return buildNode([], client);
+}
+/**
+* Builds TanStack Query options from a fetch client. Every client method
+* carries the route it answers, so the client is the only argument.
+*
+* ```ts
+* import { useQuery } from '@tanstack/react-query';
+* import { KizunaTanstackQuery } from '@kizunajs/tanstack-query';
+* import { apiClient } from './api-client.js';
+*
+* const api = new KizunaTanstackQuery(apiClient);
+*
+* useQuery(
+*     api.users.listUsers.queryOptions({
+*         input: {
+*             query: {
+*                 page: 1,
+*             },
+*         },
+*     })
+* );
+* ```
+*/
+const KizunaTanstackQuery = buildQueryProxy;
+//#endregion
+export { KizunaTanstackQuery, NonStreamResponseError, UndeclaredResponseError, isNonStreamResponseError, isUndeclaredResponseError };

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@kizunajs/tanstack-query",
+  "version": "2.0.0-beta.0",
+  "description": "TanStack Query client for Kizuna.js",
+  "keywords": [
+    "kizunajs",
+    "typescript",
+    "zod",
+    "openapi",
+    "spec-driven",
+    "type-safe",
+    "rest",
+    "api",
+    "tanstack-query",
+    "react-query",
+    "query-options",
+    "typed-client"
+  ],
+  "license": "MIT",
+  "homepage": "https://kizunajs.com/docs/clients/tanstack-query",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kizunajs/kizuna.git",
+    "directory": "packages/tanstack-query"
+  },
+  "bugs": "https://github.com/kizunajs/kizuna/issues",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "kizuna": {
+    "entries": {
+      ".": "client"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@tanstack/query-core": "^5.69.0",
+    "zod": "^4.0.0",
+    "kizunajs": "2.0.0-beta.0",
+    "@kizunajs/fetch": "2.0.0-beta.0"
+  },
+  "devDependencies": {
+    "@tanstack/query-core": "^5.101.0",
+    "@tanstack/react-query": "^5.101.0",
+    "@tanstack/svelte-query": "^6.1.0",
+    "@tanstack/vue-query": "^5.101.0",
+    "@types/react": "^19.2.18",
+    "react": "^19.2.8",
+    "svelte": "^5.0.0",
+    "tsdown": "^0.21.0",
+    "typescript": "^6.0.3",
+    "vue": "^3.5.0",
+    "zod": "^4.0.0",
+    "kizunajs": "2.0.0-beta.0",
+    "@kizunajs/fetch": "2.0.0-beta.0"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts --format esm,cjs --dts --clean --external kizunajs --external @kizunajs/fetch --external @tanstack/query-core --external zod",
+    "typecheck": "tsc --noEmit"
+  }
+}