new KizunaTanstackQuery()
Build TanStack Query options from a Kizuna fetch client.
The TanStack Query client is new and still settling. Its API surface may change while v2 is in beta, so pin your version if you depend on it.
Build TanStack Query options from your routes. See the TanStack Query guide for usage.
pnpm add @kizunajs/tanstack-query@betabun add @kizunajs/tanstack-query@betanpm install @kizunajs/tanstack-query@betaimport { KizunaTanstackQuery } from '@kizunajs/tanstack-query';Parameters
new KizunaTanstackQuery(client: Client): KizunaQueryProxy| Parameter | Type | Description |
|---|---|---|
client | Client | A fetch client, from the generated createClient |
Every client method carries the route it answers, so nothing else is needed: each route's method decides which factories it gets, and its responses decide which statuses are data.
Returns
An object mirroring your route groups.
GET and HEAD routes
| Factory | Description |
|---|---|
queryOptions(options) | For useQuery, useSuspenseQuery, prefetchQuery |
infiniteOptions(options) | For useInfiniteQuery, prefetchInfiniteQuery |
queryKey({ input }) | The query's full key |
infiniteKey({ input }) | The infinite query's full key |
key() | The partial key matching every operation on the route |
call(args) | Calls the route, bypassing the cache |
Every other method
| Factory | Description |
|---|---|
mutationOptions(options) | For useMutation |
mutationKey() | The mutation's full key |
key() | The partial key matching the route |
call(args) | Calls the route |
Routes whose response streams, whatever their method
| Factory | Description |
|---|---|
streamOptions(options) | For useQuery, over experimental_streamedQuery. data is the messages received so far |
streamKey({ input }) | The stream query's full key |
key() | The partial key matching the route |
call(args) | Calls the route, returning the async iterable |
Groups and the root carry key(). Where a route is named the same as a factory, the route wins.
Options
| Option | Type | Description |
|---|---|---|
input | ClientArgs | SkipToken | The route's { params, query, body, headers, fetchOptions }. Optional when every argument is optional. |
| … | TanStack Query options | Passed through untouched |
For infiniteOptions, input is a function of the page parameter. skipToken disables the query. streamOptions also takes refetchMode, 'reset' (default), 'append', or 'replace'.
Query keys
type KizunaQueryKey = readonly [readonly string[], { input?: unknown; type: 'query' | 'infinite' | 'stream' }];
type KizunaPathKey = readonly [readonly string[]];Segments are the route's path through your routes, so api.users.key() prefixes every key under users. fetchOptions is stripped from the input first.
Errors
Declared statuses come back as data. Anything else throws UndeclaredResponseError. A streamed route that answers a declared status other than its stream throws NonStreamResponseError, narrowed with isNonStreamResponseError.
Example
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.listUsers.queryOptions({
input: {
query: {
page: 1,
limit: 10,
},
},
staleTime: 60_000,
})
);