@tanstack/solid-query 6.0.0-rc.5 → 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.
@@ -50,6 +50,11 @@ interface HydratedEntry {
50
50
  t: number
51
51
  }
52
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
+ */
53
58
  function metaFrom(state: QueryState<any, any>): MetaState {
54
59
  return {
55
60
  dataUpdateCount: state.dataUpdateCount,
@@ -65,8 +70,10 @@ function metaFrom(state: QueryState<any, any>): MetaState {
65
70
  }
66
71
  }
67
72
 
68
- /** Internal seam: everything the read layer builds, for hooks that extend
69
- * 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
+ */
70
77
  interface BaseQueryLayer<
71
78
  TQueryFnData,
72
79
  TError,
@@ -83,7 +90,15 @@ interface BaseQueryLayer<
83
90
  status: () => 'pending' | 'error' | 'success'
84
91
  }
85
92
 
86
- // 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
+ */
87
102
  export function useBaseQuery<
88
103
  TQueryFnData,
89
104
  TError,
@@ -100,6 +115,16 @@ export function useBaseQuery<
100
115
  return useBaseQueryLayer(options, Observer, queryClient).result
101
116
  }
102
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
+ */
103
128
  export function useBaseQueryLayer<
104
129
  TQueryFnData,
105
130
  TError,
@@ -160,10 +185,15 @@ export function useBaseQueryLayer<
160
185
  * `syncClient` below).
161
186
  */
162
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
163
190
 
164
191
  createRenderEffect(
165
192
  () => defaultedOptions(),
166
- (opts) => observer.setOptions(opts),
193
+ (opts) => {
194
+ lastAppliedHash = opts.queryHash
195
+ observer.setOptions(opts)
196
+ },
167
197
  )
168
198
 
169
199
  /**
@@ -198,10 +228,10 @@ export function useBaseQueryLayer<
198
228
  ownedWrite: true,
199
229
  })
200
230
  const onCacheEvent = (event: { query: { queryHash: string } }) => {
201
- // Match the committed options hash OR the latest computed one (they
202
- // 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.
203
233
  if (
204
- event.query.queryHash === untrack(defaultedOptions).queryHash ||
234
+ event.query.queryHash === lastAppliedHash ||
205
235
  event.query.queryHash === latestHash
206
236
  ) {
207
237
  setVersion((v) => v + 1)
@@ -211,8 +241,10 @@ export function useBaseQueryLayer<
211
241
  let observerSub: (() => void) | null = null
212
242
  let cacheSub: (() => void) | null = null
213
243
  let disposed = false
214
- /** Set once the mount flow decides the observer should be live — a client
215
- * 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
+ */
216
248
  let shouldAttach = false
217
249
  let activeClient = untrack(client)
218
250
  /**
@@ -252,6 +284,7 @@ export function useBaseQueryLayer<
252
284
  * subscription moves to the new cache and the observer is rebuilt against
253
285
  * the new client, so policy fetches and cache events both follow the
254
286
  * client the hook is actually reading.
287
+ * @param c - The `QueryClient` the hook currently resolves to.
255
288
  */
256
289
  const syncClient = (c: QueryClient) => {
257
290
  if (isServer || c === activeClient) return
@@ -293,6 +326,7 @@ export function useBaseQueryLayer<
293
326
  * components go live while later boundaries still stream. No entry
294
327
  * (placeholder queries serialize nothing; SSR errors adopt at their
295
328
  * boundary) attaches immediately and lets mount policy decide.
329
+ * @param entry - The hydration registry entry for this query's hash, if one exists.
296
330
  */
297
331
  const prime = (entry?: Partial<HydratedEntry> | null) => {
298
332
  if (entry != null && typeof entry === 'object' && (entry.t ?? 0) > 0) {
@@ -379,6 +413,7 @@ export function useBaseQueryLayer<
379
413
  * it is a remount: the hydrated component is disposed and re-created as
380
414
  * a client render, and the server value stops holding the DOM. So the
381
415
  * snapshots read the cache, never the signal.
416
+ * @returns The cache entry for the current options.
382
417
  */
383
418
  const lookupQuery = (): Query<
384
419
  TQueryFnData,
@@ -461,7 +496,7 @@ export function useBaseQueryLayer<
461
496
  const opts = defaultedOptions()
462
497
  const q = query()
463
498
  const state = q.state
464
- const select = opts.select as ((d: TQueryData) => TData) | undefined
499
+ const select = opts.select
465
500
  const wrap = (d: any): { value: TData } => ({
466
501
  value: select ? select(d as TQueryData) : (d as TData),
467
502
  })
@@ -562,8 +597,8 @@ export function useBaseQueryLayer<
562
597
  * (and `q.fetch` dedupes into it), and the deferred effect later
563
598
  * sees the identical options object — a no-op diff.
564
599
  */
565
- if (!isServer) observer.setOptions(opts as any)
566
- return chainOnce(q.fetch(opts as any), select, wrap)
600
+ if (!isServer) observer.setOptions(opts)
601
+ return chainOnce(q.fetch(opts), select, wrap)
567
602
  }
568
603
  /**
569
604
  * Disabled, with nothing cached. The three guards above are all
@@ -604,7 +639,7 @@ export function useBaseQueryLayer<
604
639
  * snapshot.
605
640
  */
606
641
  const dataStore = createProjection<{ value: TData }>(
607
- (draft) => computeData(draft.value as TData | undefined),
642
+ (draft) => computeData(draft.value),
608
643
  {} as { value: TData },
609
644
  {
610
645
  key: untrack(() => options().reconcile),
@@ -632,6 +667,7 @@ export function useBaseQueryLayer<
632
667
  * node, which throws the pending read and holds the boundary until
633
668
  * settle. A disabled pending query is served as-is: 'pending' IS its
634
669
  * settled SSR truth, and the client hydrates the identical state.
670
+ * @returns The scalar metadata read live from the query's state.
635
671
  */
636
672
  const serverMeta = (): MetaState => {
637
673
  if (query().state.status === 'pending' && isEnabled()) data()
@@ -691,6 +727,7 @@ export function useBaseQueryLayer<
691
727
  * "a new answer is in flight" during a hold is core's pending probe.
692
728
  * The committed `fetchStatus` covers the first load (where the probe
693
729
  * would see an uninitialized node) and untracked/imperative reads.
730
+ * @returns `true` while a fetch for this query is in flight.
694
731
  */
695
732
  const isFetching = () =>
696
733
  meta.fetchStatus === 'fetching' || isValuePending(() => data())
@@ -789,7 +826,7 @@ export function useBaseQueryLayer<
789
826
  // targets what the UI is currently asking for, not what last
790
827
  // committed.
791
828
  if (!isServer && latestOptions) {
792
- observer.setOptions(latestOptions as any)
829
+ observer.setOptions(latestOptions)
793
830
  }
794
831
  return observer.refetch(refetchOptions)
795
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
  }
@@ -11,25 +11,126 @@ import type {
11
11
  import type { Accessor } from 'solid-js'
12
12
  import type { QueryClient } from './QueryClient'
13
13
 
14
- type MutationStateOptions<TResult = MutationState> = {
14
+ type MutationTypeFromResult<TResult> = [TResult] extends [
15
+ MutationState<
16
+ infer TData,
17
+ infer TError,
18
+ infer TVariables,
19
+ infer TOnMutateResult
20
+ >,
21
+ ]
22
+ ? Mutation<TData, TError, TVariables, TOnMutateResult>
23
+ : Mutation
24
+
25
+ type MutationStateOptions<
26
+ TResult = MutationState,
27
+ TMutation extends Mutation<any, any, any, any> =
28
+ MutationTypeFromResult<TResult>,
29
+ > = {
15
30
  filters?: MutationFilters
16
- select?: (mutation: Mutation) => TResult
31
+ select?: (mutation: TMutation) => TResult
17
32
  }
18
33
 
19
- function getResult<TResult = MutationState>(
34
+ /**
35
+ * Collects the mutations in the cache that match `options.filters`, mapped with `options.select`
36
+ * (or to their state, by default).
37
+ * @param mutationCache - The mutation cache to read.
38
+ * @param options - The `filters` to match and the `select` function to map each mutation with.
39
+ * @returns The selected value of every matching mutation.
40
+ */
41
+ function getResult<
42
+ TResult = MutationState,
43
+ TMutation extends Mutation<any, any, any, any> =
44
+ MutationTypeFromResult<TResult>,
45
+ >(
20
46
  mutationCache: MutationCache,
21
- options: MutationStateOptions<TResult>,
47
+ options: MutationStateOptions<TResult, TMutation>,
22
48
  ): Array<TResult> {
23
49
  return mutationCache
24
50
  .findAll(options.filters)
25
51
  .map(
26
52
  (mutation): TResult =>
27
- (options.select ? options.select(mutation) : mutation.state) as TResult,
53
+ (options.select
54
+ ? options.select(mutation as TMutation)
55
+ : mutation.state) as TResult,
28
56
  )
29
57
  }
30
58
 
31
- export function useMutationState<TResult = MutationState>(
32
- options: Accessor<MutationStateOptions<TResult>> = () => ({}),
59
+ /**
60
+ * `useMutationState` is a primitive that gives you access to all mutations in the `MutationCache`. You can pass
61
+ * `filters` ({@link MutationFilters}) to narrow down your mutations, and `select` to transform the mutation
62
+ * state.
63
+ * @param options - An accessor returning the `filters` to narrow down matched mutations, and an optional
64
+ * `select` to transform the mutation state.
65
+ * @param queryClient - An accessor for a custom `QueryClient`. Otherwise, the one from the nearest context
66
+ * will be used.
67
+ * @returns An accessor for an array of whatever `select` returns for each matching mutation.
68
+ * @example
69
+ * Get all variables of all running mutations:
70
+ * ```tsx
71
+ * import { useMutationState } from '@tanstack/solid-query'
72
+ *
73
+ * function PendingPosts() {
74
+ * const pendingVariables = useMutationState(() => ({
75
+ * filters: { status: 'pending' },
76
+ * select: (mutation) => mutation.state.variables,
77
+ * }))
78
+ *
79
+ * return <>{pendingVariables().length} posts saving...</>
80
+ * }
81
+ * ```
82
+ * @example
83
+ * Get all data for specific mutations via the `mutationKey`:
84
+ * ```tsx
85
+ * import { useMutation, useMutationState } from '@tanstack/solid-query'
86
+ *
87
+ * const mutationKey = ['posts']
88
+ *
89
+ * function Posts() {
90
+ * // Some mutation that we want to get the state for
91
+ * const createPostsMutation = useMutation(() => ({
92
+ * mutationKey,
93
+ * mutationFn: createPosts,
94
+ * }))
95
+ *
96
+ * const savedPosts = useMutationState(() => ({
97
+ * // this mutation key needs to match the mutation key of the given mutation (see above)
98
+ * filters: { mutationKey, status: 'success' },
99
+ * select: (mutation) => mutation.state.data,
100
+ * }))
101
+ *
102
+ * return (
103
+ * <button onClick={() => createPostsMutation.mutate(['New Post'])}>
104
+ * Create post ({savedPosts().length} saved so far)
105
+ * </button>
106
+ * )
107
+ * }
108
+ * ```
109
+ * @example
110
+ * Access the latest successful mutation data via the `mutationKey`. Each invocation of `mutate` adds a new
111
+ * entry to the mutation cache for `gcTime` milliseconds — with the `status: 'success'` filter below, check the
112
+ * last item that `useMutationState` returns to get the latest successful invocation:
113
+ * ```tsx
114
+ * import { useMutationState } from '@tanstack/solid-query'
115
+ *
116
+ * function LatestPost() {
117
+ * const savedPosts = useMutationState(() => ({
118
+ * filters: { mutationKey: ['posts'], status: 'success' },
119
+ * select: (mutation) => mutation.state.data,
120
+ * }))
121
+ *
122
+ * const latestPost = () => savedPosts()[savedPosts().length - 1]
123
+ *
124
+ * return <span>{latestPost()?.title}</span>
125
+ * }
126
+ * ```
127
+ */
128
+ export function useMutationState<
129
+ TResult = MutationState,
130
+ TMutation extends Mutation<any, any, any, any> =
131
+ MutationTypeFromResult<TResult>,
132
+ >(
133
+ options: Accessor<MutationStateOptions<TResult, TMutation>> = () => ({}),
33
134
  queryClient?: Accessor<QueryClient>,
34
135
  ): Accessor<Array<TResult>> {
35
136
  const client = createMemo(() => useQueryClient(queryClient?.()))