asyncAtom

Query-style resource atom — keyed auto-fetch, status, cancel, and refetch.

import { atom, asyncAtom } from 'mates';

const userId = atom('u1');

const user = asyncAtom(
  async ({ zero }) => {
    const res = await fetch('/api/users/' + userId(), { signal: zero.signal });
    if (!res.ok) throw new Error('Not found');
    return res.json();
  },
  {
    default: null,
    keys: [userId],   // auto-run when keys change (atoms only)
    debounce: 0,      // ms before auto-run (default 0)
    staleTime: -1,    // >0 = quiet background refresh interval (ms)
  },
);

user();              // same as user.data()
user.data();         // AtomType<T>
user.isLoading();    // boolean atom
user.status();       // "init" | "loading" | "success" | "error"
user.error();        // Error | null atom
user.isError();      // boolean helper
user.refetch();      // Promise<void> — force fetch
user.cancel();       // abort in-flight ZeroPromise

// Omit / empty keys → no auto-run; only refetch() fetches

Overview

asyncAtom is a query-style resource: a fetcher plus reactive data, isLoading, error, and status atoms. Calling the asyncAtom reads data.

Pass keys (an array of atoms) to auto-run when those keys change. Omit or pass an empty keys array for manual-only mode — then only refetch() fetches.

The fetcher receives { zero } — a ZeroPromise with .signal / .cancel() for abort. Optional debounce delays auto-run; staleTime > 0 schedules quiet background refreshes after settle.

asyncAtom vs nearby APIs

API	Role	Prefer when
`asyncAtom`	Resource	Keyed/manual fetch with status — read like an atom.
`asyncAction`	Callable workflow	Invoke with args; cache/polling helpers. See Actions.
`atom` + manual fetch	DIY	Fine for one-off loads; you wire loading/error yourself.

Keyed auto-fetch

Changing the id key re-runs the fetcher. Simulated delay + error path.

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

const App = () => {

const id = atom('ada');

const profile = asyncAtom(async () => {

await new Promise((r) => setTimeout(r, 600));

if (id() === 'fail') throw new Error('User not found');

return { id: id(), name: id() === 'ada' ? 'Ada' : 'Grace' };

}, { default: null, keys: [id] });

return () => html`

<button @click=${() => id.set('grace')}>grace</button>

<button @click=${() => profile.refetch()}>refetch</button>

</div>

<p class="muted m-t-5">status=${profile.status()} · loading=${profile.isLoading()}</p>

${profile.isLoading()

? html`<p class="muted">Loading…</p>`

: profile.error()

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

: profile()

? html`<p><strong>${profile().name}</strong> (${profile().id})</p>`

: html`<p class="muted">No data</p>`

}

</div>

};

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

Manual refetch (no keys)

Omit keys for refetch-only resources. cancel() aborts the in-flight ZeroPromise.

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

const App = () => {

// No keys → manual refetch only

const joke = asyncAtom(async () => {

await new Promise((r) => setTimeout(r, 500));

const lines = ['Why did the atom cross the road?', 'To get to the other set().'];

return lines[Math.floor(Math.random() * lines.length)];

}, { default: 'Click fetch' });

return () => html`

<p class="muted m-t-5">${joke.status()}</p>

<button class="btn-primary" @click=${() => joke.refetch()}

?disabled=${joke.isLoading()}>refetch</button>

<button @click=${() => joke.cancel()}>cancel</button>

</div>

};

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

API — asyncAtom

import { asyncAtom } from 'mates'

Prop / Option	Type	Default	Description
`asyncAtom(fetcher, options)`*	`AsyncAtomReturnType`	—	Create a resource atom. fetcher receives AsyncAtomCtx { zero } and returns Promise \| ZeroPromise.

AsyncAtomOptions

Prop / Option	Type	Default	Description
`default`*	`T`	—	Initial / fallback data before first success.
`keys`	`AtomType[]`	`[]`	Key atoms. When omitted/empty, no auto-run — only refetch().
`debounce`	`number`	`0`	Delay (ms) before auto-run after create / key change.
`staleTime`	`number`	`-1`	-1/undefined: no time-based refresh. >0: quiet refetch interval (ms) after settle.

AsyncAtomReturnType<T>

Prop / Option	Type	Default	Description
`user()`	`T`	—	Reactive read of data (same as user.data()).
`user.data`	`AtomType`	—	Data atom.
`user.error`	`AtomType`	—	Error atom.
`user.isLoading`	`AtomType`	—	Loading flag atom.
`user.status`	`AtomType<"init"\|"loading"\|"success"\|"error">`	—	Status machine atom.
`user.isError()`	`boolean`	—	True when status is error.
`user.refetch()`	`Promise`	—	Force a fetch (bypasses same-key skip).
`user.cancel()`	`void`	—	Abort in-flight ZeroPromise; clear debounce/stale timers.
`user.__isAsyncAtom___`	`true`	—	Type discriminator.

AsyncAtomCtx

Prop / Option	Type	Default	Description
`zero`	`ZeroPromise`	—	Current run’s ZeroPromise — use zero.signal / zero.cancel() for abort.