Skip to content
Source
Sign inSign up
TanStack/query
Open History to see the last commit

streamedQuery.ts

151 lines4.8 KB

1import { addConsumeAwareSignal, fetchSignal } from './utils'
2import type {
3 OmitKeyof,
4 QueryFunction,
5 QueryFunctionContext,
6 QueryKey,
7} from './types'
8import type { FetchSignalContext } from './utils'
9​
10type BaseStreamedQueryParams<TQueryFnData, TQueryKey extends QueryKey> = {
11 /** The function that returns an `AsyncIterable` to stream data from. */
12 streamFn: (
13 context: QueryFunctionContext<TQueryKey>,
14 ) => AsyncIterable<TQueryFnData> | Promise<AsyncIterable<TQueryFnData>>
15 /**
16 * Defines how refetches are handled.
17 * - `'reset'` (default): erases all data and puts the query back into `pending` state.
18 * - `'append'`: appends new data to the existing data.
19 * - `'replace'`: writes all data to the cache once the stream ends.
20 */
21 refetchMode?: 'append' | 'reset' | 'replace'
23​
24type SimpleStreamedQueryParams<
25 TQueryFnData,
26 TQueryKey extends QueryKey,
27> = BaseStreamedQueryParams<TQueryFnData, TQueryKey> & {
28 reducer?: never
29 initialValue?: never
31​
32type ReducibleStreamedQueryParams<
33 TQueryFnData,
34 TData,
35 TQueryKey extends QueryKey,
36> = BaseStreamedQueryParams<TQueryFnData, TQueryKey> & {
37 /**
38 * Reduces streamed chunks into the final data shape. Required whenever `TData` is not an
39 * array, since there is no default way to accumulate non-array chunks.
40 */
41 reducer: (acc: TData, chunk: TQueryFnData) => TData
42 /**
43 * The value used while the first chunk is being fetched, and returned if the stream yields no
44 * values. Required together with a custom `reducer`.
45 */
46 initialValue: TData
48​
49type StreamedQueryParams<TQueryFnData, TData, TQueryKey extends QueryKey> =
50 | SimpleStreamedQueryParams<TQueryFnData, TQueryKey>
51 | ReducibleStreamedQueryParams<TQueryFnData, TData, TQueryKey>
52​
53/**
54 * This is a helper function to create a query function that streams data from an AsyncIterable.
55 * Data will be an Array of all the chunks received.
56 * The query will be in a 'pending' state until the first chunk of data is received, but will go to 'success' after that.
57 * The query will stay in fetchStatus 'fetching' until the stream ends.
58 * Explicit cancellation stops further cache updates, even if `streamFn` does not read `signal`.
59 * If `streamFn` does not read `signal`, the stream continues after the last observer unsubscribes.
60 * @param options - The `streamFn` that returns an AsyncIterable to stream data from, and the optional
61 * `refetchMode`, `reducer`, and `initialValue` options.
62 * @returns A query function to pass as `queryFn`.
63 * @example
64 * ```ts
65 * await queryClient.query({
66 * queryKey: ['data'],
67 * queryFn: streamedQuery({
68 * streamFn: fetchDataInChunks,
69 * }),
70 * })
71 * ```
72 */
73export function streamedQuery<
74 TQueryFnData = unknown,
75 TData = Array<TQueryFnData>,
76 TQueryKey extends QueryKey = QueryKey,
77>({
78 streamFn,
79 refetchMode = 'reset',
80 reducer = (items, chunk) =>
81 [...(items as Array<TQueryFnData>), chunk] as TData,
82 initialValue = [] as TData,
83}: StreamedQueryParams<TQueryFnData, TData, TQueryKey>): QueryFunction<
84 TData,
85 TQueryKey
86> {
87 return async (context) => {
88 const signalContext: FetchSignalContext = context
89 const signal = signalContext[fetchSignal]
90 if (signal?.aborted) {
91 return initialValue
92 }
93​
94 const query = context.client
95 .getQueryCache()
96 .find({ queryKey: context.queryKey, exact: true })
97 const isRefetch = !!query && query.isFetched()
98 if (isRefetch && refetchMode === 'reset') {
99 query.setState({
100 ...query.resetState,
101 fetchStatus: 'fetching',
102 })
103 }
104​
105 let result = initialValue
106​
107 let cancelled = false as boolean
108 const streamFnContext = addConsumeAwareSignal<
109 OmitKeyof<typeof context, 'signal'>
110 >(
111 {
112 client: context.client,
113 meta: context.meta,
114 queryKey: context.queryKey,
115 pageParam: context.pageParam,
116 direction: context.direction,
117 },
118 () => context.signal,
119 () => (cancelled = true),
120 signal,
121 )
122​
123 const isStreamInactive = () => cancelled || signal?.aborted === true
124 const stream = await streamFn(streamFnContext)
125​
126 const isReplaceRefetch = isRefetch && refetchMode === 'replace'
127​
128 for await (const chunk of stream) {
129 if (isStreamInactive()) {
130 break
131 }
132​
133 if (isReplaceRefetch) {
134 // don't append to the cache directly when replace-refetching
135 result = reducer(result, chunk)
136 } else {
137 context.client.setQueryData<TData>(context.queryKey, (prev) =>
138 reducer(prev === undefined ? initialValue : prev, chunk),
139 )
140 }
141 }
142​
143 // finalize result: replace-refetching needs to write to the cache
144 if (isReplaceRefetch && !isStreamInactive()) {
145 context.client.setQueryData<TData>(context.queryKey, result)
146 }
147​
148 const data = context.client.getQueryData<TData>(context.queryKey)
149 return data === undefined ? initialValue : data
150 }