Svelte Query

https://sveltequery.vercel.app/
Admin
Svelte Query provides performant and powerful data synchronization for Svelte applications, enabling...
Tokens:52,907
Snippets:402
Trust Score:7.8
Update:10 months ago
Show doc for...
Tokens:
Raw
### Svelte Query Setup with QueryClientProvider

Source: https://sveltequery.vercel.app/quick-start

Sets up the Svelte Query client and provides it to the application using QueryClientProvider. This is essential for enabling Svelte Query's features throughout the component tree. It requires the '@sveltestack/svelte-query' package.

```svelte
<script>
  //App.svelte
  import { QueryClient, QueryClientProvider } from '@sveltestack/svelte-query'
  import Todos from 'Todos.svelte'

  // Create a client
  const queryClient = new QueryClient()

</script>

<QueryClientProvider client={queryClient}>
  <Todos />
</QueryClientProvider>
```

--------------------------------

### Install Svelte Query with NPM or Yarn

Source: https://sveltequery.vercel.app/installation

This snippet shows how to add the Svelte Query library to your project using either NPM or Yarn package managers. Ensure you have Node.js and a package manager installed before running these commands.

```shell
npm i @sveltestack/svelte-query
# or
yarn add @sveltestack/svelte-query
```

--------------------------------

### Initialize Svelte App with SvelteQuery (JavaScript)

Source: https://sveltequery.vercel.app/docs/examples/simple

This code snippet demonstrates the entry point for a Svelte application. It imports the main App component and initializes it, passing initial props. This is a standard setup for Svelte applications.

```javascript
import App from './App.svelte';

const app = new App({
	target: document.body,
	props: {
		name: 'world'
	}
});

export default app;
```

--------------------------------

### Svelte Todos Component with useQuery and useMutation

Source: https://sveltequery.vercel.app/quick-start

Demonstrates fetching and mutating data using Svelte Query hooks within a Svelte component. It utilizes `useQuery` to fetch a list of todos and `useMutation` to add a new todo, invalidating the 'todos' query upon successful mutation. This example requires a `my-api` module with `getTodos` and `postTodo` functions.

```svelte
<script>
  // Todos.svelte
  import { useQuery, useMutation, useQueryClient } from '@sveltestack/svelte-query'
  import { getTodos, postTodo } from '../my-api'
  // Access the client
  const queryClient = useQueryClient()

  // Queries
  const queryResult = useQuery('todos', getTodos)

  // Mutations
  const mutation = useMutation(postTodo, {
    onSuccess: () => {
      // Invalidate and refetch
      queryClient.invalidateQueries('todos')
    },
  })
</script>

<div>
  <ul>
    {#each $queryResult.data as todo}
      <li>{todo.title}</li>
    {/each}
  </ul>

  <button
    on:click={() => {
      $mutation.mutate({ id: Date.now(), title: 'Do Laundry' })
    }}>
    Add Todo
  </button>
</div>
```

--------------------------------

### Set up Svelte Query with QueryClientProvider

Source: https://sveltequery.vercel.app/overview

This snippet demonstrates the basic setup for Svelte Query in a Svelte application. It involves importing QueryClient and QueryClientProvider, creating a new QueryClient instance, and wrapping the application or a part of it with QueryClientProvider.

```svelte
<script>
  // App.svelte
  import { QueryClient, QueryClientProvider } from '@sveltestack/svelte-query'

  const queryClient = new QueryClient()
</script>

<QueryClientProvider client={queryClient}>
  <Example />
</QueryClientProvider>
```

--------------------------------

### Install broadcast-channel dependency

Source: https://sveltequery.vercel.app/plugins/broadcastQueryClient

This utility requires the 'broadcast-channel' dependency to be installed separately. Instructions are provided for npm, yarn, and pnpm.

```bash
npm install broadcast-channel

yarn add broadcast-channel

pnpm add broadcast-channel
```

--------------------------------

### Initialize Svelte App with SvelteQuery

Source: https://sveltequery.vercel.app/examples/simple

This JavaScript code initializes the main Svelte application component (App.svelte) and mounts it to the document body. It also passes initial props to the application. This is a standard entry point for many Svelte applications.

```javascript
import App from './App.svelte';

const app = new App({
  target: document.body,
  props: {
    name: 'world'
  }
});

export default app;
```

--------------------------------

### Manual Parallel Queries with SvelteQuery `useQuery`

Source: https://sveltequery.vercel.app/guides/parallel-queries

Demonstrates how to execute multiple independent queries in parallel by simply calling the `useQuery` hook multiple times. These queries run concurrently without any special setup. This approach is suitable when the number of queries is static.

```javascript
import { useQuery } from '@tanstack/svelte-query';

// Assume fetchUsers, fetchTeams, fetchProjects are defined elsewhere

// The following queries will execute in parallel
const usersQuery = useQuery('users', fetchUsers);
const teamsQuery = useQuery('teams', fetchTeams);
const projectsQuery = useQuery('projects', fetchProjects);
...
```

--------------------------------

### Fetch and Cache Infinite Query Data with fetchInfiniteQuery

Source: https://sveltequery.vercel.app/reference/QueryClient

Illustrates the usage of `queryClient.fetchInfiniteQuery` for fetching and caching data for infinite queries. Similar to `fetchQuery`, it handles data fetching and caching, including scenarios with multiple pages of data. The code example shows how to access the fetched pages.

```javascript
try {
  const data = await queryClient.fetchInfiniteQuery(queryKey, queryFn)
  console.log(data.pages)
} catch (error) {
  console.log(error)
}
```

--------------------------------

### Fetch and display data using useQuery hook in Svelte

Source: https://sveltequery.vercel.app/overview

This example shows how to use the `useQuery` hook from Svelte Query to fetch data from an API. It handles loading states, error states, and displays the fetched data. The `useQuery` hook takes a query key and a fetcher function as arguments.

```svelte
<script>
  // Example.svelte
  import { useQuery } from '@sveltestack/svelte-query'

  const queryResult = useQuery('repoData', () =>
    fetch('https://api.github.com/repos/SvelteStack/svelte-query').then(res =>
      res.json()
    )
  )
</script>

{#if $queryResult.isLoading}
  <span>Loading...</span>
{:else if $queryResult.error}
  <span>An error has occurred: {$queryResult.error.message}</span>
{:else}
  <div>
    <h1>{$queryResult.data.name}</h1>
    <p>{$queryResult.data.description}</p>
    <strong>👀 {$queryResult.data.subscribers_count}</strong>{' '}
    <strong>✨ {$queryResult.data.stargazers_count}</strong>{' '}
    <strong>🍴 {$queryResult.data.forks_count}</strong>
  </div>
{/if}
```

--------------------------------

### Basic Query Function Configurations in Svelte Query

Source: https://sveltequery.vercel.app/guides/query-functions

Demonstrates various ways to define a query function for `useQuery`. These functions must return a promise that either resolves with data or throws an error. The examples show direct function calls, arrow functions, and async/await syntax.

```javascript
1 useQuery(['todos', todoId], fetchTodoById)
2 useQuery(['todos', todoId], () => fetchTodoById(todoId))
3 useQuery(['todos', todoId], async () => {
4   const data = await fetchTodoById(todoId)
5   return data
6 })
```

--------------------------------

### Get Query Cache Instance with Svelte Query

Source: https://sveltequery.vercel.app/reference/QueryClient

The `getQueryCache` method provides access to the QueryCache instance associated with the QueryClient. This allows for direct interaction with the cache's state and methods. It takes no arguments and returns the QueryCache object.

```javascript
const queryCache = queryClient.getQueryCache()
```

--------------------------------

### Get Default Query Options by Key with Svelte Query

Source: https://sveltequery.vercel.app/reference/QueryClient

The `getQueryDefaults` method retrieves the default options specifically set for a given query key. This is helpful for understanding or overriding specific query configurations. It accepts a query key and returns the associated default options.

```javascript
const defaultOptions = queryClient.getQueryDefaults('posts')
```

--------------------------------

### Get Default Query Client Options in Svelte Query

Source: https://sveltequery.vercel.app/reference/QueryClient

The `getDefaultOptions` method retrieves the default options configured for the QueryClient, either during initialization or via `setDefaultOptions`. This is useful for inspecting current default settings. It takes no arguments and returns the default options object.

```javascript
const defaultOptions = queryClient.getDefaultOptions()
```

--------------------------------

### Dependent Queries with useQuery and enabled option in Svelte

Source: https://sveltequery.vercel.app/guides/dependent-queries

This example shows how to create dependent queries using SvelteQuery's `useQuery` hook. The second query, fetching user projects, is enabled only after the first query, fetching user data, has successfully returned a `userId`. This ensures serial execution.

```javascript
<script>
  // Get the user
  const queryUserResult = useQuery(['user', email], getUserByEmail)
  let userId
  $: userId = $queryUserResult.data?.id
  
  // Then get the user's projects
  const queryProjectsResult = useQuery(
    ['projects', userId],
    getProjectsByUser,
    {
      // The query will not execute until the userId exists
      enabled: !!userId,
    }
  )
  
  $: {
      queryProjectsResult.setOptions(
      ['projects', userId],
      getProjectsByUser,
      {
        enabled: !!userId,
      })
    }
  // $queryProjectsResult.isIdle will be `true` until `enabled` is true and the query begins to fetch.
  // It will then go to the `isLoading` stage and hopefully the `isSuccess` stage :)
</script>
```

--------------------------------

### Basic Paginated Query with Svelte Query

Source: https://sveltequery.vercel.app/guides/paginated-queries

A simple example of rendering paginated data using Svelte Query's query key to include page information. This basic implementation can lead to UI jumps between loading and success states for each new page.

```javascript
 <Query options={{queryKey: ['projects', page], queryFn: fetchProjects}} />
```

--------------------------------

### Clear the Entire QueryCache - JavaScript

Source: https://sveltequery.vercel.app/reference/QueryCache

Provides an example of how to use the `clear` method to remove all queries from the `QueryCache`, effectively resetting it. This operation starts the cache fresh.

```javascript
queryCache.clear()
```

--------------------------------

### Invalidate Queries with a Specific Prefix in Svelte

Source: https://sveltequery.vercel.app/guides/query-invalidation

Shows how to invalidate queries in a Svelte component that have a specific prefix in their query key using `useQueryClient` and `invalidateQueries`. This example invalidates all queries starting with 'todos', including those with specific variables like page number.

```javascript
1 import { useQuery, useQueryClient } from '@sveltestack/svelte-query'
2 
3 // Get QueryClient from the context
4 const queryClient = useQueryClient()
5 
6 queryClient.invalidateQueries('todos')
7 
8 // Both queries below will be invalidated
9 const todoListQuery = useQuery('todos', fetchTodoList)
10 const todoListQuery = useQuery(['todos', { page: 1 }], fetchTodoList)
```

--------------------------------

### Instantiate and Subscribe to InfiniteQueryObserver in JavaScript

Source: https://sveltequery.vercel.app/reference/InfiniteQueryObserver

Demonstrates how to create an InfiniteQueryObserver instance with query details and subscribe to its results. It requires a QueryClient instance and defines queryKey, queryFn, getNextPageParam, and getPreviousPageParam. The subscription callback receives the query result and an unsubscribe function.

```javascript
const observer = new InfiniteQueryObserver(queryClient, {
  queryKey: 'posts',
  queryFn: fetchPosts,
  getNextPageParam: (lastPage, allPages) => lastPage.nextCursor,
  getPreviousPageParam: (firstPage, allPages) => firstPage.prevCursor,
})

const unsubscribe = observer.subscribe(result => {
  console.log(result)
  unsubscribe()
})
```

--------------------------------

### Use useIsMutating Hook in SvelteQuery

Source: https://sveltequery.vercel.app/reference/useIsMutating

This snippet demonstrates how to use the useIsMutating hook from SvelteQuery to get the count of active mutations. It shows how to get the total count and how to filter by a specific query key prefix. This is useful for creating global loading indicators.

```javascript
import { useIsMutating } from '@sveltestack/svelte-query'

// How many mutations are fetching?
const isMutating = useIsMutating()

// How many mutations matching the posts prefix are fetching?
const isMutatingPosts = useIsMutating(['posts'])
```

--------------------------------

### Svelte: Connect QueryClient with QueryClientProvider

Source: https://sveltequery.vercel.app/reference/QueryClientProvider

Demonstrates how to use the QueryClientProvider component in Svelte to establish a connection and provide a QueryClient instance to your application. It requires importing QueryClient and QueryClientProvider from '@sveltestack/svelte-query'. The component wraps the application's content, making the QueryClient available throughout.

```html
<script>
import { QueryClient, QueryClientProvider } from '@sveltestack/svelte-query'

const queryClient = new QueryClient()

</script>

<QueryClientProvider client={queryClient}>...</QueryClientProvider>
```

--------------------------------

### Query Options

Source: https://sveltequery.vercel.app/reference/useQuery

This section details the various optional configurations available for SvelteQuery observations, including callbacks for query lifecycle events, data transformation, initial and placeholder data management, and fetching behavior.

```APIDOC
## Query Configuration Options

This API provides several options to configure the behavior and lifecycle of queries.

### `onSuccess`

*   **Type**: `(data: TData) => void`
*   **Optional**
*   **Description**: This function will execute any time the query successfully fetches new data.

### `onError`

*   **Type**: `(error: TError) => void`
*   **Optional**
*   **Description**: This function will execute if the query encounters an error and will be passed the error object.

### `onSettled`

*   **Type**: `(data?: TData, error?: TError) => void`
*   **Optional**
*   **Description**: This function will execute any time the query is either successfully fetched or errors, and will be passed either the data or error.

### `select`

*   **Type**: `(data: TData) => unknown`
*   **Optional**
*   **Description**: This option allows for transforming or selecting a specific part of the data returned by the query function.

### `initialData`

*   **Type**: `TData | () => TData`
*   **Optional**
*   **Description**: If set, this value will be used as the initial data for the query cache, provided the query has not been created or cached yet. If set to a function, it will be called once during query initialization and expected to return the initial data synchronously. `initialData` is considered stale by default unless `staleTime` is set and is persisted to the cache.

### `initialDataUpdatedAt`

*   **Type**: `number | (() => number | undefined)`
*   **Optional**
*   **Description**: If set, this value specifies the timestamp (in milliseconds) of when the `initialData` was last updated.

### `placeholderData`

*   **Type**: `TData | () => TData`
*   **Optional**
*   **Description**: If set, this value serves as placeholder data for the query observer while the query is loading and no `initialData` is available. `placeholderData` is not persisted to the cache.

### `keepPreviousData`

*   **Type**: `boolean`
*   **Optional**
*   **Default**: `false`
*   **Description**: If set to `true`, previous data will be retained when the query key changes and new data is being fetched.

### `structuralSharing`

*   **Type**: `boolean`
*   **Optional**
*   **Default**: `true`
*   **Description**: If set to `false`, structural sharing between query results will be disabled.
```

--------------------------------

### Get Cached Query Data with queryClient.getQueryData

Source: https://sveltequery.vercel.app/reference/QueryClient

Retrieves existing query data synchronously from the cache. Returns undefined if the query does not exist. Accepts QueryKey and QueryFilters as options.

```javascript
const data = queryClient.getQueryData(queryKey)
```

--------------------------------

### Instantiate and Subscribe to QueryObserver

Source: https://sveltequery.vercel.app/reference/QueryObserver

Demonstrates how to create a QueryObserver instance with a query client and key, subscribe to its results, log them, and then unsubscribe. This is useful for manual query management outside of Svelte components.

```javascript
const observer = new QueryObserver(queryClient, { queryKey: 'posts' })

const unsubscribe = observer.subscribe(result => {
  console.log(result)
  unsubscribe()
})
```

--------------------------------

### Post Todo Mutation - SvelteQuery

Source: https://sveltequery.vercel.app/guides/invalidations-from-mutations

Defines a mutation to post a todo item using SvelteQuery's `useMutation` hook. This snippet shows the basic setup for a mutation operation.

```javascript
const mutation = useMutation(postTodo)
```

--------------------------------

### Clear Mutation Cache - JavaScript

Source: https://sveltequery.vercel.app/reference/MutationCache

The `clear` method removes all mutations from the MutationCache, effectively resetting it to an empty state. This can be useful for starting a fresh state, particularly during testing or specific application lifecycle events.

```javascript
mutationCache.clear()
```

--------------------------------

### useInfiniteQuery Hook Usage (JavaScript)

Source: https://sveltequery.vercel.app/reference/useInfiniteQuery

Demonstrates the basic usage of the useInfiniteQuery hook to fetch paginated data. It includes setting up query options like getNextPageParam and getPreviousPageParam, and destructuring essential return values for managing infinite scrolling.

```javascript
const queryResult = useInfiniteQuery(queryKey, ({ pageParam = 1 }) => fetchPage(pageParam), {
  ...options,
  getNextPageParam: (lastPage, allPages) => lastPage.nextCursor,
  getPreviousPageParam: (firstPage, allPages) => firstPage.prevCursor
})

const { fetchNextPage, fetchPreviousPage, hasNextPage, hasPreviousPage, isFetchingNextPage, isFetchingPreviousPage, ...result } = $queryResult

```

--------------------------------

### Get Query State with queryClient.getQueryState

Source: https://sveltequery.vercel.app/reference/QueryClient

Retrieves the current state of an existing query synchronously. Returns undefined if the query does not exist. Accepts QueryKey and QueryFilters as options. The state object includes properties like `dataUpdatedAt`.

```javascript
const state = queryClient.getQueryState(queryKey)
console.log(state.dataUpdatedAt)
```

--------------------------------

### useQuery Hook Usage and Destructuring - JavaScript/TypeScript

Source: https://sveltequery.vercel.app/reference/useQuery

Demonstrates the basic usage of the useQuery hook in SvelteQuery, including destructuring its return value. It shows how to pass queryKey and queryFn, and outlines the various options available for configuring query behavior.

```javascript
const queryResult = useQuery(queryKey, queryFn, {
  cacheTime,
  enabled,
  initialData,
  initialDataUpdatedAt,
  isDataEqual,
  keepPreviousData,
  notifyOnChangeProps,
  notifyOnChangePropsExclusions,
  onError,
  onSettled,
  onSuccess,
  queryFnParamsFilter,
  queryKeyHashFn,
  refetchInterval,
  refetchIntervalInBackground,
  refetchOnMount,
  refetchOnReconnect,
  refetchOnWindowFocus,
  retry,
  retryDelay,
  staleTime,
  structuralSharing,
  useErrorBoundary,
});

const {
  data,
  dataUpdatedAt,
  error,
  errorUpdatedAt,
  failureCount,
  isError,
  isFetchedAfterMount,
  isFetching,
  isIdle,
  isLoading,
  isLoadingError,
  isPlaceholderData,
  isPreviousData,
  isRefetchError,
  isStale,
  isSuccess,
  refetch,
  remove,
  status,
} = queryResult;

// or using the object syntax
const result = useQuery({
  queryKey,
  queryFn,
  enabled,
});
```

--------------------------------

### Get Mutation Cache Instance with Svelte Query

Source: https://sveltequery.vercel.app/reference/QueryClient

The `getMutationCache` method returns the MutationCache instance connected to the QueryClient. This enables programmatic access to mutation cache operations and state. It takes no arguments and returns the MutationCache object.

```javascript
const mutationCache = queryClient.getMutationCache()
```

--------------------------------

### Svelte: Global Background Fetching Indicator

Source: https://sveltequery.vercel.app/guides/background-fetching-indicators

Shows how to use the `useIsFetching` hook from '@sveltestack/svelte-query' in Svelte to display a global indicator when any queries are fetching in the background. This is useful for showing a site-wide loading state.

```svelte
<script>
  import { useIsFetching } from '@sveltestack/svelte-query'

  const isFetching = useIsFetching()
</script>

{#if $isFetching}
  <div>Queries are fetching in the background...</div>
{/if}
```

--------------------------------

### Get Current Focus State with FocusManager

Source: https://sveltequery.vercel.app/reference/focusManager

Retrieves the current focus state managed by Svelte Query's FocusManager. This method returns a boolean value indicating whether the application is currently considered focused.

```javascript
const isFocused = focusManager.isFocused()
```

--------------------------------

### Prepulating Query Cache with `initialData` (JavaScript)

Source: https://sveltequery.vercel.app/guides/initial-query-data

Demonstrates how to use the `initialData` option within `useQuery` to prepopulate the cache. This skips the loading state but is persisted. It's recommended to use `placeholderData` for incomplete data. `initialData` is treated as fresh by default.

```javascript
const result = useQuery('todos', () => fetch('/todos'), {
  initialData: initialTodos
})
```

--------------------------------

### Svelte: Implement Load More UI with useInfiniteQuery

Source: https://sveltequery.vercel.app/guides/infinite-queries

This Svelte component demonstrates how to use `useInfiniteQuery` to fetch paginated data and implement a 'Load More' button. It handles loading, error states, and displays project names. The `getNextPageParam` option is configured to determine the cursor for the next page, and `fetchNextPage` is called to load more data when the button is clicked.

```javascript
<script>
  import { useInfiniteQuery } from '@sveltestack/svelte-query'

  const fetchProjects = async ({ pageParam = 0 }) => {
    const { data } = await axios.get(`/projects?cursor=${pageParam}`)
    return data
  }

  const queryResult = useInfiniteQuery('projects', fetchProjects, {
    getNextPageParam: lastGroup => lastGroup.nextId || undefined,
  })
</script>

{#if $queryResult.status === 'loading'}
  Loading...
{:else if $queryResult.status === 'error'}
  <span>Error: {$queryResult.error.message}</span>
{:else}
  <div>
    {#each $queryResult.data.pages as page}
      {#each page.data as project}
        <p>{project.name}</p>
      {/each}
    {/each}
  </div>
  <div>
    <button
      on:click={() => $queryResult.fetchNextPage()}
      disabled={!$queryResult.hasNextPage || $queryResult.isFetchingNextPage}>
      {#if $queryResult.isFetching}
        Loading more...
      {:else if $queryResult.hasNextPage}
        Load More
      {:else}Nothing more to load{/if}
    </button>
  </div>
{/if}
```

--------------------------------

### Observe Multiple Queries with QueriesObserver

Source: https://sveltequery.vercel.app/reference/QueriesObserver

Demonstrates how to instantiate and use QueriesObserver to track the status and data of multiple queries. It shows how to subscribe to the observer to receive updates and unsubscribe when no longer needed. This is useful for managing related data fetching operations.

```javascript
1 const observer = new QueriesObserver(queryClient, [
2   { queryKey: ['post', 1], queryFn: fetchPost },
3   { queryKey: ['post', 2], queryFn: fetchPost },
4 ])
5 
6 const unsubscribe = observer.subscribe(result => {
7   console.log(result)
8   unsubscribe()
9 })
```

--------------------------------

### SvelteQuery: Basic useQuery Hook

Source: https://sveltequery.vercel.app/guides/queries

Demonstrates the fundamental usage of the `useQuery` hook in Svelte. It requires a unique query key and a function that returns a promise to fetch data. This is the core method for subscribing to asynchronous data sources.

```javascript
import { useQuery } from '@sveltestack/svelte-query'

const info = useQuery('todos', fetchTodoList)
```

--------------------------------

### Get Default Mutation Options by Key with Svelte Query

Source: https://sveltequery.vercel.app/reference/QueryClient

The `getMutationDefaults` method retrieves the default options configured for a specific mutation key. This is useful for inspecting or managing default mutation behaviors. It takes a mutation key and returns the associated default options.

```javascript
const defaultOptions = queryClient.getMutationDefaults('addPost')
```

--------------------------------

### Initialize LocalStorage Persistor in SvelteQuery

Source: https://sveltequery.vercel.app/plugins/createLocalStoragePersistor

Demonstrates how to import and use `createLocalStoragePersistor` to persist the `QueryClient` cache to local storage. It includes setting up `QueryClient` with default options and then applying the persistor.

```javascript
import { persistQueryClient } from '@sveltestack/svelte-query'
import { createLocalStoragePersistor } from '@sveltestack/svelte-query'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      cacheTime: 1000 * 60 * 60 * 24, // 24 hours
    },
  },
})

const localStoragePersistor = createLocalStoragePersistor()

persistQueryClient({
  queryClient,
  persistor: localStoragePersistor,
})
```

--------------------------------

### Initialize and Find a Query in QueryCache - JavaScript

Source: https://sveltequery.vercel.app/reference/QueryCache

Demonstrates how to initialize a QueryCache and use the `find` method to retrieve a specific query by its key. This is useful for accessing all state and underlying details of a query.

```javascript
import { QueryCache } from '@sveltestack/svelte-query'

const queryCache = new QueryCache()
const query = queryCache.find('posts')
```

--------------------------------

### Prefetch Infinite Query Data with prefetchInfiniteQuery

Source: https://sveltequery.vercel.app/reference/QueryClient

Demonstrates the `queryClient.prefetchInfiniteQuery` method, which allows for prefetching and caching data for infinite queries. Like `prefetchQuery`, it operates asynchronously without returning data or throwing errors, optimizing performance by fetching data in advance.

```javascript
await queryClient.prefetchInfiniteQuery(queryKey, queryFn)
```

--------------------------------

### Get Current Online State with OnlineManager in JavaScript

Source: https://sveltequery.vercel.app/reference/onlineManager

This code snippet illustrates how to retrieve the current online status managed by Svelte Query using the `onlineManager.isOnline()` method in JavaScript. It returns a boolean value indicating whether the application is currently considered online.

```javascript
const isOnline = onlineManager.isOnline()
```

--------------------------------

### Configure Svelte Query Logger

Source: https://sveltequery.vercel.app/reference/setLogger

The setLogger function allows you to provide a custom logger object to Svelte Query. This object must implement `log`, `warn`, and `error` methods. Examples show integration with custom loggers, Sentry for error tracking, and Winston.

```javascript
import { setLogger } from '@sveltestack/svelte-query'
import { printLog, printWarn, printError } from 'custom-logger'

// Custom logger
setLogger({
  log: printLog,
  warn: printWarn,
  error: printError,
})

// Sentry logger
setLogger({
  log: message => {
    Sentry.captureMessage(message)
  },
  warn: message => {
    Sentry.captureMessage(message)
  },
  error: error => {
    Sentry.captureException(error)
  },
})

// Winston logger
setLogger(winston.createLogger())
```

--------------------------------

### InfiniteQueryObserver

Source: https://sveltequery.vercel.app/reference/InfiniteQueryObserver

The InfiniteQueryObserver class allows you to observe and manage infinite queries. It takes a query client and an options object, similar to useInfiniteQuery, and provides a subscribe method to listen for query result changes.

```APIDOC
## InfiniteQueryObserver

### Description

Used to observe and switch between infinite queries. It accepts the same options as `useInfiniteQuery`.

### Method

N/A (Class constructor)

### Endpoint

N/A (Class)

### Parameters

#### Constructor Parameters

- **queryClient** (QueryClient) - Required - An instance of the QueryClient.
- **options** (InfiniteQueryObserverOptions) - Required - Configuration options for the infinite query.

##### InfiniteQueryObserverOptions

- **queryKey** (QueryKey) - Required - The unique key for the query.
- **queryFn** (QueryFunction) - Required - The function that fetches the query data.
- **getNextPageParam** (function(lastPage, allPages): any) - Optional - Function to determine the parameter for fetching the next page.
- **getPreviousPageParam** (function(firstPage, allPages): any) - Optional - Function to determine the parameter for fetching the previous page.

### Request Example

```javascript
const queryClient = new QueryClient();
const observer = new InfiniteQueryObserver(queryClient, {
  queryKey: 'posts',
  queryFn: fetchPosts,
  getNextPageParam: (lastPage, allPages) => lastPage.nextCursor,
  getPreviousPageParam: (firstPage, allPages) => firstPage.prevCursor,
});

const unsubscribe = observer.subscribe(result => {
  console.log(result);
  // unsubscribe(); // Call to unsubscribe when no longer needed
});
```

### Response

#### Success Response (via subscribe callback)

- **result** (InfiniteQueryObserverResult) - The current state of the infinite query.

##### InfiniteQueryObserverResult

- **data** (TData | undefined) - The fetched data.
- **error** (TError | undefined) - Any error encountered during fetching.
- **fetchStatus** ('fetching' | 'paused' | 'idle') - The status of the fetch operation.
- **isError** (boolean) - True if an error occurred.
- **isFetching** (boolean) - True if currently fetching.
- **isFetched** (boolean) - True if the query has been fetched at least once.
- **isSuccess** (boolean) - True if the query was successful.
- **isLoading** (boolean) - True if the query is currently loading (initial fetch).
- **isRefetching** (boolean) - True if the query is refetching in the background.
- **pageParams** (TPageParam[] | undefined) - An array of page parameters used.
- **hasNextPage** (boolean) - True if there is a next page to fetch.
- **hasPreviousPage** (boolean) - True if there is a previous page to fetch.
- **fetchNextPage** (function) - Function to fetch the next page.
- **fetchPreviousPage** (function) - Function to fetch the previous page.
- **refetch** (function) - Function to refetch the query.
- **remove** (function) - Function to remove the query from the cache.

#### Response Example (in subscribe callback)

```json
{
  "data": {
    "pages": [
      { "items": ["post1", "post2"], "nextCursor": 2 },
      { "items": ["post3", "post4"], "nextCursor": 4 }
    ],
    "pageParams": [null, 2, 4]
  },
  "error": null,
  "fetchStatus": "idle",
  "isError": false,
  "isFetching": false,
  "isFetched": true,
  "isSuccess": true,
  "isLoading": false,
  "isRefetching": false,
  "pageParams": [null, 2, 4],
  "hasNextPage": true,
  "hasPreviousPage": false
}
```
```

--------------------------------

### Manually Update Infinite Query Data in Svelte Query

Source: https://sveltequery.vercel.app/guides/infinite-queries

Demonstrates how to manually update the data for an infinite query using `queryClient.setQueryData`. This example specifically shows how to remove the first page of data from the query result. It modifies the `pages` and `pageParams` arrays.

```javascript
import { QueryClient } from '@sveltestack/svelte-query';

const queryClient = new QueryClient();

// Assuming 'projects' query data exists
// Example: queryClient.setQueryData('projects', { pages: [[...], [...]], pageParams: [p1, p2] });

queryClient.setQueryData('projects', (data) => ({
  pages: data.pages.slice(1),
  pageParams: data.pageParams.slice(1),
}));
```

--------------------------------

### Handling Errors in Svelte Query Functions

Source: https://sveltequery.vercel.app/guides/query-functions

Illustrates how to handle errors within a Svelte Query function. The query function must explicitly `throw` an error for Svelte Query to catch and persist it in the `error` state. This example shows conditional error throwing.

```javascript
1 const queryResult = useQuery(['todos', todoId], async () => {
2   if (somethingGoesWrong) {
3     throw new Error('Oh no!')
4   }
5 
6   return data
7 })
8 
9 ....
10 
11 $queryResult.error
```

--------------------------------

### Fetch and Cache Query Data with fetchQuery

Source: https://sveltequery.vercel.app/reference/QueryClient

Demonstrates how to use `queryClient.fetchQuery` to asynchronously fetch and cache query data. It handles both successful data retrieval and potential errors. The method intelligently uses cached data if available and not invalidated, otherwise it fetches fresh data. It also shows how to specify a `staleTime` option to control data freshness.

```javascript
try {
  const data = await queryClient.fetchQuery(queryKey, queryFn)
} catch (error) {
  console.log(error)
}
```

```javascript
try {
  const data = await queryClient.fetchQuery(queryKey, queryFn, {
    staleTime: 10000,
  })
} catch (error) {
  console.log(error)
}
```

--------------------------------

### useQuery Hook

Source: https://sveltequery.vercel.app/reference/useQuery

The `useQuery` hook fetches, caches, and synchronizes data in your Svelte application. It accepts a query key and a query function, along with numerous options to customize its behavior.

```APIDOC
## useQuery Hook

### Description

Fetches, caches, and synchronizes data. Accepts a query key and a query function, along with options to customize behavior.

### Method

`useQuery(queryKey, queryFn?, options?)
useQuery(options)
`

### Endpoint

N/A (This is a client-side hook)

### Parameters

#### Query Key
- **queryKey** (`string | unknown[]`) - **Required** - The unique key for the query, used for caching and identification. Changes to this key trigger refetches.

#### Query Function
- **queryFn** (`(context: QueryFunctionContext) => Promise<TData>`) - **Required (if no default defined)** - The function that fetches the data. It receives a `QueryFunctionContext` and must return a Promise that resolves with data or throws an error.

#### Options

- **enabled** (`boolean`) - **Optional** - If `false`, the query will not run automatically. Useful for dependent queries.
- **retry** (`boolean | number | (failureCount: number, error: TError) => boolean`) - **Optional** - Controls query retries on failure. Can be `false` (no retries), `true` (infinite retries), a number (max retries), or a function to define custom retry logic.
- **retryDelay** (`(retryAttempt: number) => number`) - **Optional** - A function that returns the delay in milliseconds before the next retry attempt.
- **staleTime** (`number | Infinity`) - **Optional** - Time in milliseconds after which the data is considered stale. `Infinity` means data is never stale.
- **cacheTime** (`number | Infinity`) - **Optional** - Time in milliseconds that inactive cache data remains in memory. `Infinity` disables garbage collection.
- **refetchInterval** (`false | number`) - **Optional** - If set to a number, the query will refetch at this frequency in milliseconds.
- **refetchIntervalInBackground** (`boolean`) - **Optional** - If `true`, refetching continues even when the tab/window is in the background.
- **refetchOnMount** (`boolean | "always"`) - **Optional** - Defaults to `true`. Determines if the query refetches on mount if data is stale. Can be `false` to disable, or `"always"` to always refetch.
- **refetchOnWindowFocus** (`boolean | "always"`) - **Optional** - Defaults to `true`. Determines if the query refetches on window focus if data is stale. Can be `false` to disable, or `"always"` to always refetch.
- **refetchOnReconnect** (`boolean | "always"`) - **Optional** - Defaults to `true`. Determines if the query refetches on reconnect if data is stale. Can be `false` to disable, or `"always"` to always refetch.
- **notifyOnChangeProps** (`string[]`) - **Optional** - An array of property names. The component will only re-render if one of these properties changes.
- **notifyOnChangePropsExclusions** (`string[]`) - **Optional** - An array of property names. The component will not re-render if any of these properties change.

### Request Example

```javascript
import { useQuery } from '@tanstack/svelte-query';

const queryResult = useQuery({
  queryKey: ['todos'],
  queryFn: async () => {
    const response = await fetch('/api/todos');
    return response.json();
  },
  enabled: true,
  staleTime: 5000,
});

const { data, isLoading, isError } = queryResult;
```

### Response

#### Query Result Object

- **data** (`TData | undefined`) - The fetched data.
- **dataUpdatedAt** (`number`) - Timestamp of when the data was last successfully fetched.
- **error** (`TError | null`) - The error object if the query failed.
- **errorUpdatedAt** (`number`) - Timestamp of when the error was last updated.
- **failureCount** (`number`) - The number of times the query has failed.
- **isError** (`boolean`) - True if the query has errored.
- **isFetchedAfterMount** (`boolean`) - True if the query has fetched after the component mounted.
- **isFetching** (`boolean`) - True if the query is currently fetching.
- **isIdle** (`boolean`) - True if the query is currently in an idle state (e.g., disabled).
- **isLoading** (`boolean`) - True if the query is currently loading for the first time.
- **isLoadingError** (`boolean`) - True if the query experienced an error during its initial load.
- **isPlaceholderData** (`boolean`) - True if the data is placeholder data (e.g., from a previous query).
- **isPreviousData** (`boolean`) - True if the data is from a previous query (while a new fetch is in progress).
- **isRefetchError** (`boolean`) - True if the query experienced an error during a refetch.
- **isStale** (`boolean`) - True if the data is considered stale.
- **isSuccess** (`boolean`) - True if the query has successfully fetched data.
- **refetch** (`() => Promise<void>`) - A function to manually refetch the query.
- **remove** (`() => void`) - A function to remove the query from the cache.
- **status** (`"loading" | "error" | "success" | "idle"`) - The current status of the query.

#### Response Example

```json
{
  "data": [
    {
      "id": 1,
      "title": "Learn SvelteQuery",
      "completed": false
    }
  ],
  "dataUpdatedAt": 1678886400000,
  "error": null,
  "errorUpdatedAt": 0,
  "failureCount": 0,
  "isError": false,
  "isFetchedAfterMount": true,
  "isFetching": false,
  "isIdle": false,
  "isLoading": false,
  "isLoadingError": false,
  "isPlaceholderData": false,
  "isPreviousData": false,
  "isRefetchError": false,
  "isStale": true,
  "isSuccess": true,
  "status": "success"
}
```
```

--------------------------------

### Svelte: Individual Query Background Fetching Indicator

Source: https://sveltequery.vercel.app/guides/background-fetching-indicators

Demonstrates how to use the `isFetching` state from `useQuery` in Svelte to show a 'Refreshing...' indicator when a query is refetching in the background, distinct from the initial 'Loading...' state. It relies on the '@sveltestack/svelte-query' library.

```svelte
<script>
  import { useQuery } from '@sveltestack/svelte-query';

  const queryResult = useQuery('todos', fetchTodos)
</script>

{#if $queryResult.status === 'loading'}
  <span>Loading...</span>
{:else if $queryResult.status === 'error'}
  <span>Error: {$queryResult.error.message}</span>
{:else}
  {#if $queryResult.isFetching}
    <div>Refreshing...</div>
  {/if}
  {#each $queryResult.data as todo}
    <Todo {todo} />
  {/each}
{/if}
```

--------------------------------

### Improved Paginated Queries with keepPreviousData in Svelte

Source: https://sveltequery.vercel.app/guides/paginated-queries

An enhanced Svelte component demonstrating the use of `keepPreviousData: true` for smoother pagination. This setup ensures that previous data remains visible while new data for the next page is fetched, and provides `isPreviousData` for conditional logic.

```svelte
<script>
  let page = 0

  const fetchProjects = (page = 0) => fetch('/api/projects?page=' + page)
</script>

<Query options={{ queryKey: ['projects', page], queryFn: () => fetchProjects(page), keepPreviousData: true }}>
  <div slot="query" let:queryResult>
    {#if queryResult.status === 'loading'}
      Loading...
    {:else if queryResult.status === 'error'}
      <span>Error: {queryResult.error.message}</span>
    {:else}
      <div>
        {#each queryResult.data.pages as page}
          {#each page.data as project}
            <p>{project.name}</p>
          {/each}
        {/each}
      </div>
    {/if}
    <span>Current Page: {page + 1}</span>
    <button
      on:click={() => {
        page = Math.max(old - 1, 0) // Assuming 'old' is defined elsewhere or a placeholder
      }}
      disabled={page === 0}>
      Previous Page
    </button>
    <button
      on:click={() => {
        if (!queryResult.isPreviousData && queryResult.data.hasMore) {
          page = page + 1
        }
      }}
      disabled={queryResult.isPreviousData || !queryResult.data.hasMore}>
      Next Page
    </button>
  </div>
</Query>
```

--------------------------------

### Using `mutateAsync` for Promise-based Mutations

Source: https://sveltequery.vercel.app/guides/mutations

The `mutateAsync` function returns a promise that resolves on success or throws on error, enabling composition of side effects. This is useful for chaining asynchronous operations or handling mutation outcomes in a promise-based manner, as shown in the Svelte template example using `{#await}`.

```html
<script>
  import { useMutation } from '@tanstack/svelte-query';

  const addTodo = async (variables) => {
    await new Promise(resolve => setTimeout(resolve, 1000)); // Simulate async work
    return { id: Math.random(), title: variables.title };
  };

  const mutation = useMutation(addTodo);
  const mutatePromise = mutation.mutateAsync({ title: 'Async Todo' });
</script>

{#await mutatePromise}
  <p>Waiting for the promise to resolve...</p>
{:then value}
  <p>Mutation done! Result: {JSON.stringify(value)}</p>
{:catch error}
  <p>Something went wrong: {error.message}</p>
{/await}
```

--------------------------------

### Prefetch Query Data with prefetchQuery

Source: https://sveltequery.vercel.app/reference/QueryClient

Shows how to use `queryClient.prefetchQuery` to proactively fetch and cache query data before it's needed. This method is asynchronous and does not return data or throw errors, making it suitable for background data preparation. It can also utilize default query functions defined in the client's configuration.

```javascript
await queryClient.prefetchQuery(queryKey, queryFn)
```

```javascript
await queryClient.prefetchQuery(queryKey)
```

--------------------------------

### Initial Data from Cache with `initialDataUpdatedAt` (JavaScript)

Source: https://sveltequery.vercel.app/guides/initial-query-data

Demonstrates using `initialDataUpdatedAt` to provide initial data from the cache. This ensures the query uses cached data if it's considered fresh, otherwise, it refetches. It relies on `queryClient.getQueryData` and `queryClient.getQueryState`.

```javascript
function Todo({ todoId }) {
  return useQuery(['todo', todoId], () => fetch('/todos'), {
    initialData: () =>
      queryClient.getQueryData('todos')?.find(d => d.id === todoId),
    initialDataUpdatedAt: () =>
      queryClient.getQueryState('todos')?.dataUpdatedAt,
  })
}
```

--------------------------------

### Initialize QueryClient with Default Options

Source: https://sveltequery.vercel.app/reference/QueryClient

Initializes a new QueryClient instance with custom default options for all queries. This includes setting a default staleTime to Infinity, ensuring data is never considered stale by default. The client can also prefetch data for a given query key.

```javascript
import { QueryClient } from '@sveltestack/svelte-query'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: Infinity,
    },
  },
})

await queryClient.prefetchQuery('posts', fetchPosts)
```

--------------------------------

### Invalidate Queries with Specific Variables

Source: https://sveltequery.vercel.app/guides/query-invalidation

Illustrates how to invalidate queries that match a specific query key, including its variables. This allows for precise invalidation, ensuring only the intended queries are marked as stale and refetched. The example shows invalidating queries with `['todos', { type: 'done' }]` but not a general 'todos' query.

```javascript
1 queryClient.invalidateQueries(['todos', { type: 'done' }])
2 
3 // The query below will be invalidated
4 const todoListQuery = useQuery(['todos', { type: 'done' }], fetchTodoList)
5 
6 // However, the following query below will NOT be invalidated
7 const todoListQuery = useQuery('todos', fetchTodoList)
```

--------------------------------

### Fetch Multiple Queries with useQueries in JavaScript

Source: https://sveltequery.vercel.app/reference/useQueries

The useQueries hook fetches a variable number of queries. It accepts an array of query option objects, each defined like a useQuery option. It returns an array containing the results of all provided queries.

```javascript
const results = useQueries([
  { queryKey: ['post', 1], queryFn: fetchPost },
  { queryKey: ['post', 2], queryFn: fetchPost },
])
```

--------------------------------

### Using Fetch API with Error Handling in Svelte Query

Source: https://sveltequery.vercel.app/guides/query-functions

Shows how to use the `fetch` API within a Svelte Query function, addressing its default behavior of not throwing errors on unsuccessful HTTP responses. This example manually checks the `ok` status and throws an error if the network response is not successful.

```javascript
1 useQuery(['todos', todoId], async () => {
2   const { ok, json } = await fetch('/todos/' + todoId)
3   if (!ok) {
4     throw new Error('Network response was not ok')
5   }
6   return json()
7 })
```
Tokens:
Raw