diff --git a/docs/framework/svelte/reference/functions/createInfiniteQuery.md b/docs/framework/svelte/reference/functions/createInfiniteQuery.md index 4358640a1d..e7ff6d767c 100644 --- a/docs/framework/svelte/reference/functions/createInfiniteQuery.md +++ b/docs/framework/svelte/reference/functions/createInfiniteQuery.md @@ -9,7 +9,12 @@ title: createInfiniteQuery function createInfiniteQuery(options: Accessor>, queryClient?: Accessor): DefinedCreateInfiniteQueryResult; ``` -Defined in: [packages/svelte-query/src/createInfiniteQuery.ts:21](https://github.com/TanStack/query/blob/main/packages/svelte-query/src/createInfiniteQuery.ts#L21) +Defined in: [packages/svelte-query/src/createInfiniteQuery.ts:36](https://github.com/TanStack/query/blob/main/packages/svelte-query/src/createInfiniteQuery.ts#L36) + +The options for `createInfiniteQuery` are identical to `createQuery`, with the addition of +`initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`. + +This overload is selected when `initialData` is set. ### Type Parameters @@ -39,21 +44,40 @@ Defined in: [packages/svelte-query/src/createInfiniteQuery.ts:21](https://github [`Accessor`](../type-aliases/Accessor.md)\<[`DefinedInitialDataInfiniteOptions`](../type-aliases/DefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\>\> +The [DefinedInitialDataInfiniteOptions](../type-aliases/DefinedInitialDataInfiniteOptions.md) to use — everything you can pass to +`createInfiniteQuery`, with `initialData` set, wrapped in an [Accessor](../type-aliases/Accessor.md) so options can be reactive. + #### queryClient? [`Accessor`](../type-aliases/Accessor.md)\<[`QueryClient`](../classes/QueryClient.md)\> +Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will +be used. + ### Returns [`DefinedCreateInfiniteQueryResult`](../type-aliases/DefinedCreateInfiniteQueryResult.md)\<`TData`, `TError`\> +The current query result, plus `fetchNextPage`/`fetchPreviousPage`/`hasNextPage`/`hasPreviousPage` +to page through the query. + +### See + +[infiniteQueryOptions](infiniteQueryOptions.md) to share these options between `createInfiniteQuery` and imperative APIs +like `queryClient.infiniteQuery`. + ## Call Signature ```ts function createInfiniteQuery(options: Accessor>, queryClient?: Accessor): CreateInfiniteQueryResult; ``` -Defined in: [packages/svelte-query/src/createInfiniteQuery.ts:40](https://github.com/TanStack/query/blob/main/packages/svelte-query/src/createInfiniteQuery.ts#L40) +Defined in: [packages/svelte-query/src/createInfiniteQuery.ts:70](https://github.com/TanStack/query/blob/main/packages/svelte-query/src/createInfiniteQuery.ts#L70) + +The options for `createInfiniteQuery` are identical to `createQuery`, with the addition of +`initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`. + +This overload is selected when `initialData` is not set. ### Type Parameters @@ -83,21 +107,38 @@ Defined in: [packages/svelte-query/src/createInfiniteQuery.ts:40](https://github [`Accessor`](../type-aliases/Accessor.md)\<[`UndefinedInitialDataInfiniteOptions`](../type-aliases/UndefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\>\> +The [UndefinedInitialDataInfiniteOptions](../type-aliases/UndefinedInitialDataInfiniteOptions.md) to use — everything you can pass to +`createInfiniteQuery`, wrapped in an [Accessor](../type-aliases/Accessor.md) so options can be reactive. + #### queryClient? [`Accessor`](../type-aliases/Accessor.md)\<[`QueryClient`](../classes/QueryClient.md)\> +Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will +be used. + ### Returns [`CreateInfiniteQueryResult`](../type-aliases/CreateInfiniteQueryResult.md)\<`TData`, `TError`\> +The current query result, plus `fetchNextPage`/`fetchPreviousPage`/`hasNextPage`/`hasPreviousPage` +to page through the query. + +### See + +[infiniteQueryOptions](infiniteQueryOptions.md) to share these options between `createInfiniteQuery` and imperative APIs +like `queryClient.infiniteQuery`. + ## Call Signature ```ts function createInfiniteQuery(options: Accessor>, queryClient?: Accessor): CreateInfiniteQueryResult; ``` -Defined in: [packages/svelte-query/src/createInfiniteQuery.ts:152](https://github.com/TanStack/query/blob/main/packages/svelte-query/src/createInfiniteQuery.ts#L152) +Defined in: [packages/svelte-query/src/createInfiniteQuery.ts:185](https://github.com/TanStack/query/blob/main/packages/svelte-query/src/createInfiniteQuery.ts#L185) + +The options for `createInfiniteQuery` are identical to `createQuery`, with the addition of +`initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`. ### Type Parameters diff --git a/docs/framework/svelte/reference/functions/createQueries.md b/docs/framework/svelte/reference/functions/createQueries.md index 3c5030de21..56546e5a58 100644 --- a/docs/framework/svelte/reference/functions/createQueries.md +++ b/docs/framework/svelte/reference/functions/createQueries.md @@ -11,7 +11,9 @@ function createQueries(createQueriesOptions: Accessor<{ }>, queryClient?: Accessor): TCombinedResult; ``` -Defined in: [packages/svelte-query/src/createQueries.svelte.ts:260](https://github.com/TanStack/query/blob/main/packages/svelte-query/src/createQueries.svelte.ts#L260) +Defined in: [packages/svelte-query/src/createQueries.svelte.ts:262](https://github.com/TanStack/query/blob/main/packages/svelte-query/src/createQueries.svelte.ts#L262) + +The `createQueries` function can be used to fetch a variable number of queries. ## Type Parameters diff --git a/docs/framework/svelte/reference/functions/createQuery.md b/docs/framework/svelte/reference/functions/createQuery.md index 150f811a74..c55ccef74c 100644 --- a/docs/framework/svelte/reference/functions/createQuery.md +++ b/docs/framework/svelte/reference/functions/createQuery.md @@ -9,7 +9,10 @@ title: createQuery function createQuery(options: Accessor>, queryClient?: Accessor): CreateQueryResult; ``` -Defined in: [packages/svelte-query/src/createQuery.ts:74](https://github.com/TanStack/query/blob/main/packages/svelte-query/src/createQuery.ts#L74) +Defined in: [packages/svelte-query/src/createQuery.ts:77](https://github.com/TanStack/query/blob/main/packages/svelte-query/src/createQuery.ts#L77) + +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. ### Type Parameters @@ -112,7 +115,10 @@ The same query, checking `isPending`/`isError` instead of `status` — pick whic function createQuery(options: Accessor>, queryClient?: Accessor): DefinedCreateQueryResult; ``` -Defined in: [packages/svelte-query/src/createQuery.ts:122](https://github.com/TanStack/query/blob/main/packages/svelte-query/src/createQuery.ts#L122) +Defined in: [packages/svelte-query/src/createQuery.ts:128](https://github.com/TanStack/query/blob/main/packages/svelte-query/src/createQuery.ts#L128) + +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. This overload is selected when `initialData` is set, so the resulting `data` is never `undefined`. @@ -193,7 +199,7 @@ since `initialData` guarantees data upfront). `isSuccess`/`isError` are derived function createQuery(options: Accessor>, queryClient?: Accessor): CreateQueryResult; ``` -Defined in: [packages/svelte-query/src/createQuery.ts:248](https://github.com/TanStack/query/blob/main/packages/svelte-query/src/createQuery.ts#L248) +Defined in: [packages/svelte-query/src/createQuery.ts:254](https://github.com/TanStack/query/blob/main/packages/svelte-query/src/createQuery.ts#L254) ### Type Parameters diff --git a/docs/framework/svelte/reference/functions/useIsFetching.md b/docs/framework/svelte/reference/functions/useIsFetching.md index fc4afd5694..5d3bf0f8dd 100644 --- a/docs/framework/svelte/reference/functions/useIsFetching.md +++ b/docs/framework/svelte/reference/functions/useIsFetching.md @@ -7,7 +7,10 @@ title: useIsFetching function useIsFetching(filters?: QueryFilters, queryClient?: QueryClient): ReactiveValue; ``` -Defined in: [packages/svelte-query/src/useIsFetching.svelte.ts:40](https://github.com/TanStack/query/blob/main/packages/svelte-query/src/useIsFetching.svelte.ts#L40) +Defined in: [packages/svelte-query/src/useIsFetching.svelte.ts:43](https://github.com/TanStack/query/blob/main/packages/svelte-query/src/useIsFetching.svelte.ts#L43) + +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). ## Parameters diff --git a/docs/framework/svelte/reference/functions/useIsRestoring.md b/docs/framework/svelte/reference/functions/useIsRestoring.md index d8ad570c9b..834769f1c5 100644 --- a/docs/framework/svelte/reference/functions/useIsRestoring.md +++ b/docs/framework/svelte/reference/functions/useIsRestoring.md @@ -7,8 +7,29 @@ title: useIsRestoring function useIsRestoring(): Box; ``` -Defined in: [packages/svelte-query/src/useIsRestoring.ts:4](https://github.com/TanStack/query/blob/main/packages/svelte-query/src/useIsRestoring.ts#L4) +Defined in: [packages/svelte-query/src/useIsRestoring.ts:24](https://github.com/TanStack/query/blob/main/packages/svelte-query/src/useIsRestoring.ts#L24) + +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 `Box`\<`boolean`\> + +A reactive box — read `.current` for `true` while a persisted client is being restored, `false` +otherwise. + +## Example + +```svelte + + +{#if isRestoring.current} +
Restoring cached data...
+{/if} +``` diff --git a/docs/framework/svelte/reference/functions/useQueryClient.md b/docs/framework/svelte/reference/functions/useQueryClient.md index e0ad99f8e7..9cd5285c4d 100644 --- a/docs/framework/svelte/reference/functions/useQueryClient.md +++ b/docs/framework/svelte/reference/functions/useQueryClient.md @@ -7,7 +7,9 @@ title: useQueryClient function useQueryClient(queryClient?: QueryClient): QueryClient; ``` -Defined in: [packages/svelte-query/src/useQueryClient.ts:4](https://github.com/TanStack/query/blob/main/packages/svelte-query/src/useQueryClient.ts#L4) +Defined in: [packages/svelte-query/src/useQueryClient.ts:24](https://github.com/TanStack/query/blob/main/packages/svelte-query/src/useQueryClient.ts#L24) + +The `useQueryClient` function returns the current `QueryClient` instance. ## Parameters @@ -15,6 +17,29 @@ Defined in: [packages/svelte-query/src/useQueryClient.ts:4](https://github.com/T [`QueryClient`](../classes/QueryClient.md) +Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will +be used. + ## Returns [`QueryClient`](../classes/QueryClient.md) + +The current `QueryClient` instance. + +## Throws + +If no `queryClient` argument is passed and no `QueryClientProvider` is found in the component tree. + +## Example + +```svelte + +``` diff --git a/packages/svelte-query/src/createInfiniteQuery.ts b/packages/svelte-query/src/createInfiniteQuery.ts index d4f71f0544..ff5ca43153 100644 --- a/packages/svelte-query/src/createInfiniteQuery.ts +++ b/packages/svelte-query/src/createInfiniteQuery.ts @@ -18,6 +18,21 @@ import type { UndefinedInitialDataInfiniteOptions, } from './infiniteQueryOptions.js' +/** + * The options for `createInfiniteQuery` are identical to `createQuery`, with the addition of + * `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`. + * + * This overload is selected when `initialData` is set. + * + * @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. + */ export function createInfiniteQuery< TQueryFnData = unknown, TError = DefaultError, @@ -37,6 +52,21 @@ export function createInfiniteQuery< queryClient?: Accessor, ): DefinedCreateInfiniteQueryResult +/** + * The options for `createInfiniteQuery` are identical to `createQuery`, with the addition of + * `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`. + * + * This overload is selected when `initialData` is not set. + * + * @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. + */ export function createInfiniteQuery< TQueryFnData = unknown, TError = DefaultError, @@ -57,6 +87,9 @@ export function createInfiniteQuery< ): CreateInfiniteQueryResult /** + * 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 diff --git a/packages/svelte-query/src/createQueries.svelte.ts b/packages/svelte-query/src/createQueries.svelte.ts index 96ea1a9443..e1466f0c3c 100644 --- a/packages/svelte-query/src/createQueries.svelte.ts +++ b/packages/svelte-query/src/createQueries.svelte.ts @@ -187,6 +187,8 @@ export type QueriesResults< : { [K in keyof T]: GetCreateQueryResult } /** + * 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 diff --git a/packages/svelte-query/src/createQuery.ts b/packages/svelte-query/src/createQuery.ts index 34df16c533..6a16e24edd 100644 --- a/packages/svelte-query/src/createQuery.ts +++ b/packages/svelte-query/src/createQuery.ts @@ -13,6 +13,9 @@ import type { } from './queryOptions.js' /** + * 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. @@ -84,6 +87,9 @@ export function createQuery< ): CreateQueryResult /** + * 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. + * * 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`. diff --git a/packages/svelte-query/src/useIsFetching.svelte.ts b/packages/svelte-query/src/useIsFetching.svelte.ts index 0fedb8bba3..dcb3b26d35 100644 --- a/packages/svelte-query/src/useIsFetching.svelte.ts +++ b/packages/svelte-query/src/useIsFetching.svelte.ts @@ -3,6 +3,9 @@ import { useQueryClient } from './useQueryClient.js' 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 diff --git a/packages/svelte-query/src/useIsRestoring.ts b/packages/svelte-query/src/useIsRestoring.ts index 99dd4ddacb..dc01ddaeb6 100644 --- a/packages/svelte-query/src/useIsRestoring.ts +++ b/packages/svelte-query/src/useIsRestoring.ts @@ -1,6 +1,26 @@ import { getIsRestoringContext } from './context.js' 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 + * ```svelte + * + * + * {#if isRestoring.current} + *
Restoring cached data...
+ * {/if} + * ``` + */ export function useIsRestoring(): Box { return getIsRestoringContext() } diff --git a/packages/svelte-query/src/useQueryClient.ts b/packages/svelte-query/src/useQueryClient.ts index a179058578..d547741e36 100644 --- a/packages/svelte-query/src/useQueryClient.ts +++ b/packages/svelte-query/src/useQueryClient.ts @@ -1,6 +1,26 @@ import { getQueryClientContext } from './context.js' 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. + * @example + * ```svelte + * + * ``` + */ export function useQueryClient(queryClient?: QueryClient): QueryClient { if (queryClient) return queryClient return getQueryClientContext()