@tanstack/solid-query 5.102.8 → 5.103.0

package/src/useInfiniteQuery.ts

@@ -19,6 +19,54 @@ import type {
   UndefinedInitialDataInfiniteOptions,
 } from './infiniteQueryOptions'
 
+/**
+ * The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of
+ * `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
+ *
+ * This overload is selected when `initialData` is set.
+ *
+ * @remarks Keep in mind that imperative fetch calls, such as `fetchNextPage`, may interfere with the default
+ * refetch behavior, resulting in outdated data. Make sure to call these functions only in response to user
+ * actions, or add conditions like `hasNextPage && !isFetching`.
+ * @see {@link infiniteQueryOptions} to share these options between `useInfiniteQuery` and imperative APIs like `queryClient.infiniteQuery`.
+ * @param options - An accessor returning the {@link DefinedInitialDataInfiniteOptions} to use — everything you
+ * can pass to `useInfiniteQuery`, with `initialData` set.
+ * @param queryClient - An accessor for a custom `QueryClient`. Otherwise, the one from the nearest context
+ * will be used.
+ * @returns The same properties as `useQuery`, with the addition of `fetchNextPage`, `fetchPreviousPage`,
+ * `hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and `isFetchingPreviousPage`. `data.pages` and
+ * `data.pageParams` are also added, as long as a `select` doesn't change `TData` away from its default
+ * `InfiniteData<TQueryFnData>` shape.
+ *
+ * @example
+ * ```tsx
+ * import { For } from 'solid-js'
+ * import { useInfiniteQuery } from '@tanstack/solid-query'
+ *
+ * function Projects() {
+ *   // `projectsQuery.data` is never `undefined`, thanks to `initialData` — even if a refetch fails, so the
+ *   // list stays visible alongside the error.
+ *   const projectsQuery = useInfiniteQuery(() => ({
+ *     queryKey: ['projects'],
+ *     queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *     initialPageParam: 0,
+ *     getNextPageParam: (lastPage) => lastPage.nextId,
+ *     initialData: { pages: [], pageParams: [] },
+ *   }))
+ *
+ *   return (
+ *     <div>
+ *       {projectsQuery.isError ? <span>Error: {projectsQuery.error.message}</span> : null}
+ *       <ul>
+ *         <For each={projectsQuery.data.pages}>
+ *           {(page) => <For each={page.projects}>{(p) => <li>{p.name}</li>}</For>}
+ *         </For>
+ *       </ul>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
 export function useInfiniteQuery<
   TQueryFnData,
   TError = DefaultError,
@@ -35,6 +83,109 @@ export function useInfiniteQuery<
   >,
   queryClient?: Accessor<QueryClient>,
 ): DefinedUseInfiniteQueryResult<TData, TError>
+
+/**
+ * The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of
+ * `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
+ *
+ * @remarks Keep in mind that imperative fetch calls, such as `fetchNextPage`, may interfere with the default
+ * refetch behavior, resulting in outdated data. Make sure to call these functions only in response to user
+ * actions, or add conditions like `hasNextPage && !isFetching`.
+ * @see {@link infiniteQueryOptions} to share these options between `useInfiniteQuery` and imperative APIs like `queryClient.infiniteQuery`.
+ * @param options - An accessor returning the {@link UndefinedInitialDataInfiniteOptions} to use — everything
+ * you can pass to `useInfiniteQuery`.
+ * @param queryClient - An accessor for a custom `QueryClient`. Otherwise, the one from the nearest context
+ * will be used.
+ * @returns The same properties as `useQuery`, with the addition of `fetchNextPage`, `fetchPreviousPage`,
+ * `hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and `isFetchingPreviousPage`. `data.pages` and
+ * `data.pageParams` are also added, as long as a `select` doesn't change `TData` away from its default
+ * `InfiniteData<TQueryFnData>` shape.
+ *
+ * @example
+ * Fetching the next page from a "Load More" button click:
+ * ```tsx
+ * import { For, Match, Switch } from 'solid-js'
+ * import { useInfiniteQuery } from '@tanstack/solid-query'
+ *
+ * function Projects() {
+ *   const projectsQuery = useInfiniteQuery(() => ({
+ *     queryKey: ['projects'],
+ *     queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *     initialPageParam: 0,
+ *     getNextPageParam: (lastPage) => lastPage.nextId,
+ *   }))
+ *
+ *   return (
+ *     <Switch>
+ *       <Match when={projectsQuery.isPending}>Loading...</Match>
+ *       <Match when={projectsQuery.isError}>Error: {projectsQuery.error.message}</Match>
+ *       <Match when={projectsQuery.isSuccess}>
+ *         <ul>
+ *           <For each={projectsQuery.data.pages}>
+ *             {(page) => <For each={page.projects}>{(p) => <li>{p.name}</li>}</For>}
+ *           </For>
+ *         </ul>
+ *         <button
+ *           onClick={() => projectsQuery.fetchNextPage()}
+ *           disabled={!projectsQuery.hasNextPage || projectsQuery.isFetching}
+ *         >
+ *           {projectsQuery.isFetchingNextPage
+ *             ? 'Loading more...'
+ *             : projectsQuery.hasNextPage
+ *               ? 'Load More'
+ *               : 'Nothing more to load'}
+ *         </button>
+ *       </Match>
+ *     </Switch>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * Fetching the next page automatically as the user scrolls, using an `IntersectionObserver` on a
+ * sentinel element after the list:
+ * ```tsx
+ * import { For, Match, Switch, createEffect, onCleanup } from 'solid-js'
+ * import { useInfiniteQuery } from '@tanstack/solid-query'
+ *
+ * function Projects() {
+ *   const projectsQuery = useInfiniteQuery(() => ({
+ *     queryKey: ['projects'],
+ *     queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *     initialPageParam: 0,
+ *     getNextPageParam: (lastPage) => lastPage.nextId,
+ *   }))
+ *
+ *   let sentinelRef: HTMLDivElement | undefined
+ *
+ *   createEffect(() => {
+ *     if (sentinelRef == null || !projectsQuery.hasNextPage || projectsQuery.isFetching) return
+ *
+ *     const observer = new IntersectionObserver(([entry]) => {
+ *       if (entry?.isIntersecting) projectsQuery.fetchNextPage()
+ *     })
+ *     observer.observe(sentinelRef)
+ *
+ *     onCleanup(() => observer.disconnect())
+ *   })
+ *
+ *   return (
+ *     <Switch>
+ *       <Match when={projectsQuery.isPending}>Loading...</Match>
+ *       <Match when={projectsQuery.isError}>Error: {projectsQuery.error.message}</Match>
+ *       <Match when={projectsQuery.isSuccess}>
+ *         <ul>
+ *           <For each={projectsQuery.data.pages}>
+ *             {(page) => <For each={page.projects}>{(p) => <li>{p.name}</li>}</For>}
+ *           </For>
+ *         </ul>
+ *         <div ref={sentinelRef}>{projectsQuery.isFetchingNextPage ? 'Loading more...' : null}</div>
+ *       </Match>
+ *     </Switch>
+ *   )
+ * }
+ * ```
+ */
 export function useInfiniteQuery<
   TQueryFnData,
   TError = DefaultError,

package/src/useIsFetching.ts

@@ -4,6 +4,28 @@ import type { QueryFilters } from '@tanstack/query-core'
 import type { QueryClient } from './QueryClient'
 import type { Accessor } from 'solid-js'
 
+/**
+ * The `useIsFetching` hook returns the `number` of the queries that your application is loading or fetching
+ * in the background (useful for app-wide loading indicators).
+ *
+ * @param filters - An accessor returning the {@link QueryFilters} to narrow down the matched queries.
+ * @param queryClient - An accessor for a custom `QueryClient`. Otherwise, the one from the nearest context
+ * will be used.
+ * @returns An accessor for the `number` of the queries that your application is currently loading or fetching
+ * in the background.
+ *
+ * @example
+ * ```tsx
+ * import { useIsFetching } from '@tanstack/solid-query'
+ *
+ * function GlobalLoadingIndicator() {
+ *   // How many queries matching the posts prefix are fetching?
+ *   const isFetchingPosts = useIsFetching(() => ({ queryKey: ['posts'] }))
+ *
+ *   return isFetchingPosts() > 0 ? <span>Loading posts...</span> : null
+ * }
+ * ```
+ */
 export function useIsFetching(
   filters?: Accessor<QueryFilters>,
   queryClient?: Accessor<QueryClient>,

package/src/useIsMutating.ts

@@ -4,6 +4,27 @@ import type { MutationFilters } from '@tanstack/query-core'
 import type { QueryClient } from './QueryClient'
 import type { Accessor } from 'solid-js'
 
+/**
+ * The `useIsMutating` hook returns the `number` of mutations that your application currently has `pending`
+ * (useful for app-wide loading indicators).
+ *
+ * @param filters - An accessor returning the {@link MutationFilters} to narrow down the matched mutations.
+ * @param queryClient - An accessor for a custom `QueryClient`. Otherwise, the one from the nearest context
+ * will be used.
+ * @returns An accessor for the `number` of the mutations that your application currently has `pending`.
+ *
+ * @example
+ * ```tsx
+ * import { useIsMutating } from '@tanstack/solid-query'
+ *
+ * function PostsMutatingIndicator() {
+ *   // How many mutations matching the posts prefix are in progress?
+ *   const isMutatingPosts = useIsMutating(() => ({ mutationKey: ['posts'] }))
+ *
+ *   return isMutatingPosts() > 0 ? <span>Saving posts...</span> : null
+ * }
+ * ```
+ */
 export function useIsMutating(
   filters?: Accessor<MutationFilters>,
   queryClient?: Accessor<QueryClient>,

package/src/useMutation.ts

@@ -11,7 +11,165 @@ import type {
 } from './types'
 import type { Accessor } from 'solid-js'
 
-// HOOK
+/**
+ * @param options - An accessor returning the {@link UseMutationOptions} to use.
+ * @param queryClient - An accessor for a custom `QueryClient`. Otherwise, the one from the nearest context
+ * will be used.
+ * @returns `mutate`/`mutateAsync` also accept per-call `onSuccess`/`onError`/`onSettled` callbacks as a second
+ * argument, useful for triggering call-site side effects (e.g. navigation) without coupling them to the shared
+ * mutation definition. Hook-level callbacks (passed to `options`) fire for every mutation; per-call callbacks
+ * fire only for the latest call you've made, and only while the component is still mounted — unmounting before
+ * the mutation settles removes the subscription and prevents them from firing.
+ *
+ * @example
+ * ```tsx
+ * import { useMutation, useQueryClient } from '@tanstack/solid-query'
+ *
+ * function TodoItem(props: { id: number }) {
+ *   const queryClient = useQueryClient()
+ *
+ *   const deleteTodoMutation = useMutation(() => ({
+ *     mutationFn: deleteTodo,
+ *     onSuccess: () => {
+ *       queryClient.invalidateQueries({ queryKey: ['todos'] })
+ *     },
+ *   }))
+ *
+ *   return (
+ *     <button onClick={() => deleteTodoMutation.mutate({ id: props.id })} disabled={deleteTodoMutation.isPending}>
+ *       Delete
+ *     </button>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * Rendering the mutation's own state, rather than just firing it off:
+ * ```tsx
+ * import { Match, Switch } from 'solid-js'
+ * import { useMutation, useQueryClient } from '@tanstack/solid-query'
+ *
+ * function AddTodo() {
+ *   const queryClient = useQueryClient()
+ *
+ *   const addMutation = useMutation(() => ({
+ *     mutationFn: addTodo,
+ *     onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
+ *   }))
+ *
+ *   return (
+ *     <Switch fallback={<button onClick={() => addMutation.mutate('Item')}>Add</button>}>
+ *       <Match when={addMutation.isPending}>Adding todo...</Match>
+ *       <Match when={addMutation.isError}>
+ *         <div>An error occurred: {addMutation.error?.message}</div>
+ *         <button onClick={() => addMutation.mutate('Item')}>Add</button>
+ *       </Match>
+ *     </Switch>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * Optimistic update via `onMutate`, rolling back on `onError`:
+ * ```tsx
+ * import { useMutation, useQueryClient } from '@tanstack/solid-query'
+ *
+ * function AddTodo() {
+ *   const queryClient = useQueryClient()
+ *
+ *   const addMutation = useMutation(() => ({
+ *     mutationFn: addTodo,
+ *     onMutate: async (newTodo) => {
+ *       await queryClient.cancelQueries({ queryKey: ['todos'] })
+ *       const previousTodos = queryClient.getQueryData<Array<string>>(['todos'])
+ *
+ *       queryClient.setQueryData<Array<string>>(['todos'], (old) => [
+ *         ...(old ?? []),
+ *         newTodo,
+ *       ])
+ *
+ *       // Passed to `onError` as `onMutateResult` if the mutation fails.
+ *       return { previousTodos }
+ *     },
+ *     onError: (_err, _newTodo, onMutateResult) => {
+ *       queryClient.setQueryData(['todos'], onMutateResult?.previousTodos)
+ *     },
+ *     onSettled: () => {
+ *       queryClient.invalidateQueries({ queryKey: ['todos'] })
+ *     },
+ *   }))
+ *
+ *   return (
+ *     <button onClick={() => addMutation.mutate('Item')}>Add</button>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * Callbacks passed per call to `mutate` only fire for the last call — `mutateAsync` gives you a
+ * promise per call instead, so you can wait for all of them when they succeed:
+ * ```tsx
+ * import { useMutation, useQueryClient } from '@tanstack/solid-query'
+ *
+ * function AddTodos() {
+ *   const queryClient = useQueryClient()
+ *
+ *   const addMutation = useMutation(() => ({
+ *     mutationFn: addTodo,
+ *     onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
+ *   }))
+ *
+ *   async function handleAddAll(todos: Array<string>) {
+ *     try {
+ *       await Promise.all(todos.map((todo) => addMutation.mutateAsync(todo)))
+ *     } catch (error) {
+ *       console.error('Failed to add todos:', error)
+ *     }
+ *   }
+ *
+ *   return (
+ *     <button onClick={() => handleAddAll(['Todo 1', 'Todo 2', 'Todo 3'])}>
+ *       Add all
+ *     </button>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * If some of the mutations above can fail independently of the others, and you want to know which ones
+ * did — rather than losing that information the moment the first one rejects — swap `Promise.all` for
+ * `Promise.allSettled`:
+ * ```tsx
+ * import { useMutation, useQueryClient } from '@tanstack/solid-query'
+ *
+ * function AddTodos() {
+ *   const queryClient = useQueryClient()
+ *
+ *   const addMutation = useMutation(() => ({
+ *     mutationFn: addTodo,
+ *     onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
+ *   }))
+ *
+ *   async function handleAddAll(todos: Array<string>) {
+ *     const addResults = await Promise.allSettled(
+ *       todos.map((todo) => addMutation.mutateAsync(todo)),
+ *     )
+ *
+ *     addResults.forEach((addResult, index) => {
+ *       if (addResult.status === 'rejected') {
+ *         console.error(`Failed to add "${todos[index]}":`, addResult.reason)
+ *       }
+ *     })
+ *   }
+ *
+ *   return (
+ *     <button onClick={() => handleAddAll(['Todo 1', 'Todo 2', 'Todo 3'])}>
+ *       Add all
+ *     </button>
+ *   )
+ * }
+ * ```
+ */
 export function useMutation<
   TData = unknown,
   TError = DefaultError,

package/src/useMutationState.ts

@@ -48,6 +48,79 @@ function getResult<
     )
 }
 
+/**
+ * `useMutationState` is a hook that gives you access to all mutations in the `MutationCache`. You can pass
+ * `filters` ({@link MutationFilters}) to narrow down your mutations, and `select` to transform the mutation
+ * state.
+ *
+ * @param options - An accessor returning the `filters` to narrow down matched mutations, and an optional
+ * `select` to transform the mutation state.
+ * @param queryClient - An accessor for a custom `QueryClient`. Otherwise, the one from the nearest context
+ * will be used.
+ * @returns An accessor for an array of whatever `select` returns for each matching mutation.
+ *
+ * @example
+ * Get all variables of all running mutations:
+ * ```tsx
+ * import { useMutationState } from '@tanstack/solid-query'
+ *
+ * function PendingPosts() {
+ *   const pendingVariables = useMutationState(() => ({
+ *     filters: { status: 'pending' },
+ *     select: (mutation) => mutation.state.variables,
+ *   }))
+ *
+ *   return <>{pendingVariables().length} posts saving...</>
+ * }
+ * ```
+ *
+ * @example
+ * Get all data for specific mutations via the `mutationKey`:
+ * ```tsx
+ * import { useMutation, useMutationState } from '@tanstack/solid-query'
+ *
+ * const mutationKey = ['posts']
+ *
+ * function Posts() {
+ *   // Some mutation that we want to get the state for
+ *   const createPostsMutation = useMutation(() => ({
+ *     mutationKey,
+ *     mutationFn: createPosts,
+ *   }))
+ *
+ *   const savedPosts = useMutationState(() => ({
+ *     // this mutation key needs to match the mutation key of the given mutation (see above)
+ *     filters: { mutationKey, status: 'success' },
+ *     select: (mutation) => mutation.state.data,
+ *   }))
+ *
+ *   return (
+ *     <button onClick={() => createPostsMutation.mutate(['New Post'])}>
+ *       Create post ({savedPosts().length} saved so far)
+ *     </button>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * Access the latest successful mutation data via the `mutationKey`. Each invocation of `mutate` adds a new
+ * entry to the mutation cache for `gcTime` milliseconds — with the `status: 'success'` filter below, check the
+ * last item that `useMutationState` returns to get the latest successful invocation:
+ * ```tsx
+ * import { useMutationState } from '@tanstack/solid-query'
+ *
+ * function LatestPost() {
+ *   const savedPosts = useMutationState(() => ({
+ *     filters: { mutationKey: ['posts'], status: 'success' },
+ *     select: (mutation) => mutation.state.data,
+ *   }))
+ *
+ *   const latestPost = () => savedPosts()[savedPosts().length - 1]
+ *
+ *   return <span>{latestPost()?.title}</span>
+ * }
+ * ```
+ */
 export function useMutationState<
   TResult = MutationState,
   TMutation extends Mutation<any, any, any, any> =

package/src/useQueries.ts

@@ -184,6 +184,93 @@ type QueriesResults<
           >
         : { [K in keyof T]: GetResults<T[K]> }
 
+/**
+ * The `useQueries` hook can be used to fetch a variable number of queries.
+ *
+ * The `queries` key accepts an array with query option objects mostly identical to `useQuery` — see
+ * `placeholderData` below for the one difference. A custom `QueryClient` is supplied once, as `useQueries`'
+ * own top-level second argument, rather than per query.
+ *
+ * Having the same query key more than once in the array of query objects may cause some data to be shared
+ * between queries. To avoid this, consider de-duplicating the queries and map the results back to the desired
+ * structure.
+ *
+ * The `combine` option can be used to combine the results of the queries into a single value. The result will
+ * be structurally shared to be as referentially stable as possible.
+ *
+ * `placeholderData` is supported here too, but unlike `useQuery`, it doesn't receive information from
+ * previously rendered queries, because the number of queries can differ between renders.
+ * @param queriesOptions - An accessor returning the `queries` array to run, and an optional `combine`
+ * function.
+ * @param queryClient - An accessor for a custom `QueryClient`. Otherwise, the one from the nearest context
+ * will be used.
+ * @returns The combined result. Without `combine`, this is an array with all the query results, in the same
+ * order as the input. When `combine` is provided, this is the value returned by `combine` instead.
+ *
+ * @example
+ * ```tsx
+ * import { For } from 'solid-js'
+ * import { useQueries } from '@tanstack/solid-query'
+ *
+ * function Posts(props: { ids: Array<number> }) {
+ *   const postQueries = useQueries(() => ({
+ *     queries: props.ids.map((id) => ({
+ *       queryKey: ['post', id],
+ *       queryFn: () => fetchPost(id),
+ *       staleTime: Infinity,
+ *     })),
+ *   }))
+ *
+ *   return (
+ *     <ul>
+ *       <For each={postQueries}>
+ *         {(postQuery) => {
+ *           if (postQuery.isPending) return <li>Loading...</li>
+ *           if (postQuery.isError) return <li>Error: {postQuery.error.message}</li>
+ *           return <li>{postQuery.data.title}</li>
+ *         }}
+ *       </For>
+ *     </ul>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * Combining results into a single value:
+ * ```tsx
+ * import { For, Match, Switch } from 'solid-js'
+ * import { useQueries } from '@tanstack/solid-query'
+ *
+ * function Posts(props: { ids: Array<number> }) {
+ *   const combinedPostsQuery = useQueries(() => ({
+ *     queries: props.ids.map((id) => ({
+ *       queryKey: ['post', id],
+ *       queryFn: () => fetchPost(id),
+ *     })),
+ *     combine: (postQueries) => {
+ *       return {
+ *         data: postQueries.map((postQuery) => postQuery.data),
+ *         isPending: postQueries.some((postQuery) => postQuery.isPending),
+ *         isError: postQueries.some((postQuery) => postQuery.isError),
+ *       }
+ *     },
+ *   }))
+ *
+ *   return (
+ *     <Switch
+ *       fallback={
+ *         <ul>
+ *           <For each={combinedPostsQuery.data}>{(post) => <li>{post?.title}</li>}</For>
+ *         </ul>
+ *       }
+ *     >
+ *       <Match when={combinedPostsQuery.isPending}>Loading...</Match>
+ *       <Match when={combinedPostsQuery.isError}>Error loading posts</Match>
+ *     </Switch>
+ *   )
+ * }
+ * ```
+ */
 export function useQueries<
   T extends Array<any>,
   TCombinedResult extends QueriesResults<T> = QueriesResults<T>,