new KizunaTanstackQuery()

Build TanStack Query options from your routes. See the TanStack Query guide for usage.

pnpm add @kizunajs/tanstack-query@beta

import { 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`	`Args \| SkipToken`	What the client method takes: `{ 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.

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,
    })
);