Svelte Lean Query

At a glance

Search, then pin a member. The panel lists what the server received and why: mount, params, mutation, invalidate.

<!-- src/routes/members/+page.svelte -->
<script lang="ts">
	import { createMutation, createQuery } from '@svelte-lean/query';
	import { listMembers, pinMember } from '$api/members';

	let filters = $state({ search: '' });
	const members = createQuery(listMembers, () => filters, {
		keepPrevious: true,
		poll: () => '30s'
	});
	const pin = createMutation(pinMember);
</script>

<input type="search" aria-label="Search members" bind:value={filters.search} />
{#if members.loading}<p>Loading members…</p>{/if}
{#if members.refreshing}<progress aria-label="Refreshing"></progress>{/if}

<ul>
	{#each members.data?.rows ?? [] as member (member.id)}
		<li>
			{member.name}
			<button
				disabled={pin.busy || !pin.allowed()}
				onclick={() => pin.run({ id: member.id, pinned: !member.pinned })}
			>
				{member.pinned ? 'Unpin' : 'Pin'}
			</button>
		</li>
	{/each}
</ul>

import { defineMutation, defineQuery, page, tag, type } from '@svelte-lean/query';
import type { Member, MemberFilters, MemberInput, Team } from './types';

// The tag and permission registries: a typo in a tag or a permission is a compile error.
declare module '@svelte-lean/query' {
	interface Tags {
		Member: number;
		Members: void;
		Teams: void;
	}
	interface Permissions {
		'members.view': true;
		'members.edit': true;
		'members.delete': true;
	}
}

export const listMembers = defineQuery({
	get: 'api/members',
	params: type<MemberFilters>(),
	result: page<Member>(),
	entity: 'Member', // every row carries tag('Member', row.id)
	tags: ['Members'],
	fresh: '15s',
	access: 'members.view'
});

export const pinMember = defineMutation({
	put: 'api/members/{id}/pin',
	body: type<{ pinned: boolean }>(),
	result: type<Member>(),
	invalidates: (member) => [tag('Member', member.id)],
	queue: (input) => `member:${input.id}` // one write per member at a time, in order
});

<!-- src/routes/+layout.svelte — one client for the application -->
<script lang="ts">
	import { createClient, setClient } from '@svelte-lean/query';
	import { http } from '@svelte-lean/query/http';
	import { can, session } from '$api/session.svelte';

	let { children } = $props();

	setClient(
		createClient({
			transport: http({
				base: '/',
				headers: () => ({ authorization: `Bearer ${session.token}` })
			}),
			scope: () => [session.workspace], // part of every cache key
			can // resolves the permission strings of `access` rules
		})
	);
</script>

{@render children()}

What happens without more code

• Typing changes the params; the previous rows stay on screen while the next ones load.
• A request whose answer nobody waits for any more is aborted.
• The list polls only while the tab is visible; a poll sets refreshing, never loading.
• Pinning refetches only the observed entries tagged Member:<id>, once, even when a poll lands at the same time.
• Without the members.view permission, nothing is sent.

Install

One package; every entry point below is a subpath of it. Its only peer dependency is svelte ^5.20.0. Then create the client: Client setup.

npm install @svelte-lean/query

pnpm add @svelte-lean/query

yarn add @svelte-lean/query

bun add @svelte-lean/query

Levels

A screen should need level 1 only. The guides and the reference follow the same order.

When a query runs

A query starts when its result is read on screen. Everything else narrows that.

Entry points

Each module is its own import; the root entry never re-exports one. A screen that reads and writes ships 15409 B gzip; a screen that only reads ships 11787 B gzip.

Consumer entries bundled with Vite in production mode (Rollup tree-shaking, esbuild minify, ESM, es2022, production condition, svelte external, .svelte.js compiled with compileModule). "query" = defineQuery + createQuery + client (first-load code; optional parts are their own "part:" rows, loaded on first use); "query+mutation" adds defineMutation, createMutation, patch; "query + every part (static)" adds `allParts` from `./parts` (every optional part in the first load, no lazy chunk). Vite's preload helper is the application's and not counted. Marginal rows subtract the row named in "over". gzip level 9 / brotli quality 11 (node:zlib). Budgets are gzip; "target" is the 04 §2 target. Budgets, targets and every other measurement: Performance.

Where to go next

• Client setup, then Defining endpoints.
• Coming from another library: TanStack Query or RTK Query.
• Task by task: Recipes.