Extended Atoms

debouncedAtom and paginationAtom — timed writes and page-index helpers.

import { atom, debouncedAtom, paginationAtom } from 'mates';

// ── debouncedAtom: last write in the delay window wins ─────────
const raw = atom('');
const search = debouncedAtom(raw, 300);   // mirror source, lag 300ms
// Or standalone: const search = debouncedAtom('', 300);

// ── paginationAtom: AtomType<number> + page helpers ────────────
const page = paginationAtom(1);
page(); page.currentPage;          // read
page.next(); page.prev();          // prev floors at 1
page.reset(); page.set(10);        // jump / reset

// Persistence (lsStore / ssStore) → /docs/state/storage via useUtils()

Overview

These helpers extend the core atom model for two common needs: timed writes (debouncedAtom) and a reactive page index (paginationAtom).

debouncedAtom(sourceOrValue, delay) accepts either a plain initial value or a source atom. Writes (or mirrored source changes) wait until delay ms of quiet — only the last value in the window commits. Timer cleanup is registered automatically.

paginationAtom(initial?) is a full AtomType<number> plus next(), prev() (floors at 1), reset(), and a currentPage alias — not a separate pageSize/totalPages object.

Browser persistence bags (lsStore / ssStore) live on useUtils() — see Storage. Theme and document title are covered under themeAtom / titleAtom.

Which helper

Helper	Role	Notes
`debouncedAtom`	timed writes	Last write in the delay window fires; good for search / autosave.
`paginationAtom`	page number	Atom<number> helpers — use with your own total/pageSize logic.
`lsStore` / `ssStore`	persist	Dedicated page — /docs/state/storage.

Pagination cheatsheet

// paginationAtom — AtomType<number> helpers
const page = paginationAtom(1);
page.next();  // 2
page.prev();  // 1 (never below 1)
page.set(10); // jump
page.reset(); // back to 1

// Persistence → useUtils().lsStore / ssStore
// See /docs/state/storage

debouncedAtom — debounced search

The raw query atom updates on every keystroke, but the debounced atom only propagates changes after the user stops typing for 400 ms — ideal for search inputs that trigger API calls.

import { html, atom, debouncedAtom, renderApp } from 'mates';

const App = () => {

const query = atom('');

// Only updates debounced after 400ms of no typing

const debounced = debouncedAtom(query, 400);

return () => html`

<input

.value=${query()}

@input=${e => query.set(e.target.value)}

placeholder="Type to search..."

<span class="overline">Typed</span>

<span class="card-title">${query() || '—'}</span>

</div>

<span class="overline">Debounced (400ms)</span>

<span class="card-title">${debounced() || '—'}</span>

</div>

};

renderApp(App, document.getElementById('app'));

paginationAtom — page index

next / prev / reset helpers on a normal number atom. prev() floors at 1; pair with your own totalPages math.

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

const App = () => {

const page = paginationAtom(1);

const totalPages = 5;

return () => html`

<p class="muted m-t-5">Page ${page.currentPage} / ${totalPages}</p>

<button @click=${() => page.prev()} ?disabled=${page() <= 1}>Prev</button>

<button class="btn-primary" @click=${() => {

if (page() < totalPages) page.next();

}} ?disabled=${page() >= totalPages}>Next</button>

<button class="btn-ghost" @click=${() => page.reset()}>Reset</button>

</div>

};

renderApp(App, document.getElementById('app'));

API — Extended atoms

import { debouncedAtom, paginationAtom } from 'mates'

Prop / Option	Type	Default	Description
`debouncedAtom(valueOrAtom, delay, config?)`*	`AtomType`	—	Returns an atom whose set/update (or mirrored source changes) commit only after delay ms of quiet — the last write in the window wins. Accepts a plain initial value or a source AtomType. Cleanup of the internal timer is registered automatically.
`paginationAtom(initial?, config?)`	`PaginationAtomType`	—	AtomType starting at initial (default 1), plus next(), prev() (floors at 1), reset() (sets 1), and readonly currentPage alias. Full atom API (.set, .update, .get, etc.) remains available.

paginationAtom helpers

Prop / Option	Type	Default	Description
`page()`	`number`	—	Callable reactive read of the current page (1-based).
`.currentPage`	`number`	—	Readonly alias for the current value (same as page.get()).
`.next()`	`void`	—	Increment page by 1 via set(prev => prev + 1).
`.prev()`	`void`	—	Decrement by 1, floored at 1 — never goes below page 1.
`.reset()`	`void`	—	Set page back to 1.
`.set(n) / .set(fn)`	`void`	—	Standard atom write — jump to a page or apply an updater. Use this for arbitrary page jumps.