@tanstack/svelte-query 6.1.48 → 6.2.1

package/src/createMutation.svelte.ts

@@ -11,8 +11,162 @@ import type {
 import type { DefaultError, QueryClient } from '@tanstack/query-core'
 
 /**
- * @param options - A function that returns mutation options
- * @param queryClient - Custom query client which overrides provider
+ * 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
+ * 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. If you make multiple requests, `onSuccess` will fire only after the latest call you've
+ * made.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { createMutation, useQueryClient } from '@tanstack/svelte-query'
+ *
+ *   const queryClient = useQueryClient()
+ *
+ *   const addMutation = createMutation(() => ({
+ *     mutationFn: addTodo,
+ *     onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
+ *   }))
+ * </script>
+ *
+ * <button
+ *   onclick={() =>
+ *     addMutation.mutate('Item', {
+ *       onError: (error) => console.error('Failed to add item:', error),
+ *     })
+ *   }
+ * >
+ *   Add
+ * </button>
+ * ```
+ *
+ * @example
+ * Rendering the mutation's own state, rather than just firing it off:
+ * ```svelte
+ * <script lang="ts">
+ *   import { createMutation, useQueryClient } from '@tanstack/svelte-query'
+ *
+ *   const queryClient = useQueryClient()
+ *
+ *   const addMutation = createMutation(() => ({
+ *     mutationFn: addTodo,
+ *     onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
+ *   }))
+ * </script>
+ *
+ * {#if addMutation.isPending}
+ *   Adding todo...
+ * {:else}
+ *   {#if addMutation.isError}
+ *     <div>An error occurred: {addMutation.error.message}</div>
+ *   {/if}
+ *   <button onclick={() => addMutation.mutate('Item')}>Add</button>
+ * {/if}
+ * ```
+ *
+ * @example
+ * Optimistic update via `onMutate`, rolling back on `onError`:
+ * ```svelte
+ * <script lang="ts">
+ *   import { createMutation, useQueryClient } from '@tanstack/svelte-query'
+ *
+ *   const queryClient = useQueryClient()
+ *
+ *   const addMutation = createMutation(() => ({
+ *     mutationFn: addTodo,
+ *     onMutate: async (newTodo: string) => {
+ *       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'] })
+ *     },
+ *   }))
+ * </script>
+ *
+ * <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:
+ * ```svelte
+ * <script lang="ts">
+ *   import { createMutation, useQueryClient } from '@tanstack/svelte-query'
+ *
+ *   const queryClient = useQueryClient()
+ *
+ *   const addMutation = createMutation(() => ({
+ *     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)
+ *     }
+ *   }
+ * </script>
+ *
+ * <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`:
+ * ```svelte
+ * <script lang="ts">
+ *   import { createMutation, useQueryClient } from '@tanstack/svelte-query'
+ *
+ *   const queryClient = useQueryClient()
+ *
+ *   const addMutation = createMutation(() => ({
+ *     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)
+ *       }
+ *     })
+ *   }
+ * </script>
+ *
+ * <button onclick={() => handleAddAll(['Todo 1', 'Todo 2', 'Todo 3'])}>
+ *   Add all
+ * </button>
+ * ```
  */
 export function createMutation<
   TData = unknown,

package/src/createQueries.svelte.ts

@@ -186,6 +186,77 @@ export type QueriesResults<
           >
         : { [K in keyof T]: GetCreateQueryResult<T[K]> }
 
+/**
+ * @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">
+ *   import { createQueries } from '@tanstack/svelte-query'
+ *
+ *   let { ids }: { ids: Array<number> } = $props()
+ *
+ *   const postQueries = createQueries(() => ({
+ *     queries: ids.map((id) => ({
+ *       queryKey: ['post', id],
+ *       queryFn: () => fetchPost(id),
+ *       staleTime: Infinity,
+ *     })),
+ *   }))
+ * </script>
+ *
+ * <ul>
+ *   {#each postQueries as query, index (ids[index])}
+ *     {#if query.isPending}
+ *       <li>Loading...</li>
+ *     {:else if query.isError}
+ *       <li>Error: {query.error.message}</li>
+ *     {:else}
+ *       <li>{query.data.title}</li>
+ *     {/if}
+ *   {/each}
+ * </ul>
+ * ```
+ *
+ * @example
+ * Combining results into a single value:
+ * ```svelte
+ * <script lang="ts">
+ *   import { createQueries } from '@tanstack/svelte-query'
+ *
+ *   let { ids }: { ids: Array<number> } = $props()
+ *
+ *   const combined = createQueries(() => ({
+ *     queries: ids.map((id) => ({
+ *       queryKey: ['post', id],
+ *       queryFn: () => fetchPost(id),
+ *     })),
+ *     combine: (postQueries) => ({
+ *       data: postQueries.map((query) => query.data),
+ *       isPending: postQueries.some((query) => query.isPending),
+ *       isError: postQueries.some((query) => query.isError),
+ *     }),
+ *   }))
+ * </script>
+ *
+ * {#if combined.isPending}
+ *   Loading...
+ * {:else if combined.isError}
+ *   Error loading posts
+ * {:else}
+ *   <ul>
+ *     {#each combined.data as post}
+ *       <li>{post?.title}</li>
+ *     {/each}
+ *   </ul>
+ * {/if}
+ * ```
+ */
 export function createQueries<
   T extends Array<any>,
   TCombinedResult = QueriesResults<T>,

package/src/createQuery.ts

@@ -12,6 +12,65 @@ import type {
   UndefinedInitialDataOptions,
 } from './queryOptions.js'
 
+/**
+ * @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
+ * be used.
+ * @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.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { createQuery } from '@tanstack/svelte-query'
+ *
+ *   const query = createQuery(() => ({
+ *     queryKey: ['posts'],
+ *     queryFn: fetchPosts,
+ *   }))
+ * </script>
+ *
+ * {#if query.status === 'pending'}
+ *   Loading...
+ * {:else if query.status === 'error'}
+ *   <span>Error: {query.error.message}</span>
+ * {:else}
+ *   <ul>
+ *     {#each query.data as post (post.id)}
+ *       <li>{post.title}</li>
+ *     {/each}
+ *   </ul>
+ * {/if}
+ * ```
+ *
+ * @example
+ * The same query, checking `isPending`/`isError` instead of `status` — pick whichever reads better to you:
+ * ```svelte
+ * <script lang="ts">
+ *   import { createQuery } from '@tanstack/svelte-query'
+ *
+ *   const query = createQuery(() => ({
+ *     queryKey: ['posts'],
+ *     queryFn: fetchPosts,
+ *   }))
+ * </script>
+ *
+ * {#if query.isPending}
+ *   Loading...
+ * {:else if query.isError}
+ *   <span>Error: {query.error.message}</span>
+ * {:else}
+ *   <ul>
+ *     {#each query.data as post (post.id)}
+ *       <li>{post.title}</li>
+ *     {/each}
+ *   </ul>
+ * {/if}
+ * ```
+ */
 export function createQuery<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -24,6 +83,42 @@ export function createQuery<
   queryClient?: Accessor<QueryClient>,
 ): CreateQueryResult<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 `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
+ * be used.
+ * @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.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { createQuery } from '@tanstack/svelte-query'
+ *
+ *   // `data` is `Post[]`, never `undefined`, thanks to `initialData` — even if a refetch fails,
+ *   // so the list stays visible alongside the error.
+ *   const query = createQuery(() => ({
+ *     queryKey: ['posts'],
+ *     queryFn: fetchPosts,
+ *     initialData: [],
+ *   }))
+ * </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 createQuery<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -36,6 +131,120 @@ export function createQuery<
   queryClient?: Accessor<QueryClient>,
 ): DefinedCreateQueryResult<TData, TError>
 
+/**
+ * @see {@link queryOptions} to share these options between `createQuery` and imperative APIs like `queryClient.query`.
+ * @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
+ * be used.
+ * @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.
+ *
+ * @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`:
+ * ```svelte
+ * <script lang="ts">
+ *   import { createQuery } from '@tanstack/svelte-query'
+ *
+ *   const query = createQuery(() => ({
+ *     queryKey: ['posts'],
+ *     queryFn: fetchPosts,
+ *     select: (posts) => posts.length,
+ *   }))
+ * </script>
+ *
+ * {#if query.isPending}
+ *   Loading...
+ * {:else if query.isError}
+ *   <span>Error: {query.error.message}</span>
+ * {:else}
+ *   <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:
+ * ```svelte
+ * <script lang="ts">
+ *   import { createQuery } from '@tanstack/svelte-query'
+ *
+ *   let { postId }: { postId: number | undefined } = $props()
+ *
+ *   const query = createQuery(() => ({
+ *     queryKey: ['post', postId],
+ *     queryFn: () => fetchPost(postId!),
+ *     enabled: postId != null,
+ *   }))
+ * </script>
+ *
+ * {#if postId == null}
+ *   Select a post
+ * {:else if query.isLoading}
+ *   Loading...
+ * {:else if query.isError}
+ *   <span>Error: {query.error.message}</span>
+ * {:else}
+ *   <h1>{query.data?.title}</h1>
+ * {/if}
+ * ```
+ *
+ * @example
+ * Seeding a detail query from an already-cached list, to skip the loading state:
+ * ```svelte
+ * <script lang="ts">
+ *   import { createQuery, useQueryClient } from '@tanstack/svelte-query'
+ *
+ *   let { postId }: { postId: number } = $props()
+ *
+ *   const queryClient = useQueryClient()
+ *
+ *   const query = createQuery(() => ({
+ *     queryKey: ['post', postId],
+ *     queryFn: () => fetchPost(postId),
+ *     initialData: () =>
+ *       queryClient
+ *         .getQueryData<Array<Post>>(['posts'])
+ *         ?.find((post) => post.id === postId),
+ *   }))
+ * </script>
+ *
+ * {#if query.isError}
+ *   <span>Error: {query.error.message}</span>
+ * {/if}
+ * <h1>{query.data?.title}</h1>
+ * ```
+ *
+ * @example
+ * Paginated data, keeping the previous page's data visible while the next page loads:
+ * ```svelte
+ * <script lang="ts">
+ *   import { createQuery, keepPreviousData } from '@tanstack/svelte-query'
+ *
+ *   let page = $state(0)
+ *
+ *   const query = createQuery(() => ({
+ *     queryKey: ['posts', page],
+ *     queryFn: () => fetchPosts(page),
+ *     placeholderData: keepPreviousData,
+ *   }))
+ * </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>
+ * <button disabled={query.isPlaceholderData} onclick={() => page++}>
+ *   Next Page
+ * </button>
+ * ```
+ */
 export function createQuery<
   TQueryFnData,
   TError = DefaultError,

package/src/index.ts

@@ -16,6 +16,10 @@ export type {
 export { queryOptions } from './queryOptions.js'
 export { createQueries } from './createQueries.svelte.js'
 export { createInfiniteQuery } from './createInfiniteQuery.js'
+export type {
+  DefinedInitialDataInfiniteOptions,
+  UndefinedInitialDataInfiniteOptions,
+} from './infiniteQueryOptions.js'
 export { infiniteQueryOptions } from './infiniteQueryOptions.js'
 export { mutationOptions } from './mutationOptions.js'
 export { createMutation } from './createMutation.svelte.js'

package/src/infiniteQueryOptions.ts

@@ -1,6 +1,94 @@
-import type { DefaultError, InfiniteData, QueryKey } from '@tanstack/query-core'
+import type {
+  DefaultError,
+  InfiniteData,
+  InitialDataFunction,
+  NonUndefinedGuard,
+  QueryKey,
+  QueryKeyWithDataTag,
+} from '@tanstack/query-core'
 import type { CreateInfiniteQueryOptions } from './types.js'
 
+export type UndefinedInitialDataInfiniteOptions<
+  TQueryFnData = unknown,
+  TError = DefaultError,
+  TData = InfiniteData<TQueryFnData>,
+  TQueryKey extends QueryKey = QueryKey,
+  TPageParam = unknown,
+> = CreateInfiniteQueryOptions<
+  TQueryFnData,
+  TError,
+  TData,
+  TQueryKey,
+  TPageParam
+> & {
+  initialData?:
+    | undefined
+    | NonUndefinedGuard<InfiniteData<TQueryFnData, TPageParam>>
+    | InitialDataFunction<
+        NonUndefinedGuard<InfiniteData<TQueryFnData, TPageParam>>
+      >
+}
+
+export type DefinedInitialDataInfiniteOptions<
+  TQueryFnData = unknown,
+  TError = DefaultError,
+  TData = InfiniteData<TQueryFnData>,
+  TQueryKey extends QueryKey = QueryKey,
+  TPageParam = unknown,
+> = CreateInfiniteQueryOptions<
+  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 `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.
+ *
+ * This overload is selected when `initialData` is set.
+ *
+ * @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.
+ *
+ * @example
+ * `initialData` skips the loading state on first render — even if a refetch fails, the list stays
+ * visible alongside the error:
+ * ```svelte
+ * <script lang="ts">
+ *   import { infiniteQueryOptions, createInfiniteQuery } from '@tanstack/svelte-query'
+ *
+ *   const projectsOptions = infiniteQueryOptions({
+ *     queryKey: ['projects'],
+ *     queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *     initialPageParam: 0,
+ *     getNextPageParam: (lastPage) => lastPage.nextId,
+ *     initialData: { pages: [], pageParams: [] },
+ *   })
+ *
+ *   const query = createInfiniteQuery(() => projectsOptions)
+ * </script>
+ *
+ * {#if query.isError}
+ *   <span>Error: {query.error.message}</span>
+ * {/if}
+ * <ul>
+ *   {#each query.data.pages as page}
+ *     {#each page.projects as project (project.id)}
+ *       <li>{project.name}</li>
+ *     {/each}
+ *   {/each}
+ * </ul>
+ * ```
+ */
 export function infiniteQueryOptions<
   TQueryFnData,
   TError = DefaultError,
@@ -8,19 +96,89 @@ export function infiniteQueryOptions<
   TQueryKey extends QueryKey = QueryKey,
   TPageParam = unknown,
 >(
-  options: CreateInfiniteQueryOptions<
+  options: DefinedInitialDataInfiniteOptions<
     TQueryFnData,
     TError,
     TData,
     TQueryKey,
     TPageParam
   >,
-): CreateInfiniteQueryOptions<
+): DefinedInitialDataInfiniteOptions<
   TQueryFnData,
   TError,
   TData,
   TQueryKey,
   TPageParam
-> {
+> &
+  QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>
+
+/**
+ * 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.
+ *
+ * @example
+ * A parameterized factory, so the same options object can be reused per `postId`:
+ * ```svelte
+ * <script lang="ts">
+ *   import { infiniteQueryOptions, createInfiniteQuery } from '@tanstack/svelte-query'
+ *
+ *   let { postId }: { postId: string } = $props()
+ *
+ *   const commentsOptions = (postId: string) =>
+ *     infiniteQueryOptions({
+ *       queryKey: ['post', postId, 'comments'],
+ *       queryFn: ({ pageParam }) => fetchComments(postId, pageParam),
+ *       initialPageParam: 0,
+ *       getNextPageParam: (lastPage) => lastPage.nextId,
+ *     })
+ *
+ *   const query = createInfiniteQuery(() => commentsOptions(postId))
+ * </script>
+ *
+ * {#if query.isPending}
+ *   Loading...
+ * {:else if query.isError}
+ *   <span>Error: {query.error.message}</span>
+ * {:else}
+ *   <ul>
+ *     {#each query.data.pages as page}
+ *       {#each page.comments as comment (comment.id)}
+ *         <li>{comment.text}</li>
+ *       {/each}
+ *     {/each}
+ *   </ul>
+ * {/if}
+ * ```
+ */
+export function infiniteQueryOptions<
+  TQueryFnData,
+  TError = DefaultError,
+  TData = InfiniteData<TQueryFnData>,
+  TQueryKey extends QueryKey = QueryKey,
+  TPageParam = unknown,
+>(
+  options: UndefinedInitialDataInfiniteOptions<
+    TQueryFnData,
+    TError,
+    TData,
+    TQueryKey,
+    TPageParam
+  >,
+): UndefinedInitialDataInfiniteOptions<
+  TQueryFnData,
+  TError,
+  TData,
+  TQueryKey,
+  TPageParam
+> &
+  QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>
+
+export function infiniteQueryOptions(options: unknown) {
   return options
 }