TanStack Query
queryOptions, infiniteQueryOptions and mutationOptions for every procedure, streams as queries: typed keys and invalidation by path, for React, Vue, Solid, Svelte and Angular.
ts-bin-rpc/tanstack turns a client into option objects for TanStack Query. It has no hooks of its
own, so it works with every adapter: React, Vue, Solid, Svelte, Angular.
npm install @tanstack/react-queryimport { createClient } from 'ts-bin-rpc/client';import { experimental_streamedQuery } from '@tanstack/react-query';import { createQueryOptions } from 'ts-bin-rpc/tanstack';import type { appRouter } from '../server/router';import { clientProcedures } from './tbr.gen';
export const api = createClient<typeof appRouter>({ url: '/rpc', procedures: clientProcedures });// streamedQuery is needed only for streams as queriesexport const rq = createQueryOptions(api, { streamedQuery: experimental_streamedQuery });function Profile({ id }: { id: number }) { const { data, error } = useQuery(rq.user.get.queryOptions({ id })); // data: User | undefined, error: RpcError | null}rq mirrors the router: rq.user.get is the procedure user.get.
Queries
Section titled “Queries”queryOptions(input, options) returns queryKey and queryFn, plus any TanStack options you pass:
useQuery(rq.user.get.queryOptions({ id }, { staleTime: 60_000 }));useSuspenseQuery(rq.version.queryOptions());queryClient.prefetchQuery(rq.user.list.queryOptions({ role: 'admin' }));
// `select` is typed from the procedure's outputconst names = useQuery(rq.user.list.queryOptions(undefined, { select: (users) => users.map((u) => u.name) }));The input comes first, as in a call. A procedure without input takes the options first:
rq.version.queryOptions({ staleTime }). With an optional input, pass undefined to give options
without one.
queryFn passes the query’s abort signal to the call: an unmounted component or cancelQueries
cancels the request.
Infinite queries
Section titled “Infinite queries”A procedure whose input has a cursor gets infiniteQueryOptions, for useInfiniteQuery. The page
param goes into cursor; you give the rest of the input and say where the next page starts:
// serverpage: async (input: { cursor?: u32; limit?: u32 }): Promise<{ users: User[]; next?: u32 }> => …
// clientconst users = useInfiniteQuery(rq.user.page.infiniteQueryOptions({ limit: 20 }, { getNextPageParam: (last) => last.next, // undefined: no more pages}));users.data?.pages.flatMap((p) => p.users);users.fetchNextPage();The first page goes without a cursor, unless you give initialPageParam; a required cursor makes
it required. The key is [path, input, 'infinite'], apart from the plain query of the same input
and still under pathKey(). rq.user.page.infiniteQueryKey({ limit: 20 }) gives it for
getQueryData.
Streams as queries
Section titled “Streams as queries”A stream’s queryOptions give a query whose data grow as batches arrive, through TanStack’s
streamedQuery. Pass it to createQueryOptions once, as above.
const ticks = useQuery(rq.market.ticks.queryOptions({ symbol: 'BTC' }));ticks.data; // Tick[]: every row so far, one update per batch- The query is
successfrom the first batch and staysfetchinguntil the stream ends. - When the last component using it unmounts, the stream stops, as
sub.stop()does. - An error of the stream becomes the query’s
error. - A refetch starts the stream over:
refetchMode: 'reset'(default) empties the data first,'append'keeps it,'replace'swaps it in when the new stream ends.
A stream that does not end grows without a bound. Fold the batches with reducer and
initialValue to keep what you need:
// the last 100 ticksrq.market.ticks.queryOptions({ symbol: 'BTC' }, { reducer: (rows: Tick[], batch) => [...rows, ...batch].slice(-100), initialValue: [] });// only the last pricerq.market.ticks.queryOptions({ symbol: 'BTC' }, { reducer: (_: number | null, batch) => batch.at(-1)?.price ?? null, initialValue: null });Live state works the same way, and its data are the rows of the state, T[], a new
array on every change, where unchanged rows stay the same objects. order sorts them by key, as in
subscribe; a refetch keeps the old rows until the new snapshot (refetchMode: 'append').
const units = useQuery(rq.game.units.queryOptions({ order: 'asc' }));For a feed where every frame matters or that renders 60 times a second, subscribe is still the
tool: a query renders through the cache, and a stream into a query is for data you would show the
same way as a fetched list.
Mutations
Section titled “Mutations”const deposit = useMutation(rq.account.deposit.mutationOptions({ onSuccess: () => queryClient.invalidateQueries({ queryKey: rq.account.pathKey() }),}));deposit.mutate({ amount: 5 });The input of the procedure is the mutation’s variables. A procedure without input takes none:
mutate().
Keys and invalidation
Section titled “Keys and invalidation”A key is the procedure’s path and its input: [['user', 'get'], { id: 3 }].
rq.user.get.queryKey({ id: 3 }); // [['user', 'get'], { id: 3 }]rq.user.get.pathKey(); // [['user', 'get']]: every inputrq.user.pathKey(); // [['user']]: everything under userrq.pathKey(); // [[]]: every query of this clientTanStack Query matches keys by prefix, so invalidateQueries({ queryKey: rq.user.pathKey() })
refetches user.get and user.list. The path sits in an array of its own, so a key of your app
such as ['user', 5] is not under it.
Keys carry their data type: getQueryData and setQueryData know it.
const user = queryClient.getQueryData(rq.user.get.queryKey({ id: 3 })); // User | undefinedqueryClient.setQueryData(rq.user.get.queryKey({ id: 3 }), (old) => old && { ...old, name: 'Chloé' });Inputs with u64, i64, maps and typed arrays
Section titled “Inputs with u64, i64, maps and typed arrays”TanStack Query hashes keys with JSON.stringify, which throws on a bigint and turns every Map
into {}, so two inputs with different maps would share a cache entry. The options from rq
bring their own queryKeyHashFn, hashKey, which hashes bigints, maps, sets and typed arrays by
their contents (maps and sets in any order of insertion) and everything else as TanStack does.
Methods that take only a key, such as getQueryData, use the client’s default, so set it there if
your inputs have such values:
import { hashKey } from 'ts-bin-rpc/tanstack';
const queryClient = new QueryClient({ defaultOptions: { queries: { queryKeyHashFn: hashKey } } });Views or plain objects
Section titled “Views or plain objects”Responses go into the cache as plain objects (decode: 'eager'). TanStack Query needs them:
- structural sharing keeps unchanged rows the same objects across refetches, so memoized components do not re-render;
- DevTools show their fields;
dehydrate,persistQueryClientand SSR serialize them.
A view is a class instance over the response bytes. For a large response that you read in part, such as a chart over 100 000 points, ask for views:
useQuery(rq.metrics.series.queryOptions({ n: 100_000 }, { tbr: { decode: 'lazy' } }));Structural sharing is then off for that query: views are new values on every fetch. Do not dehydrate or persist such queries.
tbr: { headers } adds headers to the call.
Errors
Section titled “Errors”A failed call rejects with the RpcError, which becomes the query’s
error. TanStack Query retries a failed query three times by default, BAD_INPUT and NOT_FOUND
included. To retry only what can succeed:
new QueryClient({ defaultOptions: { queries: { retry: (n, e) => n < 3 && !(e instanceof RpcError && e.status >= 400 && e.status < 500) }, },});queryOptions, queryKey, infiniteQueryOptions, infiniteQueryKey, mutationOptions and
pathKey are methods of rq. A procedure or a
namespace with one of these names is not reachable through rq; call it on the client.