feat(svelte-query): Improve svelte runes API (#8852)

* feat: Draft proposal

* chore: Improve reactive containers

* ci: apply automated fixes

* oops

* fix: Update API, add a bunch of tests

* merge main

* fix: use const

* more tests

* feat: More tests, back to thunks, fixed svelte-query-persist-client

* feat: More tests and examples!

* lockfile

* fixes

* Fix current CI errors

* More small fixes/tweaks

* Remove test.only

* ci: apply automated fixes

* Fix pnpm-lock, fix import order

* update main docs

* feat: More tests

* ci: apply automated fixes

* add back old tests

* Cleanup

* Fix persist client

* Fix useMutationState

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: Lachlan Collins <[email protected]>

Author: 3 people

docs/config.json

@@ -127,10 +127,6 @@
             {
               "label": "SSR & SvelteKit",
               "to": "framework/svelte/ssr"
-            },
-            {
-              "label": "Reactivity",
-              "to": "framework/svelte/reactivity"
             }
           ]
         },

docs/framework/svelte/devtools.md

@@ -55,7 +55,7 @@ Place the following code as high in your Svelte app as you can. The closer it is
 
 ### Options
 
-- `initialIsOpen: Boolean`
+- `initialIsOpen: boolean`
   - Set this `true` if you want the dev tools to default to being open
 - `buttonPosition?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "relative"`
   - Defaults to `bottom-right`

docs/framework/svelte/installation.md

@@ -5,8 +5,6 @@ title: Installation
 
 You can install Svelte Query via [NPM](https://npmjs.com).
 
-> v5 is currently available as a release-candidate. We don't anticipate any major API changes from here on out. We encourage you to try it out and report any issues you find.
-
 ### NPM
 
 ```bash

docs/framework/svelte/overview.md

@@ -28,19 +28,19 @@ Then call any function (e.g. createQuery) from any component:
 <script lang="ts">
   import { createQuery } from '@tanstack/svelte-query'
 
-  const query = createQuery({
+  const query = createQuery(() => ({
     queryKey: ['todos'],
     queryFn: () => fetchTodos(),
-  })
+  }))
 </script>
 
 <div>
-  {#if $query.isLoading}
+  {#if query.isLoading}
     <p>Loading...</p>
-  {:else if $query.isError}
-    <p>Error: {$query.error.message}</p>
-  {:else if $query.isSuccess}
-    {#each $query.data as todo}
+  {:else if query.isError}
+    <p>Error: {query.error.message}</p>
+  {:else if query.isSuccess}
+    {#each query.data as todo}
       <p>{todo.title}</p>
     {/each}
   {/if}
@@ -62,6 +62,8 @@ Svelte Query offers useful functions and components that will make managing serv
 - `useQueryClient`
 - `useIsFetching`
 - `useIsMutating`
+- `useMutationState`
+- `useIsRestoring`
 - `useHydrate`
 - `<QueryClientProvider>`
 - `<HydrationBoundary>`
@@ -70,5 +72,4 @@ Svelte Query offers useful functions and components that will make managing serv
 
 Svelte Query offers an API similar to React Query, but there are some key differences to be mindful of.
 
-- Many of the functions in Svelte Query return a Svelte store. To access values on these stores reactively, you need to prefix the store with a `$`. You can learn more about Svelte stores [here](https://learn.svelte.dev/tutorial/writable-stores).
-- If your query or mutation depends on variables, you must use a store for the options. You can read more about this [here](../reactivity).
+- The arguments to the `create*` functions must be wrapped in a function to preserve reactivity.

docs/framework/svelte/reactivity.md

@@ -58,11 +58,11 @@ export async function load() {
 
   export let data: PageData
 
-  const query = createQuery({
+  const query = createQuery(() => ({
     queryKey: ['posts'],
     queryFn: getPosts,
     initialData: data.posts,
-  })
+  }))
 </script>
 ```
 
@@ -136,10 +136,10 @@ export async function load({ parent, fetch }) {
   import { createQuery } from '@tanstack/svelte-query'
 
   // This data is cached by prefetchQuery in +page.ts so no fetch actually happens here
-  const query = createQuery({
+  const query = createQuery(() => ({
     queryKey: ['posts'],
     queryFn: async () => (await fetch('/api/posts')).json(),
-  })
+  }))
 </script>
 ```
 

docs/framework/svelte/ssr.md

@@ -10,7 +10,7 @@
 
   const client = useQueryClient()
 
-  const endpoint = 'http://localhost:5173/api/data'
+  const endpoint = '/api/data'
 
   const todos = createQuery<{ items: string[] }>(() => ({
     queryKey: ['refetch'],
@@ -21,7 +21,9 @@
 
   const addMutation = createMutation(() => ({
     mutationFn: (value: string) =>
-      fetch(`${endpoint}?add=${value}`).then((r) => r.json()),
+      fetch(`${endpoint}?add=${encodeURIComponent(value)}`).then((r) =>
+        r.json(),
+      ),
     onSuccess: () => client.invalidateQueries({ queryKey: ['refetch'] }),
   }))
 
@@ -31,7 +33,7 @@
   }))
 </script>
 
-<h1>Auto Refetch with stale-time set to 1s</h1>
+<h1>Auto Refetch with stale-time set to {(intervalMs / 1000).toFixed(2)}s</h1>
 
 <p>
   This example is best experienced on your own machine, where you can open
@@ -86,14 +88,22 @@
     <button onclick={() => clearMutation.mutate(undefined)}> Clear All </button>
   </div>
 {/if}
-{#if todos.isFetching}
-  <div style="color:darkgreen; font-weight:700">
-    'Background Updating...' : ' '
-  </div>
-{/if}
+
+<pre
+  class={['updating-text', todos.isFetching && 'on']}
+  style="font-weight:700">Background Updating...</pre>
 
 <style>
   li {
     text-align: left;
   }
+
+  .updating-text {
+    color: transparent;
+    transition: all 0.3s ease;
+  }
+  .updating-text.on {
+    color: green;
+    transition: none;
+  }
 </style>

examples/svelte/auto-refetching/src/routes/+page.svelte

@@ -38,11 +38,9 @@
           </article>
         {/each}
       </ul>
-      {#if posts.isFetching}
-        <div style="color:darkgreen; font-weight:700">
-          Background Updating...
-        </div>
-      {/if}
+      <pre
+        class={['updating-text', posts.isFetching && 'on']}
+        style="font-weight:700">Background Updating...</pre>
     {/if}
   </div>
 </div>
@@ -53,8 +51,16 @@
   }
   a {
     display: block;
-    color: white;
     font-size: 1.5rem;
     margin-bottom: 1rem;
   }
+
+  .updating-text {
+    color: transparent;
+    transition: all 0.3s ease;
+  }
+  .updating-text.on {
+    color: green;
+    transition: none;
+  }
 </style>

examples/svelte/basic/src/lib/Posts.svelte

@@ -60,5 +60,6 @@
   .card {
     background-color: #111;
     margin-bottom: 1rem;
+    color: rgba(255, 255, 255, 0.87);
   }
 </style>

examples/svelte/load-more-infinite-scroll/src/lib/LoadMore.svelte

@@ -20,7 +20,7 @@
 
   const client = useQueryClient()
 
-  const endpoint = 'http://localhost:5173/api/data'
+  const endpoint = '/api/data'
 
   const fetchTodos = async (): Promise<Todos> =>
     await fetch(endpoint).then((r) => r.json())

examples/svelte/optimistic-updates/src/routes/+page.svelte

@@ -6,7 +6,7 @@ type Todo = {
   text: string
 }
 
-const items: Todo[] = []
+const items: Array<Todo> = []
 
 /** @type {import('./$types').RequestHandler} */
 export const GET: RequestHandler = async (req) => {

examples/svelte/optimistic-updates/src/routes/api/data/+server.ts

@@ -14,7 +14,6 @@
   let name = $state('')
 
   const postTodo = async ({ name, notes }: Omit<Todo, 'id'>) => {
-    console.info('postTodo', { name, notes })
     return new Promise((resolve, reject) => {
       setTimeout(
         () => {
@@ -31,7 +30,7 @@
           }
           const todo = { name, notes, id: id.value }
           id.value = id.value + 1
-          list.value = [...list.value, todo]
+          list.value.push(todo)
           resolve(todo)
         },
         queryTimeMin.value +

examples/svelte/playground/src/routes/AddTodo.svelte

@@ -26,7 +26,7 @@
 
   <button
     onclick={() => {
-      views.value = [...views.value, '']
+      views.value.push('')
     }}
   >
     Add Filter List

examples/svelte/playground/src/routes/App.svelte

@@ -38,11 +38,9 @@
           </article>
         {/each}
       </ul>
-      {#if posts.isFetching}
-        <div style="color:darkgreen; font-weight:700">
-          Background Updating...
-        </div>
-      {/if}
+      <pre
+        class={['updating-text', posts.isFetching && 'on']}
+        style="font-weight:700">Background Updating...</pre>
     {/if}
   </div>
 </div>
@@ -53,8 +51,15 @@
   }
   a {
     display: block;
-    color: white;
     font-size: 1.5rem;
     margin-bottom: 1rem;
   }
+  .updating-text {
+    color: transparent;
+    transition: all 0.3s ease;
+  }
+  .updating-text.on {
+    color: green;
+    transition: none;
+  }
 </style>

examples/svelte/ssr/src/lib/Posts.svelte

@@ -1,6 +1,6 @@
-import { browser } from '$app/environment'
 import { QueryClient } from '@tanstack/svelte-query'
 import type { LayoutLoad } from './$types'
+import { browser } from '$app/environment'
 
 export const load: LayoutLoad = () => {
   const queryClient = new QueryClient({

examples/svelte/ssr/src/routes/+layout.ts

@@ -1,5 +1,5 @@
-import { api } from '$lib/api'
 import type { PageLoad } from './$types'
+import { api } from '$lib/api'
 
 export const load: PageLoad = async ({ parent, fetch }) => {
   const { queryClient } = await parent()

examples/svelte/ssr/src/routes/+page.ts

@@ -1,5 +1,5 @@
-import { api } from '$lib/api'
 import type { PageLoad } from './$types'
+import { api } from '$lib/api'
 
 export const load: PageLoad = async ({ parent, fetch, params }) => {
   const { queryClient } = await parent()

examples/svelte/ssr/src/routes/[postId]/+page.ts

@@ -2,8 +2,7 @@
   <h2 class="text-4xl">React Query Demo</h2>
   <p>Using the Star Wars API</p>
   <p>
-    (Built by <a href="https://twitter.com/Brent_m_Clark">@Brent_m_Clark</a>
-    )
+    (Built by <a href="https://twitter.com/Brent_m_Clark">@Brent_m_Clark</a>)
   </p>
   <section>
     <h5 class="text-2xl">Why React Query?</h5>

examples/svelte/star-wars/src/routes/+page.svelte

@@ -2,18 +2,17 @@
   import { createQuery } from '@tanstack/svelte-query'
   import Homeworld from './Homeworld.svelte'
   import Film from './Film.svelte'
-
-  let { data } = $props()
+  import { page } from '$app/state'
 
   const getCharacter = async () => {
     const res = await fetch(
-      `https://swapi.dev/api/people/${data.params.characterId}/`,
+      `https://swapi.dev/api/people/${page.params.characterId}/`,
     )
     return await res.json()
   }
 
   const query = createQuery(() => ({
-    queryKey: ['character', data.params.characterId],
+    queryKey: ['character', page.params.characterId],
     queryFn: getCharacter,
   }))
 </script>