Kvale

Smart data layer for SvelteKit — fetch, cache, done.

A statement from Kal, founder of Complexia

Software built for the age of AI must be transparent, auditable, and correct by design. As artificial intelligence becomes a native tool in development workflows — reviewing code, generating logic, suggesting patterns — the libraries and data layers it interacts with carry new responsibility. Ambiguous state, hidden side effects, and silent failures are not just developer experience problems: they become safety problems when AI reasoning depends on them. At Complexia, we believe the right response is to build tools that are small, honest, and fully traceable. Kvale is one expression of that commitment.

— Kal (@qkal)

Kvale is a zero-dependency, runes-native data fetching and caching library built from the ground up for SvelteKit and Svelte 5. It gives you stale-while-revalidate caching, background refetching, polling, persistence, and dependent queries — with an API so minimal it disappears into your code.

No providers. No wrappers. No boilerplate. Just createCache() and cache.query().

<script lang="ts">
  import { cache } from '$lib/cache';

  const todos = cache.query<Todo[]>({
    key: 'todos',
    fn: () => fetch('/api/todos').then(r => r.json()),
  });
</script>

{#if todos.status === 'loading'}
  <p>Loading...</p>
{:else if todos.status === 'error'}
  <p>Error: {todos.error.message}</p>
{:else}
  {#each todos.data as todo}
    <p>{todo.title}</p>
  {/each}
{/if}

Why Kvale?

• Born in Svelte 5 — uses $state and $effect natively. No legacy store adapters, no writable(), no React-isms.
• No QueryClientProvider — call createCache() once and use it anywhere. Your app stays yours.
• Works everywhere — .svelte, .svelte.ts, and plain .ts files. The pure TypeScript core has zero framework dependencies and runs in any JS environment.
• Stale-while-revalidate — cached data is shown instantly while fresh data loads silently in the background. Users never see a blank state.
• Reactive dependent queries — enabled: () => !!user.data?.id just works. Svelte tracks it automatically.
• Impossible states eliminated — a single status discriminant ('idle' | 'loading' | 'refreshing' | 'success' | 'error') replaces the footgun of boolean flags.
• Zero dependencies — ~3kb minified. Nothing else pulled in.

Installation

Choose your package manager:

# Bun (recommended)
bun add kvale

# npm
npm install kvale

# pnpm
pnpm add kvale

Peer dependency: Svelte 5.25.0 or later.

Quick Start

Step 1: Create your cache instance

Set up a shared cache in $lib/cache.ts — call this once per app:

// src/lib/cache.ts
import { createCache } from 'kvale';

export const cache = createCache({
  staleTime: 30_000,           // data stays fresh for 30s (default)
  retry: 1,                    // retry once on failure (default)
  refetchOnWindowFocus: true,  // refetch stale queries on tab focus (default)
});

Step 2: Query data in any component

Import the cache and call cache.query() in the <script> block:

<!-- src/routes/+page.svelte -->
<script lang="ts">
  import { cache } from '$lib/cache';

  interface Todo {
    id: number;
    title: string;
    completed: boolean;
  }

  const todos = cache.query<Todo[]>({
    key: 'todos',
    fn: () => fetch('/api/todos').then(r => r.json()),
  });
</script>

{#if todos.status === 'loading'}
  <p>Loading...</p>
{:else if todos.status === 'error'}
  <p>Something went wrong: {todos.error.message}</p>
{:else if todos.status === 'success'}
  <ul>
    {#each todos.data as todo}
      <li class:done={todo.completed}>{todo.title}</li>
    {/each}
  </ul>
{/if}

{#if todos.status === 'refreshing'}
  <small>Refreshing in background…</small>
{/if}

Step 3: Do not destructure the result

QueryResult is a reactive object. Destructuring breaks reactivity — always access properties directly:

// ✅ correct
todos.status
todos.data

// ❌ breaks reactivity
const { status, data } = todos;

API Reference

createCache(config?)

Creates a shared cache instance. Call once per app, typically in $lib/cache.ts.

| Option | Type | Default | Description | |---|---|---|---| | staleTime | number | 30_000 | Milliseconds until cached data is considered stale | | retry | number | 1 | Number of retries on fetch failure | | refetchOnWindowFocus | boolean | true | Refetch stale queries when the tab regains focus | | persist | Storage | undefined | Persist cache to storage (e.g. localStorage) |

cache.query<T>(config)

Creates a reactive query bound to the cache. Returns a QueryResult<T>.

| Option | Type | Description | |---|---|---| | key | string \| unknown[] | Cache key. Strings auto-wrap to [string]. | | fn | () => Promise<T> | Async function that fetches the data | | staleTime | number? | Per-query override of global staleTime | | refetchInterval | number? | Poll interval in ms. Omit to disable polling. | | enabled | boolean \| (() => boolean)? | Set false or return false to skip the query |

QueryResult<T>

The reactive object returned by cache.query(). Access properties directly — do not destructure.

| Property | Type | Description | |---|---|---| | status | 'idle' \| 'loading' \| 'refreshing' \| 'success' \| 'error' | Current fetch state | | data | T \| undefined | The fetched data, or undefined before first success | | error | Error \| null | The last error, or null | | isStale | boolean | true when data is older than staleTime | | refetch() | () => Promise<void> | Manually trigger a refetch |

Status reference:

| Status | Meaning | |---|---| | idle | Query is disabled (enabled: false) | | loading | First fetch in progress, no cached data available | | refreshing | Background refetch — stale data is still visible | | success | Data loaded successfully | | error | Fetch failed after all retries |

Examples

Dependent Query

Run a query only when another query's data is ready.

<script lang="ts">
  import { cache } from '$lib/cache';

  const user = cache.query({
    key: 'user',
    fn: () => fetch('/api/me').then(r => r.json()),
  });

  const posts = cache.query({
    key: ['posts', user.data?.id],
    fn: () => fetch(`/api/posts?user=${user.data!.id}`).then(r => r.json()),
    enabled: () => !!user.data?.id,
  });
</script>

Polling

Keep data fresh by refetching on an interval.

<script lang="ts">
  import { cache } from '$lib/cache';

  const prices = cache.query({
    key: 'crypto-prices',
    fn: () => fetch('/api/prices').then(r => r.json()),
    refetchInterval: 5_000, // refetch every 5 seconds
  });
</script>

localStorage Persistence

Hydrate the cache from localStorage on page load so users never see a blank state on return visits.

// src/lib/cache.ts
import { createCache } from 'kvale';

export const cache = createCache({
  persist: localStorage,
});

Reusable Query Function

Define queries once, use anywhere — in .svelte, .svelte.ts, or plain .ts files.

// src/lib/queries/todos.svelte.ts
import { cache } from '$lib/cache';

export function useTodos(status?: string) {
  return cache.query<Todo[]>({
    key: ['todos', { status }],
    fn: () => fetch(`/api/todos?status=${status ?? ''}`).then(r => r.json()),
  });
}

Manual Refetch

Expose a refresh button to let users pull fresh data on demand.

<script lang="ts">
  import { cache } from '$lib/cache';

  const todos = cache.query({ key: 'todos', fn: fetchTodos });
</script>

<button onclick={() => todos.refetch()}>
  {todos.status === 'refreshing' ? 'Refreshing…' : 'Refresh'}
</button>

Disabled Query

Use enabled to conditionally skip fetching — useful for search inputs, authenticated routes, or multi-step flows.

<script lang="ts">
  import { cache } from '$lib/cache';

  let searchTerm = $state('');

  const results = cache.query({
    key: ['search', searchTerm],
    fn: () => fetch(`/api/search?q=${searchTerm}`).then(r => r.json()),
    enabled: () => searchTerm.length > 2,
  });
</script>

<input bind:value={searchTerm} placeholder="Search…" />

Roadmap

• v1.1 — cache.mutate(), cache.invalidate(), request deduplication
• v1.2 — SSR hydration bridge (initialData from SvelteKit load()), cache.prefetch()
• v1.3 — Infinite queries, pagination helpers, garbage collection

Contributing

We welcome contributions of all kinds. See CONTRIBUTING.md to get started.

License

MIT © Kal, founder of Complexia