Cache & Polling Factories

Low-level createCacheManager and createPollingManager factory functions.

import { asyncAction } from 'mates';

const searchUsers = asyncAction(
  async (query: string) => {
    const res = await fetch(
      `https://jsonplaceholder.typicode.com/users?q=${encodeURIComponent(query)}`,
      { signal: searchUsers.abortController.signal },
    );
    return res.json();
  },
  {
    cacheLimit: 25,
    cacheDuration: 60_000,
    pollInterval: 10_000,
  },
);

searchUsers.cache('ada');      // skip network on cache hit
searchUsers.clearCache('ada'); // evict one key
searchUsers.clearCache();      // evict all

searchUsers.startPolling('ada');
searchUsers.stopPolling();
searchUsers.subscribe(() => console.log(searchUsers.status()));

Overview

asyncAction supports transparent result caching (LRU with optional TTL) and automatic periodic re-fetching. Both features are opt-in via the options object — set cacheLimit / cacheDuration for caching, and pollInterval before calling startPolling().

Use .cache(...args) to invoke with memoization (skips the async function on a cache hit). Use startPolling(...args) / stopPolling() for live dashboards and other “keep fresh” UIs. For advanced composition outside asyncAction, see createCacheManager / createPollingManager.

Built-in vs standalone factories

Approach	When to use	Notes
`asyncAction` options + methods	Common case	`cacheLimit` / `cacheDuration` / `pollInterval` plus `.cache()`, `.startPolling()`, etc.
`createCacheManager` / `createPollingManager`	Advanced	Compose a custom async primitive outside of `asyncAction`. Most apps never need these directly.

asyncAction.cache() and startPolling()

cache(1) skips the network on a hit — loadedAt stays put. A plain call(1) always fetches. startPolling(1) / stopPolling() use pollInterval. subscribe() logs each settle.

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

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

const res = await fetch(

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

{ signal: loadUser.abortController.signal },

);

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

const user = await res.json();

// Stamp happens only on a real run — .cache() hits reuse this object

return { ...user, loadedAt: new Date().toLocaleTimeString() };

}, { cacheLimit: 10, cacheDuration: 30_000, pollInterval: 4000 });

const events = atom([]);

loadUser.subscribe(() => {

events.set((prev) => [

`${loadUser.status()} · ${loadUser.data()?.name ?? loadUser.error()?.message ?? '—'}`,

...prev,

].slice(0, 4));

});

const App = () => {

const polling = atom(false);

return () => html`

<button class="btn-primary" @click=${() => loadUser.cache(1)} ?disabled=${loadUser.isLoading()}>

.cache(1)

</button>

<button @click=${() => loadUser.cache(2)} ?disabled=${loadUser.isLoading()}>

.cache(2)

</button>

<button @click=${() => loadUser(1)} ?disabled=${loadUser.isLoading()}>

call(1) — always network

</button>

API — Cache & Polling (asyncAction)

import { asyncAction } from 'mates'

Prop / Option	Type	Default	Description
`options.cacheLimit`	`number`	`10`	Maximum number of cached results to retain. Uses LRU eviction — the oldest entry is removed when the limit is exceeded.
`options.cacheDuration`	`number`	`undefined`	TTL in milliseconds for each cache entry. Entries older than this are treated as misses on the next call. Omit for infinite-duration caching.
`options.pollInterval`	`number`	`5000`	Interval in milliseconds between automatic re-fetches when polling is active. Required before startPolling() can be called.

Cache methods

Prop / Option	Type	Default	Description
`fetchData.cache(...args)`	`void`	—	Call the action and cache the result keyed by args. Subsequent calls with identical args return the cached result without re-running the async function.
`fetchData.clearCache()`	`void`	—	Evict all cached results. The next call will always execute the async function regardless of previous results.
`fetchData.clearCache(...args)`	`void`	—	Evict only the cache entry matching the given argument key.

Polling methods

Prop / Option	Type	Default	Description
`fetchData.startPolling(...args)`	`void`	—	Start auto-polling: immediately calls the action with args, then repeats every pollInterval milliseconds. Requires pollInterval in options.
`fetchData.stopPolling()`	`void`	—	Stop the active polling interval. The last fetched data and status remain intact until the next manual call.

Standalone factories (advanced)

Prop / Option	Type	Default	Description
`createCacheManager(opts?)`	`CacheManager`	—	Build a standalone LRU cache layer for custom async primitives. Prefer asyncAction options for normal use.
`createPollingManager(opts?)`	`PollingManager`	—	Build a standalone polling layer for custom async primitives. Prefer asyncAction.pollInterval for normal use.