@tanstack/solid-query 6.0.0-rc.4 → 6.0.0-rc.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -4,13 +4,14 @@ import {
4
4
  createProjection,
5
5
  createRenderEffect,
6
6
  createSignal,
7
+ isHydrating,
7
8
  isPending as isValuePending,
8
9
  onCleanup,
9
10
  resolve,
10
11
  runWithOwner,
11
- sharedConfig,
12
12
  untrack,
13
13
  } from 'solid-js'
14
+ import { takeHydrationValue } from '@solidjs/web'
14
15
  import { HYDRATION_KEY_PREFIX, useQueryClient } from './QueryClientProvider'
15
16
  import { useIsRestoring } from './isRestoring'
16
17
  import type { UseBaseQueryOptions, UseBaseQueryResult } from './types'
@@ -49,6 +50,11 @@ interface HydratedEntry {
49
50
  t: number
50
51
  }
51
52
 
53
+ /**
54
+ * Copies the scalar fields of a query's state, leaving out `data` and `fetchMeta`.
55
+ * @param state - The query state to copy from.
56
+ * @returns The scalar metadata.
57
+ */
52
58
  function metaFrom(state: QueryState<any, any>): MetaState {
53
59
  return {
54
60
  dataUpdateCount: state.dataUpdateCount,
@@ -64,8 +70,10 @@ function metaFrom(state: QueryState<any, any>): MetaState {
64
70
  }
65
71
  }
66
72
 
67
- /** Internal seam: everything the read layer builds, for hooks that extend
68
- * the base result (`useInfiniteQuery` pagers ride the same entry). */
73
+ /**
74
+ * Internal seam: everything the read layer builds, for hooks that extend
75
+ * the base result (`useInfiniteQuery` pagers ride the same entry).
76
+ */
69
77
  interface BaseQueryLayer<
70
78
  TQueryFnData,
71
79
  TError,
@@ -82,7 +90,15 @@ interface BaseQueryLayer<
82
90
  status: () => 'pending' | 'error' | 'success'
83
91
  }
84
92
 
85
- // Base Query Function that is used to create the query.
93
+ /**
94
+ * Base Query Function that is used to create the query.
95
+ * @param options - A function that returns the query options.
96
+ * @param Observer - The observer class from query-core (`QueryObserver` or
97
+ * `InfiniteQueryObserver`).
98
+ * @param queryClient - A function that returns a custom `QueryClient`. Otherwise, the one from the
99
+ * nearest context is used.
100
+ * @returns The reactive query result.
101
+ */
86
102
  export function useBaseQuery<
87
103
  TQueryFnData,
88
104
  TError,
@@ -99,6 +115,16 @@ export function useBaseQuery<
99
115
  return useBaseQueryLayer(options, Observer, queryClient).result
100
116
  }
101
117
 
118
+ /**
119
+ * Builds the read layer behind `useBaseQuery` and exposes its internals to hooks that extend it.
120
+ * @param options - A function that returns the query options.
121
+ * @param Observer - The observer class from query-core (`QueryObserver` or
122
+ * `InfiniteQueryObserver`).
123
+ * @param queryClient - A function that returns a custom `QueryClient`. Otherwise, the one from the
124
+ * nearest context is used.
125
+ * @returns The query result, with the observer, the version-tracked query accessor, the defaulted
126
+ * options, and the `isFetching` and `status` accessors.
127
+ */
102
128
  export function useBaseQueryLayer<
103
129
  TQueryFnData,
104
130
  TError,
@@ -159,19 +185,22 @@ export function useBaseQueryLayer<
159
185
  * `syncClient` below).
160
186
  */
161
187
  let observer = untrack(() => new Observer(client(), defaultedOptions()))
188
+ // Fetching and refetching can advance observer.options during a hold.
189
+ let lastAppliedHash = observer.options.queryHash
162
190
 
163
191
  createRenderEffect(
164
192
  () => defaultedOptions(),
165
- (opts) => observer.setOptions(opts),
193
+ (opts) => {
194
+ lastAppliedHash = opts.queryHash
195
+ observer.setOptions(opts)
196
+ },
166
197
  )
167
198
 
168
199
  /**
169
- * `sharedConfig.hydrating` is Solid's own "this component is being
170
- * hydrated" flag, captured at setup. (The server build's sharedConfig
171
- * has no such field — undefined there, and unused.)
200
+ * Solid's own "this component is being hydrated" answer, captured at
201
+ * setup. Always false on the server.
172
202
  */
173
- const hydratedMount =
174
- !isServer && (sharedConfig as { hydrating?: boolean }).hydrating === true
203
+ const hydratedMount = isHydrating()
175
204
 
176
205
  /**
177
206
  * One version signal per hook, bumped by cache events for this query hash.
@@ -199,10 +228,10 @@ export function useBaseQueryLayer<
199
228
  ownedWrite: true,
200
229
  })
201
230
  const onCacheEvent = (event: { query: { queryHash: string } }) => {
202
- // Match the committed options hash OR the latest computed one (they
203
- // diverge during a hold — see `latestHash`).
231
+ // Match the last hash applied by the render effect OR the latest
232
+ // computed one without reading a potentially held memo.
204
233
  if (
205
- event.query.queryHash === untrack(defaultedOptions).queryHash ||
234
+ event.query.queryHash === lastAppliedHash ||
206
235
  event.query.queryHash === latestHash
207
236
  ) {
208
237
  setVersion((v) => v + 1)
@@ -212,8 +241,10 @@ export function useBaseQueryLayer<
212
241
  let observerSub: (() => void) | null = null
213
242
  let cacheSub: (() => void) | null = null
214
243
  let disposed = false
215
- /** Set once the mount flow decides the observer should be live — a client
216
- * swap re-attaches the rebuilt observer iff its predecessor was attached. */
244
+ /**
245
+ * Set once the mount flow decides the observer should be live — a client
246
+ * swap re-attaches the rebuilt observer iff its predecessor was attached.
247
+ */
217
248
  let shouldAttach = false
218
249
  let activeClient = untrack(client)
219
250
  /**
@@ -253,6 +284,7 @@ export function useBaseQueryLayer<
253
284
  * subscription moves to the new cache and the observer is rebuilt against
254
285
  * the new client, so policy fetches and cache events both follow the
255
286
  * client the hook is actually reading.
287
+ * @param c - The `QueryClient` the hook currently resolves to.
256
288
  */
257
289
  const syncClient = (c: QueryClient) => {
258
290
  if (isServer || c === activeClient) return
@@ -294,6 +326,7 @@ export function useBaseQueryLayer<
294
326
  * components go live while later boundaries still stream. No entry
295
327
  * (placeholder queries serialize nothing; SSR errors adopt at their
296
328
  * boundary) attaches immediately and lets mount policy decide.
329
+ * @param entry - The hydration registry entry for this query's hash, if one exists.
297
330
  */
298
331
  const prime = (entry?: Partial<HydratedEntry> | null) => {
299
332
  if (entry != null && typeof entry === 'object' && (entry.t ?? 0) > 0) {
@@ -336,10 +369,6 @@ export function useBaseQueryLayer<
336
369
 
337
370
  if (!isServer) {
338
371
  cacheSub = activeClient.getQueryCache().subscribe(onCacheEvent)
339
- const sc = sharedConfig as unknown as {
340
- has?: (id: string) => boolean
341
- load?: (id: string) => any
342
- }
343
372
  const registryKey =
344
373
  HYDRATION_KEY_PREFIX + untrack(defaultedOptions).queryHash
345
374
  const primeAndAttach = (entry?: Partial<HydratedEntry> | null) => {
@@ -348,24 +377,12 @@ export function useBaseQueryLayer<
348
377
  attach()
349
378
  }
350
379
  const settle = hydratedMount ? primeAndAttach : prime
351
- if (sc.has?.(registryKey)) {
352
- const entry = sc.load!(registryKey)
353
- delete (globalThis as unknown as { _$HY: { r: Record<string, unknown> } })
354
- ._$HY.r[registryKey]
355
- if (entry != null && typeof entry === 'object') {
356
- // Settled serialization refs are stamped `s`/`v`; still-streaming
357
- // ones are plain thenable refs that land with their chunk.
358
- if (entry.s === 1) settle(entry.v)
359
- else if (entry.s === 2) settle()
360
- else if (typeof entry.then === 'function')
361
- entry.then(settle, () => settle())
362
- else settle(entry)
363
- } else {
364
- settle(entry)
365
- }
366
- } else if (hydratedMount) {
367
- primeAndAttach()
368
- }
380
+ const entry = takeHydrationValue<Partial<HydratedEntry> | null>(registryKey)
381
+ if (entry?.status === 'resolved') settle(entry.value)
382
+ else if (entry?.status === 'rejected') settle()
383
+ else if (entry?.status === 'pending')
384
+ entry.promise.then(settle, () => settle())
385
+ else if (hydratedMount) primeAndAttach()
369
386
  if (!hydratedMount) {
370
387
  createRenderEffect(
371
388
  () => isRestoring(),
@@ -383,8 +400,27 @@ export function useBaseQueryLayer<
383
400
  })
384
401
  }
385
402
 
386
- const query = (): Query<TQueryFnData, TError, TQueryData, TQueryKey> => {
387
- version()
403
+ /**
404
+ * The cache entry for the current options, without the `version` read —
405
+ * for the setup-time snapshots below (`metaProjection`'s seed,
406
+ * `mountedAt`), which run in whatever computation is instantiating this
407
+ * component. Under hydration that matters: priming bumps `version`
408
+ * during setup, and Solid holds a write made during the hydration pass —
409
+ * a computation in the pass that reads the written signal, tracked or
410
+ * not, is served the pre-write snapshot and replays at release. For the
411
+ * hook's own derived nodes that replay is the takeover. For the
412
+ * instantiating computation (a boundary's children, a `<Show>` branch)
413
+ * it is a remount: the hydrated component is disposed and re-created as
414
+ * a client render, and the server value stops holding the DOM. So the
415
+ * snapshots read the cache, never the signal.
416
+ * @returns The cache entry for the current options.
417
+ */
418
+ const lookupQuery = (): Query<
419
+ TQueryFnData,
420
+ TError,
421
+ TQueryData,
422
+ TQueryKey
423
+ > => {
388
424
  const c = client()
389
425
  syncClient(c)
390
426
  const cache = c.getQueryCache()
@@ -396,6 +432,10 @@ export function useBaseQueryLayer<
396
432
  if (lastQuery?.queryHash === opts.queryHash) return lastQuery
397
433
  return (lastQuery = cache.build(c, opts as any) as any)
398
434
  }
435
+ const query = (): Query<TQueryFnData, TError, TQueryData, TQueryKey> => {
436
+ version()
437
+ return lookupQuery()
438
+ }
399
439
 
400
440
  const isEnabled = () => {
401
441
  const opts = defaultedOptions()
@@ -456,7 +496,7 @@ export function useBaseQueryLayer<
456
496
  const opts = defaultedOptions()
457
497
  const q = query()
458
498
  const state = q.state
459
- const select = opts.select as ((d: TQueryData) => TData) | undefined
499
+ const select = opts.select
460
500
  const wrap = (d: any): { value: TData } => ({
461
501
  value: select ? select(d as TQueryData) : (d as TData),
462
502
  })
@@ -522,7 +562,7 @@ export function useBaseQueryLayer<
522
562
  * priming; if a fetch is genuinely needed, the post-priming observer
523
563
  * attach issues it outside the window.
524
564
  */
525
- if (!isServer && (sharedConfig as { hydrating?: boolean }).hydrating) {
565
+ if (isHydrating()) {
526
566
  return NEVER
527
567
  }
528
568
  /**
@@ -557,8 +597,8 @@ export function useBaseQueryLayer<
557
597
  * (and `q.fetch` dedupes into it), and the deferred effect later
558
598
  * sees the identical options object — a no-op diff.
559
599
  */
560
- if (!isServer) observer.setOptions(opts as any)
561
- return chainOnce(q.fetch(opts as any), select, wrap)
600
+ if (!isServer) observer.setOptions(opts)
601
+ return chainOnce(q.fetch(opts), select, wrap)
562
602
  }
563
603
  /**
564
604
  * Disabled, with nothing cached. The three guards above are all
@@ -593,15 +633,13 @@ export function useBaseQueryLayer<
593
633
  * first-paint exception in `computeData`.
594
634
  *
595
635
  * Default ('server') hydration semantics: the serialized value owns the
596
- * node for the whole hydration window — server truth holds the document
597
- * while the stream is open — and any cache write that lands mid-stream
598
- * arms the engine's hydration-end takeover (a latched node that
599
- * recomputes has diverged), committing when hydration completes.
600
- * Requires solid-js > 2.0.0-rc.3 (before the takeover fix, a mid-stream
601
- * divergence was lost rather than deferred).
636
+ * node while it hydrates. Outside every still-pending streamed boundary,
637
+ * a cache write commits immediately. Under a pending boundary it waits
638
+ * for that boundary to resume, which hydrates against the server
639
+ * snapshot.
602
640
  */
603
641
  const dataStore = createProjection<{ value: TData }>(
604
- (draft) => computeData(draft.value as TData | undefined),
642
+ (draft) => computeData(draft.value),
605
643
  {} as { value: TData },
606
644
  {
607
645
  key: untrack(() => options().reconcile),
@@ -629,6 +667,7 @@ export function useBaseQueryLayer<
629
667
  * node, which throws the pending read and holds the boundary until
630
668
  * settle. A disabled pending query is served as-is: 'pending' IS its
631
669
  * settled SSR truth, and the client hydrates the identical state.
670
+ * @returns The scalar metadata read live from the query's state.
632
671
  */
633
672
  const serverMeta = (): MetaState => {
634
673
  if (query().state.status === 'pending' && isEnabled()) data()
@@ -644,7 +683,7 @@ export function useBaseQueryLayer<
644
683
  (draft) => {
645
684
  Object.assign(draft, metaFrom(query().state))
646
685
  },
647
- untrack(() => metaFrom(query().state)),
686
+ untrack(() => metaFrom(lookupQuery().state)),
648
687
  )
649
688
  const meta = isServer
650
689
  ? new Proxy({} as MetaState, {
@@ -668,7 +707,7 @@ export function useBaseQueryLayer<
668
707
  },
669
708
  }
670
709
  : untrack(() => {
671
- const state = query().state
710
+ const state = lookupQuery().state
672
711
  return {
673
712
  dataUpdateCount: state.dataUpdateCount,
674
713
  errorUpdateCount: state.errorUpdateCount,
@@ -688,6 +727,7 @@ export function useBaseQueryLayer<
688
727
  * "a new answer is in flight" during a hold is core's pending probe.
689
728
  * The committed `fetchStatus` covers the first load (where the probe
690
729
  * would see an uninitialized node) and untracked/imperative reads.
730
+ * @returns `true` while a fetch for this query is in flight.
691
731
  */
692
732
  const isFetching = () =>
693
733
  meta.fetchStatus === 'fetching' || isValuePending(() => data())
@@ -786,7 +826,7 @@ export function useBaseQueryLayer<
786
826
  // targets what the UI is currently asking for, not what last
787
827
  // committed.
788
828
  if (!isServer && latestOptions) {
789
- observer.setOptions(latestOptions as any)
829
+ observer.setOptions(latestOptions)
790
830
  }
791
831
  return observer.refetch(refetchOptions)
792
832
  }) as QueryObserverResult<TData, TError>['refetch'],
@@ -42,6 +42,12 @@ interface PageParamsOptions {
42
42
  ) => unknown
43
43
  }
44
44
 
45
+ /**
46
+ * Checks whether `getNextPageParam` yields a param for the page after the last cached one.
47
+ * @param options - The options holding `getNextPageParam`.
48
+ * @param data - The cached infinite data, if any.
49
+ * @returns `true` if there is a next page to fetch.
50
+ */
45
51
  function hasNextPage(
46
52
  options: PageParamsOptions,
47
53
  data?: InfiniteData<unknown>,
@@ -58,6 +64,12 @@ function hasNextPage(
58
64
  )
59
65
  }
60
66
 
67
+ /**
68
+ * Checks whether `getPreviousPageParam` yields a param for the page before the first cached one.
69
+ * @param options - The options holding `getPreviousPageParam`.
70
+ * @param data - The cached infinite data, if any.
71
+ * @returns `true` if there is a previous page to fetch.
72
+ */
61
73
  function hasPreviousPage(
62
74
  options: PageParamsOptions,
63
75
  data?: InfiniteData<unknown>,
@@ -90,6 +102,106 @@ export function useInfiniteQuery<
90
102
  >,
91
103
  queryClient?: Accessor<QueryClient>,
92
104
  ): DefinedUseInfiniteQueryResult<TData, TError>
105
+
106
+ /**
107
+ * The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of
108
+ * `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
109
+ * @param options - An accessor returning the {@link UndefinedInitialDataInfiniteOptions} to use — everything
110
+ * you can pass to `useInfiniteQuery`.
111
+ * @param queryClient - An accessor for a custom `QueryClient`. Otherwise, the one from the nearest context
112
+ * will be used.
113
+ * @returns The same properties as `useQuery`, with the addition of `fetchNextPage`, `fetchPreviousPage`,
114
+ * `hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and `isFetchingPreviousPage`. `data.pages` and
115
+ * `data.pageParams` are also added, as long as a `select` doesn't change `TData` away from its default
116
+ * `InfiniteData<TQueryFnData>` shape.
117
+ * @remarks Keep in mind that imperative fetch calls, such as `fetchNextPage`, may interfere with the default
118
+ * refetch behavior, resulting in outdated data. Make sure to call these functions only in response to user
119
+ * actions, or add conditions like `hasNextPage && !isFetching`.
120
+ * @see {@link infiniteQueryOptions} to share these options between `useInfiniteQuery` and imperative APIs like `queryClient.infiniteQuery`.
121
+ * @example
122
+ * Fetching the next page from a "Load More" button click:
123
+ * ```tsx
124
+ * import { For, Match, Switch } from 'solid-js'
125
+ * import { useInfiniteQuery } from '@tanstack/solid-query'
126
+ *
127
+ * function Projects() {
128
+ * const projectsQuery = useInfiniteQuery(() => ({
129
+ * queryKey: ['projects'],
130
+ * queryFn: ({ pageParam }) => fetchProjects(pageParam),
131
+ * initialPageParam: 0,
132
+ * getNextPageParam: (lastPage) => lastPage.nextId,
133
+ * }))
134
+ *
135
+ * return (
136
+ * <Switch>
137
+ * <Match when={projectsQuery.isPending}>Loading...</Match>
138
+ * <Match when={projectsQuery.isError}>Error: {projectsQuery.error.message}</Match>
139
+ * <Match when={projectsQuery.isSuccess}>
140
+ * <ul>
141
+ * <For each={projectsQuery.data.pages}>
142
+ * {(page) => <For each={page.projects}>{(p) => <li>{p.name}</li>}</For>}
143
+ * </For>
144
+ * </ul>
145
+ * <button
146
+ * onClick={() => projectsQuery.fetchNextPage()}
147
+ * disabled={!projectsQuery.hasNextPage || projectsQuery.isFetching}
148
+ * >
149
+ * {projectsQuery.isFetchingNextPage
150
+ * ? 'Loading more...'
151
+ * : projectsQuery.hasNextPage
152
+ * ? 'Load More'
153
+ * : 'Nothing more to load'}
154
+ * </button>
155
+ * </Match>
156
+ * </Switch>
157
+ * )
158
+ * }
159
+ * ```
160
+ * @example
161
+ * Fetching the next page automatically as the user scrolls, using an `IntersectionObserver` on a
162
+ * sentinel element after the list:
163
+ * ```tsx
164
+ * import { For, Match, Switch, createEffect, onCleanup } from 'solid-js'
165
+ * import { useInfiniteQuery } from '@tanstack/solid-query'
166
+ *
167
+ * function Projects() {
168
+ * const projectsQuery = useInfiniteQuery(() => ({
169
+ * queryKey: ['projects'],
170
+ * queryFn: ({ pageParam }) => fetchProjects(pageParam),
171
+ * initialPageParam: 0,
172
+ * getNextPageParam: (lastPage) => lastPage.nextId,
173
+ * }))
174
+ *
175
+ * let sentinelRef: HTMLDivElement | undefined
176
+ *
177
+ * createEffect(() => {
178
+ * if (sentinelRef == null || !projectsQuery.hasNextPage || projectsQuery.isFetching) return
179
+ *
180
+ * const observer = new IntersectionObserver(([entry]) => {
181
+ * if (entry?.isIntersecting) projectsQuery.fetchNextPage()
182
+ * })
183
+ * observer.observe(sentinelRef)
184
+ *
185
+ * onCleanup(() => observer.disconnect())
186
+ * })
187
+ *
188
+ * return (
189
+ * <Switch>
190
+ * <Match when={projectsQuery.isPending}>Loading...</Match>
191
+ * <Match when={projectsQuery.isError}>Error: {projectsQuery.error.message}</Match>
192
+ * <Match when={projectsQuery.isSuccess}>
193
+ * <ul>
194
+ * <For each={projectsQuery.data.pages}>
195
+ * {(page) => <For each={page.projects}>{(p) => <li>{p.name}</li>}</For>}
196
+ * </For>
197
+ * </ul>
198
+ * <div ref={sentinelRef}>{projectsQuery.isFetchingNextPage ? 'Loading more...' : null}</div>
199
+ * </Match>
200
+ * </Switch>
201
+ * )
202
+ * }
203
+ * ```
204
+ */
93
205
  export function useInfiniteQuery<
94
206
  TQueryFnData,
95
207
  TError = DefaultError,
@@ -149,8 +261,11 @@ export function useInfiniteQuery<
149
261
  TPageParam
150
262
  >
151
263
 
152
- /** Committed fetch direction — set when a page fetch dispatches,
153
- * version-tracked through the layer's query accessor. */
264
+ /**
265
+ * Committed fetch direction — set when a page fetch dispatches,
266
+ * version-tracked through the layer's query accessor.
267
+ * @returns `'forward'` or `'backward'` for a page fetch, `undefined` otherwise.
268
+ */
154
269
  const direction = () =>
155
270
  (layer.query().state.fetchMeta as any)?.fetchMore?.direction
156
271
 
@@ -159,10 +274,13 @@ export function useInfiniteQuery<
159
274
  const infiniteData = () =>
160
275
  layer.query().state.data as InfiniteData<unknown> | undefined
161
276
 
162
- const isFetchingNextPage = () =>
163
- layer.isFetching() && direction() === 'forward'
164
- const isFetchingPreviousPage = () =>
165
- layer.isFetching() && direction() === 'backward'
277
+ // Read `direction()` before `isFetching()` to work around solidjs/solid#4966.
278
+ const isFetchingPage = (expected: 'forward' | 'backward') => {
279
+ const current = direction()
280
+ return layer.isFetching() && current === expected
281
+ }
282
+ const isFetchingNextPage = () => isFetchingPage('forward')
283
+ const isFetchingPreviousPage = () => isFetchingPage('backward')
166
284
  const isError = () => layer.status() === 'error'
167
285
 
168
286
  // The base result's getters transfer as-is; the infinite surface layers
@@ -207,11 +325,15 @@ export function useInfiniteQuery<
207
325
  enumerable: true,
208
326
  },
209
327
  isRefetching: {
210
- get: () =>
211
- layer.isFetching() &&
212
- layer.status() !== 'pending' &&
213
- !isFetchingNextPage() &&
214
- !isFetchingPreviousPage(),
328
+ get: () => {
329
+ const current = direction()
330
+ return (
331
+ layer.isFetching() &&
332
+ layer.status() !== 'pending' &&
333
+ current !== 'forward' &&
334
+ current !== 'backward'
335
+ )
336
+ },
215
337
  enumerable: true,
216
338
  },
217
339
  isRefetchError: {
@@ -5,8 +5,28 @@ import type { QueryFilters } from '@tanstack/query-core'
5
5
  import type { QueryClient } from './QueryClient'
6
6
  import type { Accessor } from 'solid-js'
7
7
 
8
+ /**
9
+ * The `useIsFetching` primitive returns the `number` of the queries that your application is loading or fetching
10
+ * in the background (useful for app-wide loading indicators).
11
+ * @param filters - An accessor returning the {@link QueryFilters} to narrow down the matched queries.
12
+ * @param queryClient - An accessor for a custom `QueryClient`. Otherwise, the one from the nearest context
13
+ * will be used.
14
+ * @returns An accessor for the `number` of the queries that your application is currently loading or fetching
15
+ * in the background.
16
+ * @example
17
+ * ```tsx
18
+ * import { useIsFetching } from '@tanstack/solid-query'
19
+ *
20
+ * function GlobalLoadingIndicator() {
21
+ * // How many queries matching the posts prefix are fetching?
22
+ * const isFetchingPosts = useIsFetching(() => ({ queryKey: ['posts'] }))
23
+ *
24
+ * return isFetchingPosts() > 0 ? <span>Loading posts...</span> : null
25
+ * }
26
+ * ```
27
+ */
8
28
  export function useIsFetching(
9
- filters?: Accessor<QueryFilters>,
29
+ filters?: Accessor<Omit<QueryFilters, 'fetchStatus'>>,
10
30
  queryClient?: Accessor<QueryClient>,
11
31
  ): Accessor<number> {
12
32
  const client = createMemo(() => useQueryClient(queryClient?.()))
@@ -5,8 +5,27 @@ import type { MutationFilters } from '@tanstack/query-core'
5
5
  import type { QueryClient } from './QueryClient'
6
6
  import type { Accessor } from 'solid-js'
7
7
 
8
+ /**
9
+ * The `useIsMutating` primitive returns the `number` of mutations that your application currently has `pending`
10
+ * (useful for app-wide loading indicators).
11
+ * @param filters - An accessor returning the {@link MutationFilters} to narrow down the matched mutations.
12
+ * @param queryClient - An accessor for a custom `QueryClient`. Otherwise, the one from the nearest context
13
+ * will be used.
14
+ * @returns An accessor for the `number` of the mutations that your application currently has `pending`.
15
+ * @example
16
+ * ```tsx
17
+ * import { useIsMutating } from '@tanstack/solid-query'
18
+ *
19
+ * function PostsMutatingIndicator() {
20
+ * // How many mutations matching the posts prefix are in progress?
21
+ * const isMutatingPosts = useIsMutating(() => ({ mutationKey: ['posts'] }))
22
+ *
23
+ * return isMutatingPosts() > 0 ? <span>Saving posts...</span> : null
24
+ * }
25
+ * ```
26
+ */
8
27
  export function useIsMutating(
9
- filters?: Accessor<MutationFilters>,
28
+ filters?: Accessor<Omit<MutationFilters, 'status'>>,
10
29
  queryClient?: Accessor<QueryClient>,
11
30
  ): Accessor<number> {
12
31
  const client = createMemo(() => useQueryClient(queryClient?.()))
@@ -50,6 +50,8 @@ const IDLE: SettledState<any, any, any> = {
50
50
  * has no interactive paint to keep atomic. Yielded thenable values are
51
51
  * awaited and their results passed back in, matching what `action` does
52
52
  * minus the transition bookkeeping.
53
+ * @param iterator - The mutation generator to run to completion.
54
+ * @returns A promise for the generator's return value.
53
55
  */
54
56
  async function drain<TReturn>(
55
57
  iterator: AsyncGenerator<unknown, TReturn, unknown>,
@@ -89,6 +91,10 @@ async function drain<TReturn>(
89
91
  * branch from surfacing as an unhandled rejection. The
90
92
  * `mutate`/`mutateAsync` split existed for React's callback-vs-promise
91
93
  * error routing; it has no space here.
94
+ * @param options - An accessor returning the {@link UseMutationOptions} to use.
95
+ * @param queryClient - An accessor for a custom `QueryClient`. Otherwise, the one from the nearest context
96
+ * will be used.
97
+ * @returns The mutation state, with `mutate` to run the mutation and `reset` to clear its state.
92
98
  */
93
99
  export function useMutation<
94
100
  TData = unknown,
@@ -129,6 +135,13 @@ export function useMutation<
129
135
  unsubscribeFlight = null
130
136
  })
131
137
 
138
+ /**
139
+ * Runs one mutation: the flight overlay and `onMutate`, the fetch through query-core, then the
140
+ * options-level callbacks and the durable settle.
141
+ * @param variables - The variables passed to `mutate`.
142
+ * @returns The data the mutation resolved with.
143
+ * @yields {unknown} The promises the surrounding `action` (or `drain` on the server) awaits.
144
+ */
132
145
  async function* run(
133
146
  variables: TVariables,
134
147
  ): AsyncGenerator<unknown, TData, unknown> {
@@ -154,7 +167,7 @@ export function useMutation<
154
167
  onSuccess: undefined,
155
168
  onError: undefined,
156
169
  onSettled: undefined,
157
- }) as unknown as Mutation<TData, TError, TVariables>
170
+ })
158
171
  activeMutation = mutation
159
172
  if (!isServer) {
160
173
  // A rapid re-mutate replaces the previous flight's listener.
@@ -180,6 +193,8 @@ export function useMutation<
180
193
  * their own failures are reported as unhandled rejections but never
181
194
  * displace `error`, then the durable error state commits and the
182
195
  * mutate promise rejects with `error`.
196
+ * @param error - The error the mutation or one of its success callbacks failed with.
197
+ * @yields {unknown} The promises returned by `onError` and `onSettled`.
183
198
  */
184
199
  // Must be an async generator: async `yield` awaits its value in place,
185
200
  // so a rejecting callback promise throws at the yield inside the local
@@ -277,8 +292,8 @@ export function useMutation<
277
292
  TError,
278
293
  TVariables,
279
294
  TOnMutateResult
280
- > = (variables) => {
281
- const promise = invoke(variables)
295
+ > = (...args) => {
296
+ const promise = invoke(args[0] as TVariables)
282
297
  // Errors also land in reactive state; ignoring the promise must not
283
298
  // surface an unhandled rejection. Awaiting it still rejects.
284
299
  promise.catch(noop)
@@ -354,10 +369,5 @@ export function useMutation<
354
369
  },
355
370
  }
356
371
 
357
- return result as unknown as UseMutationResult<
358
- TData,
359
- TError,
360
- TVariables,
361
- TOnMutateResult
362
- >
372
+ return result
363
373
  }