paginatedAsyncAction

Paginated data loading with cursor/page support.

import { paginatedAsyncAction } from 'mates';

type User = { id: number; name: string; email: string };

const fetchUsers = paginatedAsyncAction(async () => {
  const page = fetchUsers.page.val; // snapshot — not page()
  const res = await fetch(
    `https://jsonplaceholder.typicode.com/users?_page=${page}&_limit=5`,
    { signal: fetchUsers.abortController.signal },
  );
  if (!res.ok) throw new Error('Failed to load users');
  const total = Number(res.headers.get('X-Total-Count') || 10);
  fetchUsers.totalPages.set(Math.ceil(total / 5));
  return res.json() as Promise<User[]>;
});

fetchUsers();        // load page 1
fetchUsers.next();   // page++ then fetch (no-op on last page)

fetchUsers.isLoading();
fetchUsers.data();
fetchUsers.page();
fetchUsers.totalPages();

Overview

paginatedAsyncAction extends asyncAction with a dedicated page cursor and helpers like next(). You get the full reactive state machine (isLoading, data, error, status) plus page and totalPages atoms.

The async function receives no arguments — read fetchPosts.page.val (the non-reactive snapshot) inside the fn to build the request URL without registering the page atom as a reactive dependency. Set totalPages from the response so Prev/Next buttons can disable at the boundaries.

vs asyncAction

Capability	asyncAction	paginatedAsyncAction
Reactive state machine	data / isLoading / error / status	Same atoms, same semantics.
Page cursor	—	`.page()` atom (starts at 1) + writable `.page.set()`.
Total pages	—	`.totalPages()` — set inside fn from the API response.
Next helper	—	`.next()` increments page and re-fetches in one call.

paginatedAsyncAction — jsonplaceholder users

Reads fetchUsers.page.val inside the fn, sets totalPages from X-Total-Count, and wires abortController. next() advances; Prev uses page.set then a call. next() is a no-op on the last page.

import { html, nothing, renderApp } from 'mates';

import { paginatedAsyncAction } from 'mates';

const LIMIT = 5;

const fetchUsers = paginatedAsyncAction(async () => {

const page = fetchUsers.page.val; // snapshot — do not call page() inside fn

const res = await fetch(

`https://jsonplaceholder.typicode.com/users?_page=${page}&_limit=${LIMIT}`,

{ signal: fetchUsers.abortController.signal },

);

if (!res.ok) throw new Error('Failed to load users');

const total = Number(res.headers.get('X-Total-Count') || 10);

fetchUsers.totalPages.set(Math.ceil(total / LIMIT));

return res.json();

});

fetchUsers(); // page 1

const App = () => {

return () => html`

<p class="muted">status=${fetchUsers.status()} · page=${fetchUsers.page()} / ${fetchUsers.totalPages()}</p>

${fetchUsers.isLoading()

? html`<p class="muted">Loading page ${fetchUsers.page()}…</p>`

: fetchUsers.error()

? html`<p>${fetchUsers.error().message}</p>`

: fetchUsers.data()?.map(user => html`

<span class="tag">${user.email}</span>

</div>

}

<button class="btn-ghost"

API — paginatedAsyncAction

import { paginatedAsyncAction } from 'mates'

Prop / Option	Type	Default	Description
`paginatedAsyncAction(fn, opts?)`*	`PaginatedAction`	—	Like asyncAction but adds page, totalPages atoms and a next() helper. fn receives no arguments — read fetchPage.page.val inside fn to get the current page number.

Pagination helpers

Prop / Option	Type	Default	Description
`fetchPage()`	`void`	—	Triggers a fetch for the current page. Equivalent to calling the action. Does not auto-increment the page.
`fetchPage.next()`	`void`	—	Increments page by 1 and triggers a fetch in a single call. Ideal for “Load more” / Next buttons.
`fetchPage.page`	`AtomType`	—	Reactive atom holding the current page number. Starts at 1. Writable — set it then call fetchPage() to jump to any page.
`fetchPage.totalPages`	`AtomType`	—	Reactive atom for total page count. Set this manually inside fn after computing it from the response (e.g. Math.ceil(total / pageSize)). Default -1 (unknown).

Reactive atoms (inherited from asyncAction)

Prop / Option	Type	Default	Description
`fetchPage.data()`	`T \| null`	`null`	Holds the last successful page result. Stays at the previous value while a new page is in flight.
`fetchPage.isLoading()`	`boolean`	`false`	True while a fetch is in progress — use to disable Prev/Next and show spinners.
`fetchPage.error()`	`Error \| null`	`null`	Holds the last error, or null after a successful fetch. Cleared at the start of the next run.
`fetchPage.status()`	`"init" \| "loading" \| "success" \| "error"`	`"init"`	Full state-machine status matching the current request state.

Options (opts)

Prop / Option	Type	Default	Description
`cacheLimit`	`number`	`undefined`	Maximum number of cached results to retain. Accepts the same option as asyncAction.
`cacheDuration`	`number`	`undefined`	TTL in milliseconds for each cache entry. Same semantics as asyncAction.
`pollInterval`	`number`	`undefined`	Interval for startPolling(). Same semantics as asyncAction.