@tanstack/solid-query 5.102.7 → 5.103.0

package/build/index.d.cts

@@ -2,6 +2,17 @@ import { DefaultError, DefaultOptions as DefaultOptions$1, DefinedInfiniteQueryO
 import { Accessor, JSX } from "solid-js";
 export * from "@tanstack/query-core";
 //#region src/QueryClient.d.ts
+/**
+ * The core `QueryObserverOptions`, with Solid's `reconcile` option added.
+ *
+ * @template TQueryFnData - The type your `queryFn` resolves to.
+ * @template TError - The type of errors your `queryFn` may throw.
+ * @template TData - The type `data` ends up as after `select` runs.
+ * @template TQueryData - The type of the data actually held in the query cache.
+ * @template TQueryKey - The type of your `queryKey`.
+ * @template TPageParam - The type of the parameter passed to `queryFn` to fetch a given page, when this type
+ * is shared with an infinite query's observer options. Defaults to `never` for regular queries.
+ */
 interface QueryObserverOptions<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryData = TQueryFnData, TQueryKey extends QueryKey = QueryKey, TPageParam = never> extends OmitKeyof<QueryObserverOptions$1<TQueryFnData, TError, TData, TQueryData, TQueryKey, TPageParam>, 'structuralSharing'> {
   /**
    * Set this to a reconciliation key to enable reconciliation between query results.
@@ -11,6 +22,15 @@ interface QueryObserverOptions<TQueryFnData = unknown, TError = DefaultError, TD
    */
   reconcile?: string | false | ((oldData: TData | undefined, newData: TData) => TData);
 }
+/**
+ * The core `InfiniteQueryObserverOptions`, with Solid's `reconcile` option added.
+ *
+ * @template TQueryFnData - The type of a single page, as your `queryFn` resolves it.
+ * @template TError - The type of errors your `queryFn` may throw.
+ * @template TData - The type `data` ends up as after `select` runs.
+ * @template TQueryKey - The type of your `queryKey`.
+ * @template TPageParam - The type of the parameter passed to `queryFn` to fetch a given page.
+ */
 interface InfiniteQueryObserverOptions<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey, TPageParam = unknown> extends OmitKeyof<InfiniteQueryObserverOptions$1<TQueryFnData, TError, TData, TQueryKey, TPageParam>, 'structuralSharing'> {
   /**
    * Set this to a reconciliation key to enable reconciliation between query results.
@@ -20,17 +40,42 @@ interface InfiniteQueryObserverOptions<TQueryFnData = unknown, TError = DefaultE
    */
   reconcile?: string | false | ((oldData: TData | undefined, newData: TData) => TData);
 }
+/**
+ * The default options a `QueryClient` applies to every query, with Solid's `reconcile` option added to
+ * `queries`.
+ *
+ * @template TError - The default type of errors thrown by queries and mutations using this `QueryClient`.
+ */
 interface DefaultOptions<TError = DefaultError> extends DefaultOptions$1<TError> {
   queries?: OmitKeyof<QueryObserverOptions<unknown, TError>, 'queryKey'>;
 }
+/**
+ * The config accepted by `new QueryClient(config)`, with Solid's extended {@link DefaultOptions}.
+ */
 interface QueryClientConfig extends QueryClientConfig$1 {
   defaultOptions?: DefaultOptions;
 }
+/**
+ * The core `@tanstack/query-core` `QueryClient`, typed so its `defaultOptions.queries` accepts Solid's
+ * `reconcile` option.
+ */
 declare class QueryClient extends QueryClient$1 {
   constructor(config?: QueryClientConfig);
 }
 //#endregion
 //#region src/types.d.ts
+/**
+ * The options accepted by `useQuery`. Extends {@link QueryObserverOptions} from `@tanstack/query-core` with
+ * the `solid-query`-specific `deferStream` and `suspense` options.
+ *
+ * @template TQueryFnData - The type your `queryFn` resolves to.
+ * @template TError - The type of errors your `queryFn` may throw.
+ * @template TData - The type `data` ends up as after `select` runs. Defaults to `TQueryFnData` when no
+ * `select` is used.
+ * @template TQueryData - The type of the data actually held in the query cache — the input to `select` and
+ * `placeholderData`. Defaults to, and is usually the same as, `TQueryFnData`.
+ * @template TQueryKey - The type of your `queryKey`.
+ */
 interface UseBaseQueryOptions<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryData = TQueryFnData, TQueryKey extends QueryKey = QueryKey> extends OmitKeyof<QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>, 'suspense'> {
   /**
    * Only applicable while rendering queries on the server with streaming.
@@ -46,12 +91,67 @@ interface UseBaseQueryOptions<TQueryFnData = unknown, TError = DefaultError, TDa
    */
   suspense?: boolean;
 }
+/**
+ * The options accepted by `useQuery` and `queryOptions`.
+ *
+ * @template TQueryFnData - The type your `queryFn` resolves to.
+ * @template TError - The type of errors your `queryFn` may throw.
+ * @template TData - The type `data` ends up as after `select` runs. Defaults to `TQueryFnData` when no
+ * `select` is used.
+ * @template TQueryKey - The type of your `queryKey`.
+ */
 interface QueryOptions<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey> extends UseBaseQueryOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey> {}
+/**
+ * The accessor `useQuery` expects as its first argument — Solid re-evaluates it reactively, so `queryKey` and
+ * other options can depend on signals.
+ *
+ * @template TQueryFnData - The type your `queryFn` resolves to.
+ * @template TError - The type of errors your `queryFn` may throw.
+ * @template TData - The type `data` ends up as after `select` runs. Defaults to `TQueryFnData` when no
+ * `select` is used.
+ * @template TQueryKey - The type of your `queryKey`.
+ */
 type UseQueryOptions<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey> = Accessor<QueryOptions<TQueryFnData, TError, TData, TQueryKey>>;
+/**
+ * The object `useQuery` returns when `initialData` isn't set — `data`/`error` may still be `undefined`/`null`
+ * while the query is `pending`. Re-exports {@link QueryObserverResult} from `@tanstack/query-core`.
+ * `useInfiniteQuery` returns {@link UseInfiniteQueryResult} instead.
+ *
+ * @template TData - The type `data` ends up as, after `select` runs (if set).
+ * @template TError - The type of errors this query may hold.
+ */
 type UseBaseQueryResult<TData = unknown, TError = DefaultError> = QueryObserverResult<TData, TError>;
+/**
+ * The object `useQuery` returns — `data`/`error` may still be `undefined`/`null` while the query is
+ * `pending`.
+ *
+ * @template TData - The type `data` ends up as, after `select` runs (if set).
+ * @template TError - The type of errors this query may hold.
+ */
 type UseQueryResult<TData = unknown, TError = DefaultError> = UseBaseQueryResult<TData, TError>;
+/**
+ * The object `useQuery` returns when `initialData` guarantees `data` is never `undefined`.
+ *
+ * @template TData - The type `data` ends up as, after `select` runs (if set).
+ * @template TError - The type of errors this query may hold.
+ */
 type DefinedUseBaseQueryResult<TData = unknown, TError = DefaultError> = DefinedQueryObserverResult<TData, TError>;
+/**
+ * The object `useQuery` returns when `initialData` guarantees `data` is never `undefined`.
+ *
+ * @template TData - The type `data` ends up as, after `select` runs (if set).
+ * @template TError - The type of errors this query may hold.
+ */
 type DefinedUseQueryResult<TData = unknown, TError = DefaultError> = DefinedUseBaseQueryResult<TData, TError>;
+/**
+ * The options accepted by `useInfiniteQuery`.
+ *
+ * @template TQueryFnData - The type of a single page, as your `queryFn` resolves it.
+ * @template TError - The type of errors your `queryFn` may throw.
+ * @template TData - The type `data` ends up as after `select` runs.
+ * @template TQueryKey - The type of your `queryKey`.
+ * @template TPageParam - The type of the parameter passed to `queryFn` to fetch a given page.
+ */
 interface InfiniteQueryOptions<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey, TPageParam = unknown> extends OmitKeyof<InfiniteQueryObserverOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, 'queryKey' | 'suspense'> {
   queryKey: TQueryKey;
   /**
@@ -68,49 +168,832 @@ interface InfiniteQueryOptions<TQueryFnData = unknown, TError = DefaultError, TD
    */
   suspense?: boolean;
 }
+/**
+ * The accessor `useInfiniteQuery` expects as its first argument — Solid re-evaluates it reactively, so
+ * `queryKey` and other options can depend on signals.
+ *
+ * @template TQueryFnData - The type of a single page, as your `queryFn` resolves it.
+ * @template TError - The type of errors your `queryFn` may throw.
+ * @template TData - The type `data` ends up as after `select` runs.
+ * @template TQueryKey - The type of your `queryKey`.
+ * @template TPageParam - The type of the parameter passed to `queryFn` to fetch a given page.
+ */
 type UseInfiniteQueryOptions<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey, TPageParam = unknown> = Accessor<InfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>>;
+/**
+ * The object `useInfiniteQuery` returns — `data`/`error` may still be `undefined`/`null` while the query is
+ * `pending`.
+ *
+ * @template TData - The type `data` ends up as, after `select` runs (if set).
+ * @template TError - The type of errors this query may hold.
+ */
 type UseInfiniteQueryResult<TData = unknown, TError = DefaultError> = InfiniteQueryObserverResult<TData, TError>;
+/**
+ * The object `useInfiniteQuery` returns when `initialData` guarantees `data` is never `undefined`.
+ *
+ * @template TData - The type `data` ends up as, after `select` runs (if set).
+ * @template TError - The type of errors this query may hold.
+ */
 type DefinedUseInfiniteQueryResult<TData = unknown, TError = DefaultError> = DefinedInfiniteQueryObserverResult<TData, TError>;
+/**
+ * The options accepted by `useMutation` and `mutationOptions`.
+ *
+ * @template TData - The type your `mutationFn` resolves to.
+ * @template TError - The type of errors your `mutationFn` may throw.
+ * @template TVariables - The type of the variables your `mutationFn` accepts.
+ * @template TOnMutateResult - The type returned by `onMutate`, passed on to `onSuccess`/`onError`/`onSettled`.
+ */
 interface MutationOptions<TData = unknown, TError = DefaultError, TVariables = void, TOnMutateResult = unknown> extends OmitKeyof<MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>, '_defaulted'> {}
+/**
+ * The accessor `useMutation` expects as its first argument — Solid re-evaluates it reactively, so callbacks
+ * and other options can depend on signals.
+ *
+ * @template TData - The type your `mutationFn` resolves to.
+ * @template TError - The type of errors your `mutationFn` may throw.
+ * @template TVariables - The type of the variables your `mutationFn` accepts.
+ * @template TOnMutateResult - The type returned by `onMutate`, passed on to `onSuccess`/`onError`/`onSettled`.
+ */
 type UseMutationOptions<TData = unknown, TError = DefaultError, TVariables = void, TOnMutateResult = unknown> = Accessor<MutationOptions<TData, TError, TVariables, TOnMutateResult>>;
 type UseMutateFunction<TData = unknown, TError = DefaultError, TVariables = void, TOnMutateResult = unknown> = (...args: Parameters<MutateFunction<TData, TError, TVariables, TOnMutateResult>>) => void;
+/**
+ * The type of `mutateAsync`, as returned by `useMutation`. Similar to {@link UseMutateFunction}, but returns a
+ * promise which can be awaited.
+ *
+ * @template TData - The type your `mutationFn` resolves to.
+ * @template TError - The type of errors your `mutationFn` may throw.
+ * @template TVariables - The type of the variable passed to `mutateAsync`.
+ * @template TOnMutateResult - The type returned by `onMutate`, passed to `onSuccess`/`onError`/`onSettled` as
+ * their `onMutateResult` parameter — useful for optimistic-update rollback data.
+ */
 type UseMutateAsyncFunction<TData = unknown, TError = DefaultError, TVariables = void, TOnMutateResult = unknown> = MutateFunction<TData, TError, TVariables, TOnMutateResult>;
+/**
+ * The result of `useMutation`. Same as {@link MutationObserverResult} from `@tanstack/query-core`, with
+ * `mutate` narrowed to the fire-and-forget {@link UseMutateFunction} signature, plus the added `mutateAsync`.
+ *
+ * @template TData - The type your `mutationFn` resolves to.
+ * @template TError - The type of errors your `mutationFn` may throw.
+ * @template TVariables - The type of the variable passed to `mutate`/`mutateAsync`.
+ * @template TOnMutateResult - The type returned by `onMutate`, passed to `onSuccess`/`onError`/`onSettled` as
+ * their `onMutateResult` parameter — useful for optimistic-update rollback data.
+ */
 type UseBaseMutationResult<TData = unknown, TError = DefaultError, TVariables = unknown, TOnMutateResult = unknown> = Override<MutationObserverResult<TData, TError, TVariables, TOnMutateResult>, {
   mutate: UseMutateFunction<TData, TError, TVariables, TOnMutateResult>;
 }> & {
+  /**
+   * Similar to `mutate`, but returns a promise which can be awaited.
+   */
   mutateAsync: UseMutateAsyncFunction<TData, TError, TVariables, TOnMutateResult>;
 };
+/**
+ * The result of `useMutation`. Same as {@link UseBaseMutationResult}.
+ *
+ * @template TData - The type your `mutationFn` resolves to.
+ * @template TError - The type of errors your `mutationFn` may throw.
+ * @template TVariables - The type of the variable passed to `mutate`/`mutateAsync`.
+ * @template TOnMutateResult - The type returned by `onMutate`, passed to `onSuccess`/`onError`/`onSettled` as
+ * their `onMutateResult` parameter — useful for optimistic-update rollback data.
+ */
 type UseMutationResult<TData = unknown, TError = DefaultError, TVariables = unknown, TOnMutateResult = unknown> = UseBaseMutationResult<TData, TError, TVariables, TOnMutateResult>;
 //#endregion
 //#region src/queryOptions.d.ts
+/**
+ * The options accepted by the `queryOptions` overload selected when no `initialData` is set — `data` may be
+ * `undefined` while the query is `pending`. `queryOptions` itself accepts and returns a plain object (its
+ * parameter type is `ReturnType<UndefinedInitialDataOptions<...>>`, i.e. this `Accessor` called); Solid's
+ * reactivity applies where the result is consumed instead, e.g. `useQuery(() => options)`.
+ *
+ * @template TQueryFnData - The type your `queryFn` resolves to.
+ * @template TError - The type of errors your `queryFn` may throw.
+ * @template TData - The type `data` ends up as after `select` runs.
+ * @template TQueryKey - The type of your `queryKey`.
+ */
 type UndefinedInitialDataOptions<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey> = Accessor<QueryOptions<TQueryFnData, TError, TData, TQueryKey> & {
   initialData?: undefined;
 }>;
+/**
+ * The options accepted by the `queryOptions` overload selected when `initialData` is set — `data` is never
+ * `undefined`.
+ *
+ * @template TQueryFnData - The type your `queryFn` resolves to.
+ * @template TError - The type of errors your `queryFn` may throw.
+ * @template TData - The type `data` ends up as after `select` runs.
+ * @template TQueryKey - The type of your `queryKey`.
+ */
 type DefinedInitialDataOptions<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey> = Accessor<QueryOptions<TQueryFnData, TError, TData, TQueryKey> & {
   initialData: TQueryFnData | (() => TQueryFnData);
 }>;
-declare function queryOptions<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey>(options: ReturnType<UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>>): ReturnType<UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>> & QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>;
+/**
+ * You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can
+ * be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and
+ * is the query key to generate options for.
+ *
+ * This overload is selected when `initialData` is set, so the resulting `data` is never `undefined`.
+ *
+ * @see {@link useQuery} to run a query with these options.
+ * @param options - The {@link DefinedInitialDataOptions} to use — everything you can pass to `useQuery`, with `initialData` set.
+ * @returns The same options object, typed so that `queryKey` carries the inferred data type.
+ *
+ * @example
+ * ```tsx
+ * import { For } from 'solid-js'
+ * import { queryOptions, useQuery } from '@tanstack/solid-query'
+ *
+ * const postsOptions = queryOptions({
+ *   queryKey: ['posts'],
+ *   queryFn: fetchPosts,
+ *   initialData: [],
+ * })
+ *
+ * function Posts() {
+ *   // `postsQuery.data` is `Post[]`, never `undefined`, thanks to `initialData` — even if a refetch fails,
+ *   // so the list stays visible alongside the error.
+ *   const postsQuery = useQuery(() => postsOptions)
+ *
+ *   return (
+ *     <div>
+ *       {postsQuery.isError ? <span>Error: {postsQuery.error.message}</span> : null}
+ *       <ul>
+ *         <For each={postsQuery.data}>{(post) => <li>{post.title}</li>}</For>
+ *       </ul>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
 declare function queryOptions<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey>(options: ReturnType<DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>>): ReturnType<DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>> & QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>;
+/**
+ * You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can
+ * be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and
+ * is the query key to generate options for.
+ *
+ * @see {@link useQuery} to run a query with these options.
+ * @param options - The {@link UndefinedInitialDataOptions} to use — everything you can pass to `useQuery`.
+ * @returns The same options object, typed so that `queryKey` carries the inferred data type.
+ *
+ * @example
+ * A parameterized factory, so the same options object can be reused per `id`:
+ * ```tsx
+ * import { Match, Switch } from 'solid-js'
+ * import { queryOptions, useQuery } from '@tanstack/solid-query'
+ *
+ * const postOptions = (id: string) =>
+ *   queryOptions({
+ *     queryKey: ['post', id],
+ *     queryFn: () => fetchPost(id),
+ *   })
+ *
+ * function Post(props: { id: string }) {
+ *   const postQuery = useQuery(() => postOptions(props.id))
+ *
+ *   return (
+ *     <Switch>
+ *       <Match when={postQuery.isPending}>Loading...</Match>
+ *       <Match when={postQuery.isError}>Error: {postQuery.error.message}</Match>
+ *       <Match when={postQuery.isSuccess}>
+ *         <h1>{postQuery.data.title}</h1>
+ *       </Match>
+ *     </Switch>
+ *   )
+ * }
+ * ```
+ */
+declare function queryOptions<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey>(options: ReturnType<UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>>): ReturnType<UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>> & QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>;
 //#endregion
 //#region src/useQuery.d.ts
+/**
+ * @see {@link queryOptions} to share these options between `useQuery` and imperative APIs like `queryClient.query`.
+ * @param options - An accessor returning the {@link UndefinedInitialDataOptions} to use — everything you can
+ * pass to `useQuery`.
+ * @param queryClient - An accessor for a custom `QueryClient`. Otherwise, the one from the nearest context
+ * will be used.
+ * @returns The current query result, as a Solid store. `status` is `pending` if there is no cached data to
+ * display, `error` if the last fetch attempt failed, or `success` if the query has data to display.
+ * `isPending`/`isSuccess`/`isError` are derived booleans for convenience.
+ *
+ * @example
+ * ```tsx
+ * import { For, Match, Switch } from 'solid-js'
+ * import { useQuery } from '@tanstack/solid-query'
+ *
+ * function Posts() {
+ *   const postsQuery = useQuery(() => ({
+ *     queryKey: ['posts'],
+ *     queryFn: fetchPosts,
+ *   }))
+ *
+ *   return (
+ *     <Switch>
+ *       <Match when={postsQuery.isPending}>Loading...</Match>
+ *       <Match when={postsQuery.isError}>Error: {postsQuery.error.message}</Match>
+ *       <Match when={postsQuery.isSuccess}>
+ *         <ul>
+ *           <For each={postsQuery.data}>{(post) => <li>{post.title}</li>}</For>
+ *         </ul>
+ *         <div>{postsQuery.isFetching ? 'Background Updating...' : ' '}</div>
+ *       </Match>
+ *     </Switch>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * `select` derives whatever `data` a component needs from the cached value, without changing what's
+ * actually stored in the cache — the cache still holds the full `Post[]`, but `data` here is a `number`:
+ * ```tsx
+ * import { Match, Switch } from 'solid-js'
+ * import { useQuery } from '@tanstack/solid-query'
+ *
+ * function PostCount() {
+ *   const postsQuery = useQuery(() => ({
+ *     queryKey: ['posts'],
+ *     queryFn: fetchPosts,
+ *     select: (posts) => posts.length,
+ *   }))
+ *
+ *   return (
+ *     <Switch>
+ *       <Match when={postsQuery.isPending}>Loading...</Match>
+ *       <Match when={postsQuery.isError}>Error: {postsQuery.error.message}</Match>
+ *       <Match when={postsQuery.isSuccess}>{postsQuery.data} posts</Match>
+ *     </Switch>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * A dependent query, only enabled once `postId` is set:
+ * ```tsx
+ * import { Match, Switch } from 'solid-js'
+ * import { useQuery } from '@tanstack/solid-query'
+ *
+ * function Post(props: { postId: number | undefined }) {
+ *   const postQuery = useQuery(() => ({
+ *     queryKey: ['post', props.postId],
+ *     queryFn: () => fetchPost(props.postId!),
+ *     enabled: props.postId != null,
+ *   }))
+ *
+ *   return (
+ *     <Switch fallback={<h1>{postQuery.data?.title}</h1>}>
+ *       <Match when={props.postId == null}>Select a post</Match>
+ *       <Match when={postQuery.isLoading}>Loading...</Match>
+ *       <Match when={postQuery.isError}>Error: {postQuery.error.message}</Match>
+ *     </Switch>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * The same dependent query, using `skipToken` to disable it in a type-safe way instead of relying on
+ * `enabled`. The non-null assertion is still needed — Solid's `props` narrowing doesn't survive into the
+ * `queryFn` closure the way a local `const` would — but `skipToken` keeps `queryFn`'s return type accurate
+ * without it. `refetch` doesn't work while `queryFn` is `skipToken` — use `enabled: false` instead if you
+ * need to trigger the query manually:
+ * ```tsx
+ * import { Match, Switch } from 'solid-js'
+ * import { skipToken, useQuery } from '@tanstack/solid-query'
+ *
+ * function Post(props: { postId: number | undefined }) {
+ *   const postQuery = useQuery(() => ({
+ *     queryKey: ['post', props.postId],
+ *     queryFn: props.postId != null ? () => fetchPost(props.postId!) : skipToken,
+ *   }))
+ *
+ *   return (
+ *     <Switch fallback={<h1>{postQuery.data?.title}</h1>}>
+ *       <Match when={props.postId == null}>Select a post</Match>
+ *       <Match when={postQuery.isLoading}>Loading...</Match>
+ *       <Match when={postQuery.isError}>Error: {postQuery.error.message}</Match>
+ *     </Switch>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * Seeding a detail query from an already-cached list, to skip the loading state:
+ * ```tsx
+ * import { useQuery, useQueryClient } from '@tanstack/solid-query'
+ *
+ * function Post(props: { postId: number }) {
+ *   const queryClient = useQueryClient()
+ *
+ *   const postQuery = useQuery(() => ({
+ *     queryKey: ['post', props.postId],
+ *     queryFn: () => fetchPost(props.postId),
+ *     initialData: () =>
+ *       queryClient
+ *         .getQueryData<Array<Post>>(['posts'])
+ *         ?.find((post) => post.id === props.postId),
+ *   }))
+ *
+ *   return postQuery.isError ? <span>Error: {postQuery.error.message}</span> : <h1>{postQuery.data?.title}</h1>
+ * }
+ * ```
+ *
+ * @example
+ * Paginated data, keeping the previous page's data visible while the next page loads:
+ * ```tsx
+ * import { For, createSignal } from 'solid-js'
+ * import { keepPreviousData, useQuery } from '@tanstack/solid-query'
+ *
+ * function Posts() {
+ *   const [page, setPage] = createSignal(0)
+ *
+ *   const postsQuery = useQuery(() => ({
+ *     queryKey: ['posts', page()],
+ *     queryFn: () => fetchPosts(page()),
+ *     placeholderData: keepPreviousData,
+ *   }))
+ *
+ *   return (
+ *     <div>
+ *       <ul>
+ *         <For each={postsQuery.data}>{(post) => <li>{post.title}</li>}</For>
+ *       </ul>
+ *       <button
+ *         disabled={postsQuery.isPlaceholderData}
+ *         onClick={() => setPage((old) => old + 1)}
+ *       >
+ *         Next Page
+ *       </button>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
 declare function useQuery<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey>(options: UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>, queryClient?: () => QueryClient): UseQueryResult<TData, TError>;
+/**
+ * This overload is selected when `initialData` is set, so the resulting `data` is never `undefined`.
+ *
+ * @see {@link queryOptions} to share these options between `useQuery` and imperative APIs like `queryClient.query`.
+ * @param options - An accessor returning the {@link DefinedInitialDataOptions} to use — everything you can
+ * pass to `useQuery`, with `initialData` set.
+ * @param queryClient - An accessor for a custom `QueryClient`. Otherwise, the one from the nearest context
+ * will be used.
+ * @returns The current query result, as a Solid store, typed so that `status` is `success` — or `error` if a
+ * fetch attempt fails while keeping the existing data (`status` never resolves to `pending` in this overload's
+ * type, since `initialData` guarantees data upfront). `isSuccess`/`isError` are derived booleans for
+ * convenience.
+ *
+ * @example
+ * ```tsx
+ * import { For } from 'solid-js'
+ * import { useQuery } from '@tanstack/solid-query'
+ *
+ * function Posts() {
+ *   // `postsQuery.data` is never `undefined`, thanks to `initialData` — even if a refetch fails, so the
+ *   // list stays visible alongside the error.
+ *   const postsQuery = useQuery(() => ({
+ *     queryKey: ['posts'],
+ *     queryFn: fetchPosts,
+ *     initialData: [],
+ *   }))
+ *
+ *   return (
+ *     <div>
+ *       {postsQuery.isError ? <span>Error: {postsQuery.error.message}</span> : null}
+ *       <ul>
+ *         <For each={postsQuery.data}>{(post) => <li>{post.title}</li>}</For>
+ *       </ul>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
 declare function useQuery<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey>(options: DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>, queryClient?: () => QueryClient): DefinedUseQueryResult<TData, TError>;
 //#endregion
 //#region src/infiniteQueryOptions.d.ts
+/**
+ * The options accepted by the `infiniteQueryOptions` overload selected when no `initialData` is set — `data`
+ * may be `undefined` while the query is `pending`. `infiniteQueryOptions` itself accepts and returns a plain
+ * object (its parameter type is `ReturnType<UndefinedInitialDataInfiniteOptions<...>>`, i.e. this `Accessor`
+ * called); Solid's reactivity applies where the result is consumed instead, e.g.
+ * `useInfiniteQuery(() => options)`.
+ *
+ * @template TQueryFnData - The type of a single page, as your `queryFn` resolves it.
+ * @template TError - The type of errors your `queryFn` may throw.
+ * @template TData - The type `data` ends up as after `select` runs — defaults to `InfiniteData<TQueryFnData>`,
+ * the shape of all fetched pages plus their page params.
+ * @template TQueryKey - The type of your `queryKey`.
+ * @template TPageParam - The type of the parameter passed to `queryFn` to fetch a given page.
+ */
 type UndefinedInitialDataInfiniteOptions<TQueryFnData, TError = DefaultError, TData = InfiniteData<TQueryFnData>, TQueryKey extends QueryKey = QueryKey, TPageParam = unknown> = Accessor<InfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & {
   initialData?: undefined;
 }>;
+/**
+ * The options accepted by the `infiniteQueryOptions` overload selected when `initialData` is set — `data` is
+ * never `undefined`.
+ *
+ * @template TQueryFnData - The type of a single page, as your `queryFn` resolves it.
+ * @template TError - The type of errors your `queryFn` may throw.
+ * @template TData - The type `data` ends up as after `select` runs — defaults to `InfiniteData<TQueryFnData>`,
+ * the shape of all fetched pages plus their page params.
+ * @template TQueryKey - The type of your `queryKey`.
+ * @template TPageParam - The type of the parameter passed to `queryFn` to fetch a given page.
+ */
 type DefinedInitialDataInfiniteOptions<TQueryFnData, TError = DefaultError, TData = InfiniteData<TQueryFnData>, TQueryKey extends QueryKey = QueryKey, TPageParam = unknown> = Accessor<InfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & {
   initialData: NonUndefinedGuard<InfiniteData<TQueryFnData, TPageParam>> | (() => NonUndefinedGuard<InfiniteData<TQueryFnData, TPageParam>>);
 }>;
+/**
+ * You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
+ * These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
+ * `options.queryKey` is required and is the query key to generate options for.
+ *
+ * This overload is selected when `initialData` is set.
+ *
+ * @see {@link useInfiniteQuery} to run an infinite query with these options.
+ * @param options - The {@link DefinedInitialDataInfiniteOptions} to use — everything you can pass to `useInfiniteQuery`, with `initialData` set.
+ * @returns The same options object, typed so that `queryKey` carries the inferred data type.
+ *
+ * @example
+ * ```tsx
+ * import { For } from 'solid-js'
+ * import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/solid-query'
+ *
+ * const projectsOptions = infiniteQueryOptions({
+ *   queryKey: ['projects'],
+ *   queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *   initialPageParam: 0,
+ *   getNextPageParam: (lastPage) => lastPage.nextId,
+ *   initialData: { pages: [], pageParams: [] },
+ * })
+ *
+ * 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(() => projectsOptions)
+ *
+ *   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>
+ *   )
+ * }
+ * ```
+ */
 declare function infiniteQueryOptions<TQueryFnData, TError = DefaultError, TData = InfiniteData<TQueryFnData>, TQueryKey extends QueryKey = QueryKey, TPageParam = unknown>(options: ReturnType<DefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>>): ReturnType<DefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>> & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>;
+/**
+ * You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
+ * These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
+ * `options.queryKey` is required and is the query key to generate options for.
+ *
+ * @see {@link useInfiniteQuery} to run an infinite query with these options.
+ * @param options - The {@link UndefinedInitialDataInfiniteOptions} to use — everything you can pass to `useInfiniteQuery`.
+ * @returns The same options object, typed so that `queryKey` carries the inferred data type.
+ *
+ * @example
+ * A parameterized factory, so the same options object can be reused per `postId`:
+ * ```tsx
+ * import { For, Match, Switch } from 'solid-js'
+ * import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/solid-query'
+ *
+ * const commentsOptions = (postId: string) =>
+ *   infiniteQueryOptions({
+ *     queryKey: ['post', postId, 'comments'],
+ *     queryFn: ({ pageParam }) => fetchComments(postId, pageParam),
+ *     initialPageParam: 0,
+ *     getNextPageParam: (lastPage) => lastPage.nextId,
+ *   })
+ *
+ * function Comments(props: { postId: string }) {
+ *   const commentsQuery = useInfiniteQuery(() => commentsOptions(props.postId))
+ *
+ *   return (
+ *     <Switch>
+ *       <Match when={commentsQuery.isPending}>Loading...</Match>
+ *       <Match when={commentsQuery.isError}>Error: {commentsQuery.error.message}</Match>
+ *       <Match when={commentsQuery.isSuccess}>
+ *         <ul>
+ *           <For each={commentsQuery.data.pages}>
+ *             {(page) => <For each={page.comments}>{(c) => <li>{c.text}</li>}</For>}
+ *           </For>
+ *         </ul>
+ *       </Match>
+ *     </Switch>
+ *   )
+ * }
+ * ```
+ */
 declare function infiniteQueryOptions<TQueryFnData, TError = DefaultError, TData = InfiniteData<TQueryFnData>, TQueryKey extends QueryKey = QueryKey, TPageParam = unknown>(options: ReturnType<UndefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>>): ReturnType<UndefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>> & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>;
 //#endregion
 //#region src/useInfiniteQuery.d.ts
+/**
+ * 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>
+ *   )
+ * }
+ * ```
+ */
 declare function useInfiniteQuery<TQueryFnData, TError = DefaultError, TData = InfiniteData<TQueryFnData>, TQueryKey extends QueryKey = QueryKey, TPageParam = unknown>(options: DefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, 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>
+ *   )
+ * }
+ * ```
+ */
 declare function useInfiniteQuery<TQueryFnData, TError = DefaultError, TData = InfiniteData<TQueryFnData>, TQueryKey extends QueryKey = QueryKey, TPageParam = unknown>(options: UndefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, queryClient?: Accessor<QueryClient>): UseInfiniteQueryResult<TData, TError>;
 //#endregion
 //#region src/useMutation.d.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>
+ *   )
+ * }
+ * ```
+ */
 declare function useMutation<TData = unknown, TError = DefaultError, TVariables = void, TOnMutateResult = unknown>(options: UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, queryClient?: Accessor<QueryClient>): UseMutationResult<TData, TError, TVariables, TOnMutateResult>;
 //#endregion
 //#region src/useQueries.d.ts
@@ -164,28 +1047,254 @@ type QueriesOptions<T extends Array<any>, TResult extends Array<any> = [], TDept
  * QueriesResults reducer recursively maps type param to results
  */
 type QueriesResults<T extends Array<any>, TResult extends Array<any> = [], TDepth extends ReadonlyArray<number> = []> = TDepth['length'] extends MAXIMUM_DEPTH ? Array<UseQueryResult> : T extends [] ? [] : T extends [infer Head] ? [...TResult, GetResults<Head>] : T extends [infer Head, ...infer Tail] ? QueriesResults<[...Tail], [...TResult, GetResults<Head>], [...TDepth, 1]> : { [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>
+ *   )
+ * }
+ * ```
+ */
 declare function useQueries<T extends Array<any>, TCombinedResult extends QueriesResults<T> = QueriesResults<T>>(queriesOptions: Accessor<{
   queries: readonly [...QueriesOptions<T>] | readonly [...{ [K in keyof T]: GetOptions<T[K]>; }];
   combine?: (result: QueriesResults<T>) => TCombinedResult;
 }>, queryClient?: Accessor<QueryClient>): TCombinedResult;
 //#endregion
 //#region src/QueryClientProvider.d.ts
+/**
+ * The context that `useQueryClient` reads from. `QueryClientProvider` is the normal way to set it.
+ */
 declare const QueryClientContext: import("solid-js").Context<(() => QueryClient) | undefined>;
+/**
+ * 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.
+ */
 declare const useQueryClient: (queryClient?: QueryClient) => QueryClient;
+/**
+ * The props accepted by `QueryClientProvider`.
+ */
 type QueryClientProviderProps = {
+  /**
+   * **Required**
+   *
+   * The `QueryClient` instance to provide.
+   */
   client: QueryClient;
+  /**
+   * The components that get access to the provided `QueryClient`.
+   */
   children?: JSX.Element;
 };
+/**
+ * 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>
+ * }
+ * ```
+ */
 declare const QueryClientProvider: (props: QueryClientProviderProps) => JSX.Element;
 //#endregion
 //#region src/useIsFetching.d.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
+ * }
+ * ```
+ */
 declare function useIsFetching(filters?: Accessor<QueryFilters>, queryClient?: Accessor<QueryClient>): Accessor<number>;
 //#endregion
 //#region src/mutationOptions.d.ts
+/**
+ * You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. A
+ * `mutationKey` is required on this overload so the mutation can be looked up later, e.g. with
+ * `useMutationState`.
+ *
+ * @see {@link useMutation} to run the mutation these options describe.
+ * @param options - The mutation options to use, identical to what you'd pass to `useMutation`, with a
+ * required `mutationKey`.
+ * @returns The same options object, unchanged.
+ *
+ * @example
+ * Looking the mutation up elsewhere via its `mutationKey`, e.g. for a global "saving…" indicator:
+ * ```tsx
+ * import { mutationOptions, useMutationState } from '@tanstack/solid-query'
+ *
+ * const createPostOptions = mutationOptions({
+ *   mutationKey: ['posts', 'create'],
+ *   mutationFn: createPost,
+ * })
+ *
+ * function SavingIndicator() {
+ *   const isCreatingPost = useMutationState(() => ({
+ *     filters: { mutationKey: createPostOptions.mutationKey, status: 'pending' },
+ *   }))
+ *
+ *   return isCreatingPost().length > 0 ? <span>Saving…</span> : null
+ * }
+ * ```
+ */
 declare function mutationOptions<TData = unknown, TError = DefaultError, TVariables = void, TOnMutateResult = unknown>(options: WithRequired<MutationOptions<TData, TError, TVariables, TOnMutateResult>, 'mutationKey'>): WithRequired<MutationOptions<TData, TError, TVariables, TOnMutateResult>, 'mutationKey'>;
+/**
+ * You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. No
+ * `mutationKey` is required on this overload — use this when you don't need to target the mutation via a
+ * `mutationKey` filter later (e.g. with `useMutationState`); it can still be observed through other filters,
+ * such as `status`.
+ *
+ * @see {@link useMutation} to run the mutation these options describe.
+ * @param options - The mutation options to use, identical to what you'd pass to `useMutation`, without a
+ * `mutationKey`.
+ * @returns The same options object, unchanged.
+ * @remarks See the other overload's example for looking a mutation up via `useMutationState`.
+ *
+ * @example
+ * ```tsx
+ * import { mutationOptions, useMutation } from '@tanstack/solid-query'
+ *
+ * const createPostOptions = mutationOptions({
+ *   mutationFn: createPost,
+ * })
+ *
+ * function CreatePost() {
+ *   const createPostMutation = useMutation(() => createPostOptions)
+ *   return <button onClick={() => createPostMutation.mutate({ title: 'Hello' })}>Create</button>
+ * }
+ * ```
+ */
 declare function mutationOptions<TData = unknown, TError = DefaultError, TVariables = void, TOnMutateResult = unknown>(options: Omit<MutationOptions<TData, TError, TVariables, TOnMutateResult>, 'mutationKey'>): Omit<MutationOptions<TData, TError, TVariables, TOnMutateResult>, 'mutationKey'>;
 //#endregion
 //#region src/useIsMutating.d.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
+ * }
+ * ```
+ */
 declare function useIsMutating(filters?: Accessor<MutationFilters>, queryClient?: Accessor<QueryClient>): Accessor<number>;
 //#endregion
 //#region src/useMutationState.d.ts
@@ -194,10 +1303,94 @@ type MutationStateOptions<TResult = MutationState, TMutation extends Mutation<an
   filters?: MutationFilters;
   select?: (mutation: TMutation) => TResult;
 };
+/**
+ * `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>
+ * }
+ * ```
+ */
 declare function useMutationState<TResult = MutationState, TMutation extends Mutation<any, any, any, any> = MutationTypeFromResult<TResult>>(options?: Accessor<MutationStateOptions<TResult, TMutation>>, queryClient?: Accessor<QueryClient>): Accessor<Array<TResult>>;
 //#endregion
 //#region src/isRestoring.d.ts
+/**
+ * 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.
+ */
 declare const useIsRestoring: () => Accessor<boolean>;
+/**
+ * The Provider that `PersistQueryClientProvider` uses to signal whether a persisted client is currently
+ * being restored, read by `useIsRestoring`.
+ */
 declare const IsRestoringProvider: import("solid-js").ContextProviderComponent<Accessor<boolean>>;
 //#endregion
 //#region src/index.d.ts