asyncAction

Asynchronous actions with reactive loading, data, and error atoms.

import { asyncAction } from 'mates';

const fetchUser = asyncAction(async (id: string) => {
  const res = await fetch(`https://jsonplaceholder.typicode.com/users/${id}`, {
    signal: fetchUser.abortController.signal,
  });
  if (!res.ok) throw new Error('Not found');
  return res.json() as Promise<{ id: number; name: string }>;
}, { cacheLimit: 5, pollInterval: 4000 });

fetchUser('1');
fetchUser.cache('1');
fetchUser.cancel();

fetchUser.isLoading();
fetchUser.status();
fetchUser.data();
fetchUser.error();

Overview

asyncAction takes an async function and returns an enhanced callable that automatically manages a reactive state machine. Instead of manually setting isLoading, error, and data atoms around every await, you get them as reactive atoms you can read directly in templates.

The returned object is directly callable — fetchUser('u_1'). Reactive atoms update automatically: isLoading flips to true when the call starts, and status transitions through 'loading' → 'success' (or 'error') when it settles.

asyncAction vs asyncAtom vs fetchAction

API	Invocation	Prefer when
`asyncAction`	Call with args	Any Promise workflow; cache/polling factories; custom fetch logic.
`fetchAction` / `getAction`	Call with params	Declarative HTTP config on top of asyncAction. See fetch-actions.
`asyncAtom`	Read like an atom	Keyed auto-fetch from atom deps; refetch/cancel. See State → asyncAtom.

Full API quick reference

import { asyncAction } from 'mates';

const fetchUser = asyncAction(async (id: string) => {
  const res = await fetch(`https://jsonplaceholder.typicode.com/users/${id}`, {
    signal: fetchUser.abortController.signal,
  });
  if (!res.ok) throw new Error('Not found');
  return res.json() as Promise<{ id: number; name: string }>;
}, { cacheLimit: 5, pollInterval: 4000 });

fetchUser.isLoading()
fetchUser.status()     // "init" | "loading" | "success" | "error"
fetchUser.data()
fetchUser.error()

fetchUser('1');
fetchUser.cancel();            // abort() the current AbortController
fetchUser.cache('1');          // skip network on cache hit
fetchUser.clearCache('1');
fetchUser.startPolling('1');
fetchUser.stopPolling();
fetchUser.subscribe(() => console.log(fetchUser.status()), true); // success only
fetchUser.interceptBefore((next, id) => next(String(id).trim()));
fetchUser.interceptAfter((user) => ({ ...user, loadedAt: Date.now() }));

data / isLoading / error / status + interceptAfter

Real GET against jsonplaceholder. interceptAfter stamps loadedAt. status walks init → loading → success | error. User 999 is a 404.

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

const fetchUser = asyncAction(async (id) => {

const res = await fetch(

`https://jsonplaceholder.typicode.com/users/${id}`,

{ signal: fetchUser.abortController.signal },

);

if (!res.ok) throw new Error(`HTTP ${res.status}`);

return res.json();

});

fetchUser.interceptAfter((user) => ({

...user,

loadedAt: new Date().toLocaleTimeString(),

}));

const App = () => {

return () => html`

<button

class="btn-primary"

@click=${() => fetchUser(1)}

?disabled=${fetchUser.isLoading()}

fetchUser(1)

</button>

<button

@click=${() => fetchUser(2)}

?disabled=${fetchUser.isLoading()}

fetchUser(2)

</button>

<button

class="btn-danger"

@click=${() => fetchUser(999)}

cancel() aborts abortController

The fn listens on fetchUser.abortController.signal. cancel() aborts that controller, drops the result, and sets status back to init.

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

const fetchUser = asyncAction(async () => {

const signal = fetchUser.abortController.signal;

// Pause so cancel() is clickable; abortController.abort() unwinds both

await new Promise((resolve, reject) => {

const t = setTimeout(resolve, 2500);

signal.addEventListener('abort', () => {

clearTimeout(t);

reject(Object.assign(new Error('Aborted'), { name: 'AbortError' }));

}, { once: true });

});

const res = await fetch('https://jsonplaceholder.typicode.com/users/1', { signal });

if (!res.ok) throw new Error('Not found');

return res.json();

});

const App = () => {

return () => html`

<button

class="btn-primary"

@click=${() => { void fetchUser(); }}

?disabled=${fetchUser.isLoading()}

Start Request

</button>

${fetchUser.isLoading()

? html`

<button class="btn-danger" @click=${() => fetchUser.cancel()}>

cancel()

</button>

: nothing}

</div>

API — asyncAction

import { asyncAction } from 'mates';

Prop / Option	Type	Default	Description
`fn`*	`(...args: A) => Promise`	—	The async function to wrap. Its argument types become the call signature.
`options.cacheLimit`	`number`	—	Maximum number of cached results to keep. When set, results are memoised by serialised arguments.
`options.pollInterval`	`number`	—	Milliseconds between auto-polls when startPolling() is active. Default 5000 when omitted from options object defaults.

Reactive atoms — read inside a template or effect

Prop / Option	Type	Default	Description
`data()`	`Awaited \| null`	`null`	Holds the last successfully resolved value. Stays at the previous success value while a new request is in flight, so the UI never flickers to null mid-request.
`isLoading()`	`boolean`	`false`	Flips to true the moment run() is called and back to false once the async function resolves or throws. Read inside a template to show spinners or disable buttons.
`error()`	`Error \| null`	`null`	Set to the thrown Error on failure; automatically reset to null at the start of the next run() so stale errors don't linger after a retry.
`status()`	`"init" \| "loading" \| "success" \| "error"`	`"init"`	Full state-machine status. Prefer this over boolean flags when you need to distinguish 'never called yet' (init) from an in-flight request (loading) or a settled result.

Methods

Prop / Option	Type	Default	Description
`(...args) / callable`	`Promise`	—	Invoke the wrapped async function. The returned object is itself callable — there is no separate .run().
`cancel()`	`void`	—	Aborts the current AbortController (and any ZeroPromise), drops the in-flight result, sets isLoading to false and status to init. Wire fetch(..., { signal: action.abortController.signal }) so the network request aborts too.
`abortController`	`AbortController \| null`	—	The controller for the in-flight run. Created at the start of each call; null when idle. Pass .signal into fetch or listen for abort.
`subscribe(fn, onSuccessOrError?)`	`() => void`	—	Listener after each settle. Second arg true = success only, false = error only, omit = both. Returns unsubscribe.
`val() / set(fn)`	`—`	—	Read or replace the underlying async function without losing atoms, cache, or interceptors.
`clearCache(...args?)`	`void`	—	Evict one cache key (args) or the whole LRU when called with no args.
`cache(...args)`	`void`	—	Invoke the action and memoize the result keyed by serialized args. On a cache hit the async function is skipped entirely and the cached value is written to data() immediately.
`startPolling(...args)`	`void`	—	Begin auto-polling: immediately calls the action with args, then repeats every pollInterval milliseconds. Requires options.pollInterval to be configured — otherwise logs an error and does nothing.
`stopPolling()`	`void`	—	Stop the active poll loop. The last fetched data and status remain intact until the next manual call.
`interceptBefore(fn)`	`void`	—	Register argument middleware. Receives (next, ...args) — transform or validate args and call next() to continue, or throw to abort the execution.
`interceptAfter(fn)`	`void`	—	Register result middleware. Receives the resolved value and must return the (possibly transformed) value that gets written to data().