@tanstack/solid-query 5.102.8 → 5.103.1

package/build/dev.cjs

@@ -4,8 +4,19 @@ let solid_js = require("solid-js");
 let solid_js_web = require("solid-js/web");
 let solid_js_store = require("solid-js/store");
 //#region src/QueryClientProvider.tsx
+/**
+* The context that `useQueryClient` reads from. `QueryClientProvider` is the normal way to set it.
+*/
 const QueryClientContext = (0, solid_js.createContext)(void 0);
 const queryClientContextError = "No QueryClient set, use QueryClientProvider to set one";
+/**
+* The `useQueryClient` hook returns the current `QueryClient` instance.
+*
+* @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
+* be used.
+* @returns The current `QueryClient` instance.
+* @throws If no `queryClient` argument is passed and no `QueryClientProvider` is found in the component tree.
+*/
 const useQueryClient = (queryClient) => {
 	if (queryClient) return queryClient;
 	const client = (0, solid_js.useContext)(QueryClientContext);
@@ -21,6 +32,25 @@ const useQueryClientResolver = (queryClient) => {
 		return contextClient();
 	};
 };
+/**
+* Use the `QueryClientProvider` component to connect and provide a `QueryClient` to your application. Also
+* calls `client.mount()`/`client.unmount()` as this component mounts/unmounts, which subscribes the client to
+* focus/online events (resuming any paused mutations and refetching as needed when the app regains focus or
+* comes back online).
+*
+* @returns The provided `children`, wrapped so they can read the `QueryClient` via `useQueryClient`.
+*
+* @example
+* ```tsx
+* import { QueryClient, QueryClientProvider } from '@tanstack/solid-query'
+*
+* const queryClient = new QueryClient()
+*
+* function App() {
+*   return <QueryClientProvider client={queryClient}>...</QueryClientProvider>
+* }
+* ```
+*/
 const QueryClientProvider = (props) => {
 	(0, solid_js.createRenderEffect)((unmount) => {
 		unmount?.();
@@ -38,7 +68,18 @@ const QueryClientProvider = (props) => {
 //#endregion
 //#region src/isRestoring.ts
 const IsRestoringContext = (0, solid_js.createContext)(() => false);
+/**
+* If you are using `PersistQueryClientProvider`, you can also use the `useIsRestoring` hook alongside it to
+* check if a restore is currently in progress. `useQuery` and friends also check this internally to avoid
+* race conditions between the restore and mounting queries.
+*
+* @returns An accessor that reads `true` while a persisted client is being restored, `false` otherwise.
+*/
 const useIsRestoring = () => (0, solid_js.useContext)(IsRestoringContext);
+/**
+* The Provider that `PersistQueryClientProvider` uses to signal whether a persisted client is currently
+* being restored, read by `useIsRestoring`.
+*/
 const IsRestoringProvider = IsRestoringContext.Provider;
 //#endregion
 //#region src/useBaseQuery.ts
@@ -248,6 +289,165 @@ function useInfiniteQuery(options, queryClient) {
 }
 //#endregion
 //#region src/useMutation.ts
+/**
+* @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>
+*   )
+* }
+* ```
+*/
 function useMutation(options, queryClient) {
 	const resolveClient = useQueryClientResolver(queryClient);
 	const client = (0, solid_js.createMemo)(() => resolveClient());
@@ -278,6 +478,93 @@ function useMutation(options, queryClient) {
 }
 //#endregion
 //#region src/useQueries.ts
+/**
+* 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>
+*   )
+* }
+* ```
+*/
 function useQueries(queriesOptions, queryClient) {
 	const resolveClient = useQueryClientResolver(queryClient);
 	const client = (0, solid_js.createMemo)(() => resolveClient());
@@ -349,6 +636,10 @@ function useQueries(queriesOptions, queryClient) {
 }
 //#endregion
 //#region src/QueryClient.ts
+/**
+* The core `@tanstack/query-core` `QueryClient`, typed so its `defaultOptions.queries` accepts Solid's
+* `reconcile` option.
+*/
 var QueryClient = class extends _tanstack_query_core.QueryClient {
 	constructor(config = {}) {
 		super(config);
@@ -361,6 +652,28 @@ function queryOptions(options) {
 }
 //#endregion
 //#region src/useIsFetching.ts
+/**
+* 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
+* }
+* ```
+*/
 function useIsFetching(filters, queryClient) {
 	const resolveClient = useQueryClientResolver(queryClient);
 	const client = (0, solid_js.createMemo)(() => resolveClient());
@@ -387,6 +700,27 @@ function mutationOptions(options) {
 }
 //#endregion
 //#region src/useIsMutating.ts
+/**
+* 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
+* }
+* ```
+*/
 function useIsMutating(filters, queryClient) {
 	const resolveClient = useQueryClientResolver(queryClient);
 	const client = (0, solid_js.createMemo)(() => resolveClient());
@@ -406,6 +740,79 @@ function useIsMutating(filters, queryClient) {
 function getResult(mutationCache, options) {
 	return mutationCache.findAll(options.filters).map((mutation) => options.select ? options.select(mutation) : mutation.state);
 }
+/**
+* `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>
+* }
+* ```
+*/
 function useMutationState(options = () => ({}), queryClient) {
 	const resolveClient = useQueryClientResolver(queryClient);
 	const client = (0, solid_js.createMemo)(() => resolveClient());