new KizunaTanstackQuery()

Beta

The TanStack Query client is new and still settling. Its API surface may change before v2, so pin your version if you depend on it.

Build TanStack Query options from a contract. See the TanStack Query guide for usage.

pnpm add @ts-kizuna/tanstack-query

bun add @ts-kizuna/tanstack-query

npm install @ts-kizuna/tanstack-query

import { KizunaTanstackQuery } from '@ts-kizuna/tanstack-query';

Parameters

new KizunaTanstackQuery(contract: Contract, client: Client): KizunaQueryProxy

Parameter	Type	Description
`contract`	`Contract`	The contract from `k.contract`
`client`	`Client`	A client from `new KizunaClient()`, built from that contract

The contract is needed as well as the client: each route's method decides which factories it gets, and its responses decide which statuses are data.

Returns

An object mirroring the contract's 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

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.

Query keys

type KizunaQueryKey = readonly [readonly string[], { input?: unknown; type: 'query' | 'infinite' }];
type KizunaPathKey = readonly [readonly string[]];

Segments are the route's path through the contract, 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.

Example

import { useQuery } from '@tanstack/react-query';
import { KizunaClient } from '@ts-kizuna/fetch';
import { KizunaTanstackQuery } from '@ts-kizuna/tanstack-query';
import { contract } from '@/contract';

const apiClient = new KizunaClient(contract, {
    baseUrl: 'http://localhost:3000',
});

const api = new KizunaTanstackQuery(contract, apiClient);

const { data } = useQuery(
    api.users.listUsers.queryOptions({
        input: {
            query: {
                page: 1,
                limit: 10,
            },
        },
        staleTime: 60_000,
    })
);