@tanstack/svelte-query 6.1.48 → 6.2.1

package/src/mutationOptions.ts

@@ -1,6 +1,36 @@
 import type { DefaultError, WithRequired } from '@tanstack/query-core'
 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.
+ *
+ * @example
+ * Looking the mutation up elsewhere via its `mutationKey`, e.g. for a global "saving…" indicator:
+ * ```svelte
+ * <script lang="ts">
+ *   import { mutationOptions, useMutationState } from '@tanstack/svelte-query'
+ *
+ *   const createPostOptions = mutationOptions({
+ *     mutationKey: ['posts', 'create'],
+ *     mutationFn: createPost,
+ *   })
+ *
+ *   const pending = useMutationState({
+ *     filters: { mutationKey: createPostOptions.mutationKey, status: 'pending' },
+ *   })
+ * </script>
+ *
+ * {#if pending.length > 0}
+ *   <span>Saving…</span>
+ * {/if}
+ * ```
+ */
 export function mutationOptions<
   TData = unknown,
   TError = DefaultError,
@@ -15,6 +45,29 @@ export function mutationOptions<
   CreateMutationOptions<TData, TError, TVariables, TOnMutateResult>,
   'mutationKey'
 >
+
+/**
+ * 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.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { mutationOptions, createMutation } from '@tanstack/svelte-query'
+ *
+ *   const createPostOptions = mutationOptions({
+ *     mutationFn: createPost,
+ *   })
+ *
+ *   const mutation = createMutation(() => createPostOptions)
+ * </script>
+ *
+ * <button onclick={() => mutation.mutate({ title: 'Hello' })}>Create</button>
+ * ```
+ */
 export function mutationOptions<
   TData = unknown,
   TError = DefaultError,

package/src/queryOptions.ts

@@ -27,6 +27,44 @@ export type DefinedInitialDataOptions<
     | (() => NonUndefinedGuard<TQueryFnData>)
 }
 
+/**
+ * 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.
+ *
+ * This overload is selected when `initialData` is set, so the resulting `data` is never `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.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { queryOptions, createQuery } from '@tanstack/svelte-query'
+ *
+ *   const postsOptions = queryOptions({
+ *     queryKey: ['posts'],
+ *     queryFn: fetchPosts,
+ *     initialData: [],
+ *   })
+ *
+ *   // `data` is `Post[]`, never `undefined`, thanks to `initialData` — even if a refetch fails,
+ *   // so the list stays visible alongside the error.
+ *   const query = createQuery(() => postsOptions)
+ * </script>
+ *
+ * {#if query.isError}
+ *   <span>Error: {query.error.message}</span>
+ * {/if}
+ * <ul>
+ *   {#each query.data as post (post.id)}
+ *     <li>{post.title}</li>
+ *   {/each}
+ * </ul>
+ * ```
+ */
 export function queryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -37,6 +75,41 @@ export function queryOptions<
 ): DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey> &
   QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>
 
+/**
+ * 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.
+ *
+ * @example
+ * A parameterized factory, so the same options object can be reused per `id`:
+ * ```svelte
+ * <script lang="ts">
+ *   import { queryOptions, createQuery } from '@tanstack/svelte-query'
+ *
+ *   let { id }: { id: string } = $props()
+ *
+ *   const postOptions = (id: string) =>
+ *     queryOptions({
+ *       queryKey: ['post', id],
+ *       queryFn: () => fetchPost(id),
+ *     })
+ *
+ *   const query = createQuery(() => postOptions(id))
+ * </script>
+ *
+ * {#if query.isPending}
+ *   Loading...
+ * {:else if query.isError}
+ *   <span>Error: {query.error.message}</span>
+ * {:else}
+ *   <h1>{query.data.title}</h1>
+ * {/if}
+ * ```
+ */
 export function queryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,

package/src/types.ts

@@ -1,6 +1,7 @@
 import type { Snippet } from 'svelte'
 import type {
   DefaultError,
+  DefinedInfiniteQueryObserverResult,
   DefinedQueryObserverResult,
   InfiniteQueryObserverOptions,
   InfiniteQueryObserverResult,
@@ -70,6 +71,12 @@ export type CreateInfiniteQueryResult<
   TError = DefaultError,
 > = InfiniteQueryObserverResult<TData, TError>
 
+/** Result from createInfiniteQuery with initialData */
+export type DefinedCreateInfiniteQueryResult<
+  TData = unknown,
+  TError = DefaultError,
+> = DefinedInfiniteQueryObserverResult<TData, TError>
+
 /** Options for createBaseQuery with initialData */
 export type DefinedCreateBaseQueryResult<
   TData = unknown,

package/src/useHydrate.ts

@@ -2,6 +2,34 @@ import { hydrate } from '@tanstack/query-core'
 import { useQueryClient } from './useQueryClient.js'
 import type { HydrateOptions, QueryClient } from '@tanstack/query-core'
 
+/**
+ * Adds a previously dehydrated `state` into the `queryClient` (from the nearest context, or the one
+ * 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)`:
+ * ```svelte
+ * <script lang="ts">
+ *   import { HydrationBoundary } from '@tanstack/svelte-query'
+ *   import type { DehydratedState } from '@tanstack/svelte-query'
+ *   import Posts from './Posts.svelte'
+ *
+ *   let { dehydratedState }: { dehydratedState: DehydratedState } = $props()
+ * </script>
+ *
+ * <HydrationBoundary state={dehydratedState}>
+ *   <Posts />
+ * </HydrationBoundary>
+ * ```
+ */
 export function useHydrate(
   state?: unknown,
   options?: HydrateOptions,

package/src/useIsFetching.svelte.ts

@@ -2,6 +2,41 @@ import { ReactiveValue } from './containers.svelte.js'
 import { useQueryClient } from './useQueryClient.js'
 import type { QueryClient, QueryFilters } from '@tanstack/query-core'
 
+/**
+ * @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">
+ *   import { useIsFetching } from '@tanstack/svelte-query'
+ *
+ *   // How many queries matching the posts prefix are fetching?
+ *   const isFetchingPosts = useIsFetching({ queryKey: ['posts'] })
+ * </script>
+ *
+ * {#if isFetchingPosts.current}
+ *   <span>Refreshing posts...</span>
+ * {/if}
+ * ```
+ *
+ * @example
+ * A global loading indicator for any query fetching in the background, not just the ones on screen:
+ * ```svelte
+ * <script lang="ts">
+ *   import { useIsFetching } from '@tanstack/svelte-query'
+ *
+ *   const isFetching = useIsFetching()
+ * </script>
+ *
+ * {#if isFetching.current}
+ *   <div>Queries are fetching in the background...</div>
+ * {/if}
+ * ```
+ */
 export function useIsFetching(
   filters?: QueryFilters,
   queryClient?: QueryClient,

package/src/useIsMutating.svelte.ts

@@ -2,6 +2,29 @@ import { useQueryClient } from './useQueryClient.js'
 import { ReactiveValue } from './containers.svelte.js'
 import type { MutationFilters, QueryClient } from '@tanstack/query-core'
 
+/**
+ * `useIsMutating` is an optional hook 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">
+ *   import { useIsMutating } from '@tanstack/svelte-query'
+ *
+ *   // How many mutations matching the posts prefix are in progress?
+ *   const isMutatingPosts = useIsMutating({ mutationKey: ['posts'] })
+ * </script>
+ *
+ * {#if isMutatingPosts.current}
+ *   <span>Saving posts...</span>
+ * {/if}
+ * ```
+ */
 export function useIsMutating(
   filters?: MutationFilters,
   queryClient?: QueryClient,

package/src/useMutationState.svelte.ts

@@ -26,6 +26,76 @@ function getResult<
     )
 }
 
+/**
+ * `useMutationState` gives you access to all mutations (matching the given `filters`), including ones that
+ * were created by a different component or hook instance, or even ones no longer mounted.
+ *
+ * @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
+ * <script lang="ts">
+ *   import { useMutationState } from '@tanstack/svelte-query'
+ *
+ *   const pendingVariables = useMutationState({
+ *     filters: { status: 'pending' },
+ *     select: (mutation) => mutation.state.variables,
+ *   })
+ * </script>
+ *
+ * {pendingVariables.length} posts saving...
+ * ```
+ *
+ * @example
+ * Get all data for specific mutations via the `mutationKey`:
+ * ```svelte
+ * <script lang="ts">
+ *   import { createMutation, useMutationState } from '@tanstack/svelte-query'
+ *
+ *   const mutationKey = ['posts']
+ *
+ *   // Some mutation that we want to get the state for
+ *   const mutation = createMutation(() => ({
+ *     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,
+ *   })
+ * </script>
+ *
+ * <button onclick={() => mutation.mutate(['New Post'])}>
+ *   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
+ * latest successful mutation (the `status: 'success'` filter above excludes pending/errored ones):
+ * ```svelte
+ * <script lang="ts">
+ *   import { useMutationState } from '@tanstack/svelte-query'
+ *
+ *   const savedPosts = useMutationState({
+ *     filters: { mutationKey: ['posts'], status: 'success' },
+ *     select: (mutation) => mutation.state.data,
+ *   })
+ *
+ *   const latestSavedPost = $derived(savedPosts[savedPosts.length - 1])
+ * </script>
+ *
+ * {latestSavedPost ? 'Saved' : 'Nothing saved yet'}
+ * ```
+ */
 export function useMutationState<
   TResult = MutationState,
   TMutation extends Mutation<any, any, any, any> =