@tanstack/svelte-query 6.3.1 → 6.3.2

package/src/context.ts

@@ -7,9 +7,8 @@ const _contextKey = Symbol('QueryClient')
 /**
  * Retrieves the `QueryClient` set on Svelte's context by `QueryClientProvider` (or by
  * {@link setQueryClientContext} directly). This is what {@link useQueryClient} calls internally.
- *
- * @throws If no `QueryClient` was found in context.
  * @returns The `QueryClient` set on context, whether by `QueryClientProvider` or {@link setQueryClientContext}.
+ * @throws {Error} If no `QueryClient` was found in context.
  */
 export const getQueryClientContext = (): QueryClient => {
   const client = getContext<QueryClient | undefined>(_contextKey)
@@ -26,9 +25,7 @@ export const getQueryClientContext = (): QueryClient => {
  * Sets a `QueryClient` on Svelte's context, so it can be read with {@link getQueryClientContext} (or
  * {@link useQueryClient}) from any descendant component. `QueryClientProvider` wraps this — use it directly
  * only if you need to set the client from your own component instead.
- *
  * @param client - The `QueryClient` to make available to descendant components.
- *
  * @example
  * ```svelte
  * <script lang="ts">
@@ -48,7 +45,11 @@ export const setQueryClientContext = (client: QueryClient): void => {
 
 const _isRestoringContextKey = Symbol('isRestoring')
 
-/** Retrieves a `isRestoring` from Svelte's context */
+/**
+ * Retrieves a `isRestoring` from Svelte's context.
+ * @returns The `isRestoring` box set on context, or a box holding `false` if none was set or the
+ * context is unavailable.
+ */
 export const getIsRestoringContext = (): Box<boolean> => {
   try {
     const isRestoring = getContext<Box<boolean> | undefined>(
@@ -60,7 +61,10 @@ export const getIsRestoringContext = (): Box<boolean> => {
   }
 }
 
-/** Sets a `isRestoring` on Svelte's context */
+/**
+ * Sets a `isRestoring` on Svelte's context.
+ * @param isRestoring - The box holding whether the cache is being restored, e.g. by a persister.
+ */
 export const setIsRestoringContext = (isRestoring: Box<boolean>): void => {
   setContext(_isRestoringContextKey, isRestoring)
 }

package/src/createBaseQuery.svelte.ts

@@ -15,6 +15,7 @@ import type {
  * @param options - A function that returns query options
  * @param Observer - The observer from query-core
  * @param queryClient - Custom query client which overrides provider
+ * @returns The reactive query result.
  */
 export function createBaseQuery<
   TQueryFnData,
@@ -61,6 +62,11 @@ export function createBaseQuery<
     },
   )
 
+  /**
+   * Computes the observer's current result for the resolved options, tracking property access unless
+   * `notifyOnChangeProps` is set.
+   * @returns The current query result.
+   */
   function createResult() {
     const result = observer.getOptimisticResult(resolvedOptions)
     return !resolvedOptions.notifyOnChangeProps

package/src/createInfiniteQuery.ts

@@ -23,15 +23,14 @@ import type {
  * `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
  *
  * This overload is selected when `initialData` is known to be defined.
- *
- * @see {@link infiniteQueryOptions} to share these options between `createInfiniteQuery` and imperative APIs
- * like `queryClient.infiniteQuery`.
  * @param options - The {@link DefinedInitialDataInfiniteOptions} to use — everything you can pass to
  * `createInfiniteQuery`, with `initialData` set, wrapped in an {@link Accessor} so options can be reactive.
  * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
  * be used.
  * @returns The current query result, plus `fetchNextPage`/`fetchPreviousPage`/`hasNextPage`/`hasPreviousPage`
  * to page through the query.
+ * @see {@link infiniteQueryOptions} to share these options between `createInfiniteQuery` and imperative APIs
+ * like `queryClient.infiniteQuery`.
  */
 export function createInfiniteQuery<
   TQueryFnData = unknown,
@@ -57,15 +56,14 @@ export function createInfiniteQuery<
  * `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
  *
  * This overload is selected when `initialData` is omitted or may be `undefined`.
- *
- * @see {@link infiniteQueryOptions} to share these options between `createInfiniteQuery` and imperative APIs
- * like `queryClient.infiniteQuery`.
  * @param options - The {@link UndefinedInitialDataInfiniteOptions} to use — everything you can pass to
  * `createInfiniteQuery`, wrapped in an {@link Accessor} so options can be reactive.
  * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
  * be used.
  * @returns The current query result, plus `fetchNextPage`/`fetchPreviousPage`/`hasNextPage`/`hasPreviousPage`
  * to page through the query.
+ * @see {@link infiniteQueryOptions} to share these options between `createInfiniteQuery` and imperative APIs
+ * like `queryClient.infiniteQuery`.
  */
 export function createInfiniteQuery<
   TQueryFnData = unknown,
@@ -89,16 +87,14 @@ export function createInfiniteQuery<
 /**
  * The options for `createInfiniteQuery` are identical to `createQuery`, with the addition of
  * `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
- *
- * @see {@link infiniteQueryOptions} to share these options between `createInfiniteQuery` and imperative APIs
- * like `queryClient.infiniteQuery`.
  * @param options - The {@link CreateInfiniteQueryOptions} to use — everything you can pass to
  * `createInfiniteQuery`, wrapped in an {@link Accessor} so options can be reactive.
  * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
  * be used.
  * @returns The current query result, plus `fetchNextPage`/`fetchPreviousPage`/`hasNextPage`/`hasPreviousPage`
  * to page through the query.
- *
+ * @see {@link infiniteQueryOptions} to share these options between `createInfiniteQuery` and imperative APIs
+ * like `queryClient.infiniteQuery`.
  * @example
  * Fetching the next page from a "Load More" button click:
  * ```svelte
@@ -137,7 +133,6 @@ export function createInfiniteQuery<
  *   </button>
  * {/if}
  * ```
- *
  * @example
  * Fetching the next page automatically as the user scrolls, using an `IntersectionObserver` on a
  * sentinel element after the list:

package/src/createMutation.svelte.ts

@@ -13,9 +13,6 @@ import type { DefaultError, QueryClient } from '@tanstack/query-core'
 /**
  * Unlike queries, mutations are typically used to create/update/delete data or perform server side-effects.
  * `createMutation` is the function for that.
- *
- * @see {@link mutationOptions} to share these options across multiple `createMutation` call sites, or to look
- * the mutation up elsewhere via its `mutationKey` (e.g. with `useMutationState`).
  * @param options - The {@link CreateMutationOptions} to use, wrapped in an {@link Accessor} so options can be
  * reactive.
  * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
@@ -24,7 +21,8 @@ import type { DefaultError, QueryClient } from '@tanstack/query-core'
  * argument, useful for triggering call-site side effects (e.g. navigation) without coupling them to the shared
  * mutation definition. If you make multiple requests, `onSuccess` will fire only after the latest call you've
  * made.
- *
+ * @see {@link mutationOptions} to share these options across multiple `createMutation` call sites, or to look
+ * the mutation up elsewhere via its `mutationKey` (e.g. with `useMutationState`).
  * @example
  * ```svelte
  * <script lang="ts">
@@ -48,7 +46,6 @@ import type { DefaultError, QueryClient } from '@tanstack/query-core'
  *   Add
  * </button>
  * ```
- *
  * @example
  * Rendering the mutation's own state, rather than just firing it off:
  * ```svelte
@@ -72,7 +69,6 @@ import type { DefaultError, QueryClient } from '@tanstack/query-core'
  *   <button onclick={() => addMutation.mutate('Item')}>Add</button>
  * {/if}
  * ```
- *
  * @example
  * Optimistic update via `onMutate`, rolling back on `onError`:
  * ```svelte
@@ -106,7 +102,6 @@ import type { DefaultError, QueryClient } from '@tanstack/query-core'
  *
  * <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:
@@ -134,7 +129,6 @@ import type { DefaultError, QueryClient } from '@tanstack/query-core'
  *   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

package/src/createQueries.svelte.ts

@@ -188,14 +188,12 @@ export type QueriesResults<
 
 /**
  * The `createQueries` function can be used to fetch a variable number of queries.
- *
  * @param createQueriesOptions - The `queries` array to run, and an optional `combine` function, wrapped in an
  * {@link Accessor} so options can be reactive.
  * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context
  * will be used.
  * @returns An array with one result per query, in the same order as `queries` — or, if `combine` is provided,
  * whatever `combine` returns.
- *
  * @example
  * ```svelte
  * <script lang="ts">
@@ -224,7 +222,6 @@ export type QueriesResults<
  *   {/each}
  * </ul>
  * ```
- *
  * @example
  * Combining results into a single value:
  * ```svelte
@@ -297,6 +294,10 @@ export function createQueries<
     ),
   )
 
+  /**
+   * Computes the combined result of the observer's queries for the resolved options.
+   * @returns The combined result, built from the tracked per-query results.
+   */
   function createResult() {
     const [_, getCombinedResult, trackResult] = observer.getOptimisticResult(
       resolvedQueryOptions,

package/src/createQuery.ts

@@ -18,8 +18,6 @@ import type {
  *
  * This overload is selected when `initialData` is set, so the resulting `data` is never `undefined` (unless
  * a `select` changes `TData` to include `undefined`).
- *
- * @see {@link queryOptions} to share these options between `createQuery` and imperative APIs like `queryClient.query`.
  * @param options - The {@link DefinedInitialDataOptions} to use — everything you can pass to `createQuery`,
  * with `initialData` set, wrapped in an {@link Accessor} so options can be reactive.
  * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
@@ -27,7 +25,7 @@ import type {
  * @returns The current query result, 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.
- *
+ * @see {@link queryOptions} to share these options between `createQuery` and imperative APIs like `queryClient.query`.
  * @example
  * ```svelte
  * <script lang="ts">
@@ -67,8 +65,6 @@ export function createQuery<
 /**
  * Subscribes to a query: a declarative dependency on an asynchronous source of data that is tied to a unique key.
  * The query runs when the options call for it — `enabled: false` skips the initial fetch.
- *
- * @see {@link queryOptions} to share these options between `createQuery` and imperative APIs like `queryClient.query`.
  * @param options - The {@link UndefinedInitialDataOptions} to use — everything you can pass to `createQuery`,
  * wrapped in an {@link Accessor} so options can be reactive.
  * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
@@ -76,7 +72,7 @@ export function createQuery<
  * @returns The current query result. `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.
- *
+ * @see {@link queryOptions} to share these options between `createQuery` and imperative APIs like `queryClient.query`.
  * @example
  * ```svelte
  * <script lang="ts">
@@ -100,7 +96,6 @@ export function createQuery<
  *   </ul>
  * {/if}
  * ```
- *
  * @example
  * The same query, checking `isPending`/`isError` instead of `status` — pick whichever reads better to you:
  * ```svelte
@@ -139,7 +134,9 @@ export function createQuery<
 ): CreateQueryResult<TData, TError>
 
 /**
- * @see {@link queryOptions} to share these options between `createQuery` and imperative APIs like `queryClient.query`.
+ * Fallback overload for options whose `initialData` presence isn't statically known — for example, an
+ * object typed as {@link CreateQueryOptions} rather than an object literal. Prefer one of the other
+ * overloads when possible, since they infer whether `data` can be `undefined` from `initialData` directly.
  * @param options - The {@link CreateQueryOptions} to use — everything you can pass to `createQuery`, wrapped
  * in an {@link Accessor} so options can be reactive.
  * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
@@ -147,7 +144,7 @@ export function createQuery<
  * @returns The current query result. `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.
- *
+ * @see {@link queryOptions} to share these options between `createQuery` and imperative APIs like `queryClient.query`.
  * @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`:
@@ -170,7 +167,6 @@ export function createQuery<
  *   <span>{query.data} posts</span>
  * {/if}
  * ```
- *
  * @example
  * A dependent query, only enabled once `postId` is set — use `isLoading`, not `isPending`, so the
  * loading state doesn't show while the query is disabled:
@@ -197,7 +193,6 @@ export function createQuery<
  *   <h1>{query.data?.title}</h1>
  * {/if}
  * ```
- *
  * @example
  * Seeding a detail query from an already-cached list, to skip the loading state:
  * ```svelte
@@ -223,7 +218,6 @@ export function createQuery<
  * {/if}
  * <h1>{query.data?.title}</h1>
  * ```
- *
  * @example
  * Paginated data, keeping the previous page's data visible while the next page loads:
  * ```svelte

package/src/infiniteQueryOptions.ts

@@ -8,6 +8,10 @@ import type {
 } from '@tanstack/query-core'
 import type { CreateInfiniteQueryOptions } from './types.js'
 
+/**
+ * The options accepted by the `infiniteQueryOptions` overload selected when `initialData` is omitted or may
+ * be `undefined` — `data` may be `undefined` while the query is `pending`.
+ */
 export type UndefinedInitialDataInfiniteOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -29,6 +33,10 @@ export type UndefinedInitialDataInfiniteOptions<
       >
 }
 
+/**
+ * The options accepted by the `infiniteQueryOptions` overload selected when `initialData` is known to be
+ * defined — `data` is never `undefined` (unless a `select` changes `TData` to include `undefined`).
+ */
 export type DefinedInitialDataInfiniteOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -53,12 +61,10 @@ export type DefinedInitialDataInfiniteOptions<
  * `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for.
  *
  * This overload is selected when `initialData` is known to be defined.
- *
- * @see {@link createInfiniteQuery} to run an infinite query with these options.
  * @param options - The {@link DefinedInitialDataInfiniteOptions} to use — everything you can pass to
  * `createInfiniteQuery`, with `initialData` set.
  * @returns The same options object, typed so that `queryKey` carries the inferred data type.
- *
+ * @see {@link createInfiniteQuery} to run an infinite query with these options.
  * @example
  * `initialData` skips the loading state on first render — even if a refetch fails, the list stays
  * visible alongside the error:
@@ -116,12 +122,10 @@ export function infiniteQueryOptions<
  * You can generally pass everything to `infiniteQueryOptions` that you can also pass to `createInfiniteQuery`.
  * These options can be shared across `createInfiniteQuery` calls and imperative APIs such as
  * `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for.
- *
- * @see {@link createInfiniteQuery} to run an infinite query with these options.
  * @param options - The {@link UndefinedInitialDataInfiniteOptions} to use — everything you can pass to
  * `createInfiniteQuery`.
  * @returns The same options object, typed so that `queryKey` carries the inferred data type.
- *
+ * @see {@link createInfiniteQuery} to run an infinite query with these options.
  * @example
  * A parameterized factory, so the same options object can be reused per `postId`:
  * ```svelte

package/src/mutationOptions.ts

@@ -5,11 +5,9 @@ import type { CreateMutationOptions } from './types.js'
  * You can generally pass everything to `mutationOptions` that you can also pass to `createMutation`. This
  * overload requires `mutationKey`, so the resulting options can be looked up elsewhere (e.g. with
  * `useMutationState`).
- *
- * @see {@link createMutation} to run a mutation with these options.
  * @param options - The options to use — everything you can pass to `createMutation`, with `mutationKey` set.
  * @returns The same options object.
- *
+ * @see {@link createMutation} to run a mutation with these options.
  * @example
  * Looking the mutation up elsewhere via its `mutationKey`, e.g. for a global "saving…" indicator:
  * ```svelte
@@ -48,11 +46,9 @@ export function mutationOptions<
 
 /**
  * You can generally pass everything to `mutationOptions` that you can also pass to `createMutation`.
- *
- * @see {@link createMutation} to run a mutation with these options.
  * @param options - The options to use — everything you can pass to `createMutation`.
  * @returns The same options object.
- *
+ * @see {@link createMutation} to run a mutation with these options.
  * @example
  * ```svelte
  * <script lang="ts">

package/src/queryOptions.ts

@@ -7,6 +7,10 @@ import type {
 } from '@tanstack/query-core'
 import type { CreateQueryOptions } from './types.js'
 
+/**
+ * The options accepted by the `queryOptions` overload selected when `initialData` is omitted or may be
+ * `undefined` — `data` may be `undefined` while the query is `pending`.
+ */
 export type UndefinedInitialDataOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -19,6 +23,10 @@ export type UndefinedInitialDataOptions<
     | NonUndefinedGuard<TQueryFnData>
 }
 
+/**
+ * The options accepted by the `queryOptions` overload selected when `initialData` is set — `data` is never
+ * `undefined` (unless a `select` changes `TData` to include `undefined`).
+ */
 export type DefinedInitialDataOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -26,7 +34,8 @@ export type DefinedInitialDataOptions<
   TQueryKey extends QueryKey = QueryKey,
 > = CreateQueryOptions<TQueryFnData, TError, TData, TQueryKey> & {
   initialData:
-    NonUndefinedGuard<TQueryFnData> | (() => NonUndefinedGuard<TQueryFnData>)
+    | NonUndefinedGuard<TQueryFnData>
+    | (() => NonUndefinedGuard<TQueryFnData>)
 }
 
 /**
@@ -36,12 +45,10 @@ export type DefinedInitialDataOptions<
  *
  * This overload is selected when `initialData` is set, so the resulting `data` is never `undefined` (unless
  * a `select` changes `TData` to include `undefined`).
- *
- * @see {@link createQuery} to run a query with these options.
  * @param options - The {@link DefinedInitialDataOptions} to use — everything you can pass to `createQuery`,
  * with `initialData` set.
  * @returns The same options object, typed so that `queryKey` carries the inferred data type.
- *
+ * @see {@link createQuery} to run a query with these options.
  * @example
  * ```svelte
  * <script lang="ts">
@@ -82,11 +89,9 @@ export function queryOptions<
  * You can generally pass everything to `queryOptions` that you can also pass to `createQuery`. These options
  * can be shared across `createQuery` calls and imperative APIs such as `queryClient.query`. `options.queryKey`
  * is required and is the query key to generate options for.
- *
- * @see {@link createQuery} to run a query with these options.
  * @param options - The {@link UndefinedInitialDataOptions} to use — everything you can pass to `createQuery`.
  * @returns The same options object, typed so that `queryKey` carries the inferred data type.
- *
+ * @see {@link createQuery} to run a query with these options.
  * @example
  * A parameterized factory, so the same options object can be reused per `id`:
  * ```svelte

package/src/types.ts

@@ -19,6 +19,10 @@ import type {
   QueryObserverResult,
 } from '@tanstack/query-core'
 
+/**
+ * A function that returns a value. Options passed as an accessor are read inside reactive contexts, so they
+ * update when the state they read changes.
+ */
 export type Accessor<T> = () => T
 
 /** Options for createBaseQuery */
@@ -100,6 +104,11 @@ export type CreateMutationOptions<
   '_defaulted'
 >
 
+/**
+ * The type of `mutate`, as returned by `createMutation`. Forwards the variables (and an optional per-call
+ * `onSuccess`/`onError`/`onSettled`) to the underlying `mutate` call. Fire-and-forget — errors are surfaced
+ * through the mutation result, not thrown.
+ */
 export type CreateMutateFunction<
   TData = unknown,
   TError = DefaultError,
@@ -111,6 +120,10 @@ export type CreateMutateFunction<
   >
 ) => void
 
+/**
+ * The type of `mutateAsync`, as returned by `createMutation`. Similar to {@link CreateMutateFunction}, but
+ * returns a promise which can be awaited.
+ */
 export type CreateMutateAsyncFunction<
   TData = unknown,
   TError = DefaultError,
@@ -118,6 +131,11 @@ export type CreateMutateAsyncFunction<
   TOnMutateResult = unknown,
 > = MutateFunction<TData, TError, TVariables, TOnMutateResult>
 
+/**
+ * The result of `createMutation`. Same as {@link MutationObserverResult} from `@tanstack/query-core`, with
+ * `mutate` narrowed to the fire-and-forget {@link CreateMutateFunction} signature, plus the added
+ * `mutateAsync`.
+ */
 export type CreateBaseMutationResult<
   TData = unknown,
   TError = DefaultError,
@@ -143,6 +161,10 @@ export type CreateMutationResult<
   TOnMutateResult = unknown,
 > = CreateBaseMutationResult<TData, TError, TVariables, TOnMutateResult>
 
+/**
+ * Infers the `Mutation` type passed to `useMutationState`'s `select` from the `MutationState` type it
+ * returns, falling back to `Mutation` otherwise.
+ */
 export type MutationTypeFromResult<TResult> = [TResult] extends [
   MutationState<
     infer TData,
@@ -160,11 +182,26 @@ export type MutationStateOptions<
   TMutation extends Mutation<any, any, any, any> =
     MutationTypeFromResult<TResult>,
 > = {
+  /**
+   * The filters that select the mutations to return the state of.
+   */
   filters?: MutationFilters
+  /**
+   * Maps each matching mutation to the value returned for it. Defaults to the mutation's `state`.
+   */
   select?: (mutation: TMutation) => TResult
 }
 
+/**
+ * The props accepted by `QueryClientProvider`.
+ */
 export type QueryClientProviderProps = {
+  /**
+   * The `QueryClient` to provide to the children.
+   */
   client: QueryClient
+  /**
+   * The children that can use the provided `QueryClient`.
+   */
   children: Snippet
 }

package/src/useHydrate.ts

@@ -7,12 +7,10 @@ import type { HydrateOptions, QueryClient } from '@tanstack/query-core'
  * passed explicitly). If the client already contains data, the new queries will be intelligently merged based
  * on update timestamp. `HydrationBoundary` wraps this — use it directly only if you need to hydrate from your
  * own component instead.
- *
  * @param state - The dehydrated state to hydrate into the cache, as produced by `dehydrate`.
  * @param options - {@link HydrateOptions} to control the hydration.
  * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
  * be used.
- *
  * @example
  * Server-side prefetch handed off to the client via `dehydrate` — `dehydratedState` would typically come
  * from a server load function that prefetched with `queryClient.query` and called `dehydrate(queryClient)`:

package/src/useIsFetching.svelte.ts

@@ -5,13 +5,11 @@ import type { QueryClient, QueryFilters } from '@tanstack/query-core'
 /**
  * The `useIsFetching` function returns the `number` of the queries that your application is loading or
  * fetching in the background (useful for app-wide loading indicators).
- *
  * @param filters - {@link QueryFilters} to narrow down which queries to count. Omit to count every fetching
  * query.
  * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
  * be used.
  * @returns A reactive value — read `.current` to get how many matching queries are currently fetching.
- *
  * @example
  * ```svelte
  * <script lang="ts">
@@ -25,7 +23,6 @@ import type { QueryClient, QueryFilters } from '@tanstack/query-core'
  *   <span>Refreshing posts...</span>
  * {/if}
  * ```
- *
  * @example
  * A global loading indicator for any query fetching in the background, not just the ones on screen:
  * ```svelte

package/src/useIsMutating.svelte.ts

@@ -5,12 +5,10 @@ import type { MutationFilters, QueryClient } from '@tanstack/query-core'
 /**
  * `useIsMutating` is an optional function that returns the `number` of mutations that your application is
  * running (useful for app-wide loading indicators).
- *
  * @param filters - {@link MutationFilters} to narrow down which mutations to count.
  * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
  * be used.
  * @returns A reactive value — read `.current` to get how many matching mutations are currently running.
- *
  * @example
  * ```svelte
  * <script lang="ts">

package/src/useIsRestoring.ts

@@ -5,7 +5,6 @@ import type { Box } from './containers.svelte.js'
  * If you are using `PersistQueryClientProvider`, you can also use the `useIsRestoring` function alongside it to
  * check if a restore is currently in progress. `createQuery` and friends also check this internally to avoid
  * race conditions between the restore and mounting queries.
- *
  * @returns A reactive box — read `.current` for `true` while a persisted client is being restored, `false`
  * otherwise.
  * @example

package/src/useMutationState.svelte.ts

@@ -8,6 +8,13 @@ import type {
 } from '@tanstack/query-core'
 import type { MutationStateOptions, MutationTypeFromResult } from './types.js'
 
+/**
+ * Collects the mutations in the cache that match `options.filters`, mapped with `options.select`
+ * (or to their state, by default).
+ * @param mutationCache - The mutation cache to read.
+ * @param options - The `filters` to match and the `select` function to map each mutation with.
+ * @returns The selected value of every matching mutation.
+ */
 function getResult<
   TResult = MutationState,
   TMutation extends Mutation<any, any, any, any> =
@@ -30,13 +37,11 @@ function getResult<
  * `useMutationState` is a function 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 - The `filters` to narrow down matched mutations, and an optional `select` to transform the
  * mutation state.
  * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
  * be used.
  * @returns An Array of whatever `select` returns for each matching mutation.
- *
  * @example
  * Get all variables of all running mutations:
  * ```svelte
@@ -51,7 +56,6 @@ function getResult<
  *
  * {pendingVariables.length} posts saving...
  * ```
- *
  * @example
  * Get all data for specific mutations via the `mutationKey`:
  * ```svelte
@@ -77,7 +81,6 @@ function getResult<
  *   Create post ({savedPosts.length} saved so far)
  * </button>
  * ```
- *
  * @example
  * Access the latest mutation data via the `mutationKey`. Each invocation of `mutate` adds a new entry to the
  * mutation cache for `gcTime` milliseconds — check the last item that `useMutationState` returns to get the

package/src/useQueryClient.ts

@@ -3,11 +3,11 @@ import type { QueryClient } from '@tanstack/query-core'
 
 /**
  * The `useQueryClient` function 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.
+ * @throws {Error} If no `queryClient` argument is passed and no `QueryClientProvider` is found in the
+ * component tree.
  * @example
  * ```svelte
  * <script lang="ts">

package/src/utils.svelte.ts

@@ -1,5 +1,10 @@
 import { untrack } from 'svelte'
 // modified from the great https://github.com/svecosystem/runed
+/**
+ * Runs an effect after (`'post'`) or before (`'pre'`) the DOM updates.
+ * @param flush - When to run the effect: `'post'` uses `$effect`, `'pre'` uses `$effect.pre`.
+ * @param effect - The effect to run. It may return a cleanup function.
+ */
 function runEffect(
   flush: 'post' | 'pre',
   effect: () => void | VoidFunction,
@@ -14,6 +19,14 @@ function runEffect(
   }
 }
 type Getter<T> = () => T
+/**
+ * Runs `effect` whenever the reactive state read by `sources` changes, even if they return the
+ * same values, skipping the first run. The effect receives the new and previous values, and is
+ * called untracked, so only `sources` are tracked.
+ * @param sources - The getter, or array of getters, to watch.
+ * @param flush - Whether to run after (`'post'`) or before (`'pre'`) the DOM updates.
+ * @param effect - Called with the new and previous values. It may return a cleanup function.
+ */
 export const watchChanges = <T>(
   sources: Getter<T> | Array<Getter<T>>,
   flush: 'post' | 'pre',