@svelte-lean/query/paged · Query

Import

import

import { createPaged, tablePaging } from '@svelte-lean/query/paged';

Usage

members.svelte

<script lang="ts">
	import { createPaged } from '@svelte-lean/query/paged';
	import { listMembers } from '$api/members';

	let filters = $state({ search: '' });
	// A filter change resets the page to 1; the previous rows stay while the next page loads.
	const list = createPaged(listMembers, () => filters, { perPage: 25, prefetch: 'next' });
</script>

<input type="search" aria-label="Search members" bind:value={filters.search} />
<ul aria-busy={list.loading}>
	{#each list.rows as member (member.id)}<li>{member.name}</li>{/each}
</ul>
<button disabled={list.page <= 1} onclick={() => list.setPage(list.page - 1)}>Previous</button>
<span>Page {list.page} of {list.lastPage}</span>
<button disabled={list.page >= list.lastPage} onclick={() => list.setPage(list.page + 1)}
	>Next</button
>

Size

Production Vite builds of a small consumer entry, Svelte external. A marginal row is the bytes the entry adds over the row it names.

Build	Over	gzip	brotli	Budget (gzip)
`paged (marginal)`	`query`	1234 B	1109 B	1400 B

Read from packages/query/artifacts/size.json. Every entry and its method: Performance.

Functions

The binding and the adapter to DataTable state.

Exports

Runtime exports of the entry.

Name	Type	Default	Description
# `createPaged`	`(endpoint: QueryEndpoint<P, Page<T>>, filters: () => P \| undefined \| null, options?: PagedOptions) => PagedResult<T>`	–	A query of the current page; page params come from the profile's pageParams.
# `tablePaging`	`(state: () => { pageIndex, pageSize }) => { page, perPage }`	–	Keep the page and the page size in DataTable state: pass the result into the options.

Options

PagedOptions, the third argument of createPaged().

PagedOptions

page and perPage are numbers, or values owned elsewhere (Controlled).

Name	Type	Default	Description
# `page`	`number \| Controlled<number>`	`1`	The page, 1-based.
# `perPage`	`number \| Controlled<number>`	`20`	The page size.
# `when`	`boolean \| (() => boolean)`	–	A state condition: pauses fetching and polling, keeps data.
# `keepPrevious`	`boolean`	`true`	Keep the previous rows while the next page loads.
# `poll`	`PollOption \| (() => PollOption)`	–	Polling of the current page's entry only.
# `fresh`	`Duration`	–	Per-use freshness.
# `prefetch`	`'next' \| 'neighbours' \| false`	`false`	Prefetch the next page, or both neighbours, after a settled answer.

Controlled

A value owned elsewhere (DataTable state, the URL).

Name	Type	Default	Description
# `get`	`() => T`	–	Read the value.
# `set`	`(value: T) => void`	–	Write the value.

Result

PagedResult extends QueryState<Page<T>> (data, error, loading, refreshing, busy, blocked, info, refetch) with the page state.

PagedResult

The fields of QueryState, plus these.

Name	Type	Default	Description
# `rows`	`T[]`	–	The rows; an empty array while there is no data.
# `total`	`number`	–	0 while there is no data; a lower bound when estimated.
# `page`	`number`	–	The effective page, 1-based.
# `perPage`	`number`	–	The page size.
# `lastPage`	`number`	–	The last page, at least 1.
# `estimated`	`boolean`	–	The server sent a bare list without a paginator.
# `setPage`	`(page: number) => void`	–	Go to a page.
# `setPerPage`	`(perPage: number) => void`	–	Change the page size; resets the page to 1.
# `table`	`PagedTableProps<T>`	–	Props for <DataTable manual>: spread them.

PagedTableProps

list.table: one object whose getters each read their own signal.

Name	Type	Default	Description
# `manual`	`true`	–	Server mode of DataTable.
# `data`	`T[]`	–	The rows of the page.
# `rowCount`	`number \| undefined`	–	undefined when the total is unknown.
# `pageCount`	`number`	–	The last page.
# `loading`	`boolean`	–	The user waits for this page.
# `fetching`	`boolean`	–	Any fetch of the page (DataTable’s prop name; busy on the list).
# `refreshing`	`boolean`	–	A quiet refresh: a thin line, the rows stay.

Guide

How to use it, with examples: Lists. All entry points: Svelte Lean Query.