feat(svelte-query): Svelte Query Adapter for TanStack Query

.codesandbox/ci.json

@@ -1,6 +1,6 @@
 {
   "installCommand": "install:csb",
-  "sandboxes": ["/examples/react/basic-typescript", "/examples/solid/basic-typescript", "/examples/vue/basic"],
+  "sandboxes": ["/examples/react/basic-typescript", "/examples/solid/basic-typescript", "/examples/svelte/basic", "/examples/vue/basic"],
   "packages": ["packages/**"],
   "node": "16"
 }

.prettierignore

@@ -0,0 +1 @@
+/packages/svelte-query/.svelte-kit

babel.config.js

@@ -33,7 +33,7 @@ module.exports = {
   ].filter(Boolean),
   overrides: [
     {
-      exclude: ['./packages/solid-query/**', './packages/vue-query/**'],
+      exclude: ['./packages/solid-query/**', './packages/svelte-query/**', './packages/vue-query/**'],
       presets: ['@babel/react'],
     },
     {

docs/config.json

@@ -688,7 +688,7 @@
           "label": "Getting Started",
           "children": [
             {
-              "label": "Coming Soon",
+              "label": "Overview",
               "to": "svelte/overview"
             }
           ]

docs/svelte/overview.md

@@ -1,8 +1,69 @@
 ---
 id: overview
-title: Svelte Query (Coming Soon)
+title: Svelte Query
 ---
 
-> ⚠️ This module has not yet been developed. It requires an adapter similar to `react-query` to work. We estimate the amount of code to do this is low-to-moderate, but does require familiarity with the Svelte framework. If you would like to contribute this adapter, please open a PR!
+The `@tanstack/svelte-query` package offers a 1st-class API for using TanStack Query via Svelte.
 
-The `@tanstack/svelte-query` package offers a 1st-class API for using TanStack Query via Svelte. However, all of the primitives you receive from this API are core APIs that are shared across all of the TanStack Adapters including the Query Client, query results, query subscriptions, etc.
+## Example
+
+Include the QueryClientProvider near the root of your project:
+
+```svelte
+<script lang="ts">
+  import { QueryClientProvider, QueryClient } from '@tanstack/svelte-query'
+  import Simple from './lib/Example.svelte'
+
+  const queryClient = new QueryClient()
+</script>
+
+<QueryClientProvider client={queryClient}>
+  <Simple />
+</QueryClientProvider>
+```
+
+Then call any function (e.g. createQuery) from any component:
+
+```svelte
+<script lang="ts">
+  import { createQuery } from '@tanstack/svelte-query'
+
+  const query = createQuery({
+    queryKey: ['todos'],
+    queryFn: () => fetchTodos(),
+  })
+</script>
+
+<div>
+  {#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}
+        <p>{todo.title}</p>
+      {/each}
+  {/if}
+</div>
+```
+
+## Available Functions
+
+Svelte Query offers useful functions and components that will make managing server state in Svelte apps easier.
+
+- `createQuery`
+- `createQueries`
+- `createInfiniteQuery`
+- `createMutation`
+- `useQueryClient`
+- `useIsFetching`
+- `useIsMutating`
+- `useHydrate`
+- `<QueryClientProvider>`
+- `<Hydrate>`
+
+## Important Differences between Svelte Query & React Query
+
+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://svelte.dev/tutorial/writable-stores).

examples/svelte/auto-refetching/.gitignore

@@ -0,0 +1,9 @@
+.DS_Store
+node_modules
+/build
+/.svelte-kit
+/package
+.env
+.env.*
+!.env.example
+!lib/

examples/svelte/auto-refetching/README.md

@@ -0,0 +1,38 @@
+# create-svelte
+
+Everything you need to build a Svelte project, powered by [`create-svelte`](https://github.com/sveltejs/kit/tree/master/packages/create-svelte).
+
+## Creating a project
+
+If you're seeing this, you've probably already done this step. Congrats!
+
+```bash
+# create a new project in the current directory
+npm create svelte@latest
+
+# create a new project in my-app
+npm create svelte@latest my-app
+```
+
+## Developing
+
+Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:
+
+```bash
+npm run dev
+
+# or start the server and open the app in a new browser tab
+npm run dev -- --open
+```
+
+## Building
+
+To create a production version of your app:
+
+```bash
+npm run build
+```
+
+You can preview the production build with `npm run preview`.
+
+> To deploy your app, you may need to install an [adapter](https://kit.svelte.dev/docs/adapters) for your target environment.

examples/svelte/auto-refetching/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@tanstack/query-example-svelte-auto-refetching",
+  "version": "0.0.1",
+  "private": true,
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build",
+    "preview": "vite preview",
+    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json"
+  },
+  "dependencies": {
+    "@tanstack/svelte-query": "^4.12.0"
+  },
+  "devDependencies": {
+    "@sveltejs/adapter-auto": "^1.0.0",
+    "@sveltejs/kit": "^1.0.0",
+    "svelte": "^3.54.0",
+    "svelte-check": "^2.9.2",
+    "svelte-preprocess": "^4.10.7",
+    "tslib": "^2.4.1",
+    "typescript": "^4.7.4",
+    "vite": "^4.0.0"
+  },
+  "type": "module"
+}

examples/svelte/auto-refetching/src/app.css

@@ -0,0 +1,81 @@
+:root {
+  font-family: Inter, Avenir, Helvetica, Arial, sans-serif;
+  font-size: 16px;
+  line-height: 24px;
+  font-weight: 400;
+
+  color-scheme: light dark;
+  color: rgba(255, 255, 255, 0.87);
+  background-color: #242424;
+
+  font-synthesis: none;
+  text-rendering: optimizeLegibility;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  -webkit-text-size-adjust: 100%;
+}
+
+a {
+  font-weight: 500;
+  color: #646cff;
+  text-decoration: inherit;
+}
+a:hover {
+  color: #535bf2;
+}
+
+body {
+  margin: 0;
+  display: flex;
+  place-items: center;
+  min-width: 320px;
+  min-height: 100vh;
+}
+
+h1 {
+  font-size: 3.2em;
+  line-height: 1.1;
+}
+
+.card {
+  padding: 2em;
+}
+
+main {
+  max-width: 1280px;
+  margin: 0 auto;
+  padding: 2rem;
+  text-align: center;
+}
+
+button {
+  border-radius: 8px;
+  border: 1px solid transparent;
+  padding: 0.6em 1.2em;
+  font-size: 1em;
+  font-weight: 500;
+  font-family: inherit;
+  background-color: #1a1a1a;
+  cursor: pointer;
+  transition: border-color 0.25s;
+}
+button:hover {
+  border-color: #646cff;
+}
+button:focus,
+button:focus-visible {
+  outline: 4px auto -webkit-focus-ring-color;
+}
+
+@media (prefers-color-scheme: light) {
+  :root {
+    color: #213547;
+    background-color: #ffffff;
+  }
+  a:hover {
+    color: #747bff;
+  }
+  button {
+    background-color: #f9f9f9;
+  }
+}

examples/svelte/auto-refetching/src/app.d.ts

@@ -0,0 +1,9 @@
+// See https://kit.svelte.dev/docs/types#app
+// for information about these interfaces
+// and what to do when importing types
+declare namespace App {
+  // interface Locals {}
+  // interface PageData {}
+  // interface Error {}
+  // interface Platform {}
+}

examples/svelte/auto-refetching/src/app.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <link rel="shortcut icon" type="image/svg+xml" href="%sveltekit.assets%/emblem-light.svg" />
+    <meta name="viewport" content="width=device-width" />
+    %sveltekit.head%
+  </head>
+  <body>
+    <div>%sveltekit.body%</div>
+  </body>
+</html>

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

@@ -0,0 +1,12 @@
+<script lang="ts">
+  import '../app.css'
+  import { QueryClientProvider, QueryClient } from '@tanstack/svelte-query'
+
+  const queryClient = new QueryClient()
+</script>
+
+<QueryClientProvider client={queryClient}>
+  <main>
+    <slot />
+  </main>
+</QueryClientProvider>

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

@@ -0,0 +1,101 @@
+<script lang="ts">
+  import {
+    useQueryClient,
+    createQuery,
+    createMutation,
+  } from '@tanstack/svelte-query'
+
+  let intervalMs = 1000
+  let value: string
+
+  const client = useQueryClient()
+
+  const endpoint = 'http://localhost:5173/api/data'
+
+  const todos = createQuery<{ items: string[] }, Error>({
+    queryKey: ['refetch'],
+    queryFn: async () => await fetch(endpoint).then((r) => r.json()),
+    // Refetch the data every second
+    refetchInterval: intervalMs,
+  })
+
+  const addMutation = createMutation(
+    (value: string) => fetch(`${endpoint}?add=${value}`).then((r) => r.json()),
+    { onSuccess: () => client.invalidateQueries(['refetch']) },
+  )
+  const clearMutation = createMutation(
+    () => fetch(`${endpoint}?clear=1`).then((r) => r.json()),
+    {
+      onSuccess: () => client.invalidateQueries(['refetch']),
+    },
+  )
+</script>
+
+<h1>Auto Refetch with stale-time set to 1s</h1>
+
+<p>
+  This example is best experienced on your own machine, where you can open
+  multiple tabs to the same localhost server and see your changes propagate
+  between the two.
+</p>
+
+<label>
+  Query Interval speed (ms):{' '}
+  <div class="flex">
+    <input bind:value={intervalMs} type="number" step="100" />{' '}
+
+    <span
+      style="display:inline-block; 
+          margin-left:.5rem;
+          width:.75rem;
+          height:.75rem; 
+          background: {$todos.isFetching ? 'green' : 'transparent'};
+          transition:: {!$todos.isFetching ? 'all .3s ease' : 'none'};
+          border-radius: 100%;
+          transform: 'scale(2)"
+    />
+  </div>
+</label>
+<h2>Todo List</h2>
+<form
+  on:submit={(e) => {
+    e.preventDefault()
+    e.stopPropagation()
+    $addMutation.mutate(value, {
+      onSuccess: () => (value = ''),
+    })
+  }}
+>
+  <input placeholder="enter something" bind:value />
+</form>
+
+{#if $todos.isLoading}
+  Loading...
+{/if}
+{#if $todos.error}
+  An error has occurred:
+  {$todos.error.message}
+{/if}
+{#if $todos.isSuccess}
+  <ul>
+    {#each $todos.data.items as item}
+      <li>{item}</li>
+    {/each}
+  </ul>
+  <div>
+    <button on:click={() => $clearMutation.mutate(undefined)}>
+      Clear All
+    </button>
+  </div>
+{/if}
+{#if $todos.isFetching}
+  <div style="color:darkgreen; font-weight:700">
+    'Background Updating...' : ' '
+  </div>
+{/if}
+
+<style>
+  li {
+    text-align: left;
+  }
+</style>