fetchAction family

fetchAction, getAction, postAction, putAction, patchAction, deleteAction — HTTP asyncAction factories.

import {
  fetchAction,
  getAction,
  postAction,
  putAction,
  patchAction,
  deleteAction,
} from 'mates';

// All return asyncAction — data / isLoading / error / status / cache / polling
const loadUser = getAction<User>({
  host: 'https://api.example.com',
  url: '/users/:id',
  cacheLimit: 10,
});

loadUser({ id: 7, expand: 'posts' });
// → GET https://api.example.com/users/7?expand=posts

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

// Method helpers (same surface as fetchAction with method fixed)
const create = postAction<User>({ host: 'https://api.example.com', url: '/users', body: { role: 'member' } });
const replace = putAction<User>({ url: '/users/:id' });
const patch = patchAction<User>({ url: '/users/:id' });
const remove = deleteAction({ url: '/users/:id' });

Overview

fetchAction (and the method helpers) create an asyncAction whose body calls Mates Fetch. You get the full reactive state machine — data, isLoading, error, status — plus cache / startPolling from the same options object.

Config fixes host, url, method, headers, and default body/params. Call-time args are a plain params object: keys matching :tokens in the URL fill path segments; the rest become query-string params.

Module-level helpers (getAction, …) use the shared fetchClient. Prefer new FetchClient({ host }) + api.getAction(…) when you need a shared base URL or interceptors.

fetchAction vs asyncAction vs asyncAtom

API	Role	Prefer when
`fetchAction` / `getAction`…	HTTP + asyncAction	Declarative URL/method config; call with params. Built on Fetch.
`asyncAction`	Any async fn	Custom Promise work, non-HTTP, or when you wrap `Post`/`Fetch` yourself.
`asyncAtom`	Resource atom	Keyed auto-fetch from atom deps — read like an atom. See asyncAtom.

getAction — real GET with :id params

getAction fills :id from call-time params and hits jsonplaceholder. You get data / isLoading / error / status, plus cancel() and interceptAfter.

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

const loadUser = getAction({

host: 'https://jsonplaceholder.typicode.com',

url: '/users/:id',

cacheLimit: 10,

});

loadUser.interceptAfter((user) => ({

...user,

loadedAt: new Date().toLocaleTimeString(),

}));

const App = () => {

return () => html`

<button class="btn-primary" ?disabled=${loadUser.isLoading()}

@click=${() => loadUser({ id: 1 })}>Load user 1</button>

<button ?disabled=${loadUser.isLoading()}

@click=${() => loadUser({ id: 2 })}>Load user 2</button>

<button class="btn-danger" ?disabled=${loadUser.isLoading()}

@click=${() => loadUser({ id: 999 })}>Missing id</button>

<button class="btn-ghost"

?disabled=${!loadUser.isLoading()}

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

</div>

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

${loadUser.isLoading()

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

: loadUser.error()

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

: loadUser.data()

? html`<p>

<strong>${loadUser.data().name}</strong>

· ${loadUser.data().email}<br>

getAction.cache() vs a plain call

cache({ id }) skips the network on a hit — loadedAt from interceptAfter stays the same. A plain call() always fetches. clearCache() drops the LRU.

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

const loadPost = getAction({

host: 'https://jsonplaceholder.typicode.com',

url: '/posts/:id',

cacheLimit: 10,

cacheDuration: 30_000,

});

// Runs on network success only — cache hits reuse the stamped object

loadPost.interceptAfter((post) => ({

...post,

loadedAt: new Date().toLocaleTimeString(),

}));

const App = () => {

return () => html`

<button class="btn-primary" ?disabled=${loadPost.isLoading()}

@click=${() => loadPost.cache({ id: 1 })}>.cache({ id: 1 })</button>

<button ?disabled=${loadPost.isLoading()}

@click=${() => loadPost.cache({ id: 2 })}>.cache({ id: 2 })</button>

<button ?disabled=${loadPost.isLoading()}

@click=${() => loadPost({ id: 1 })}>call({ id: 1 }) — always network</button>

<button class="btn-ghost" @click=${() => loadPost.clearCache()}>clearCache()</button>

</div>

${loadPost.data()

? html`

<p>

<strong>#${loadPost.data().id}</strong> ${loadPost.data().title}

</p>

<p class="hint">loadedAt stays put on a cache hit: ${loadPost.data().loadedAt}</p>

: nothing

}

postAction — config body, JSON response

postAction sends the config body. Call-time params would go to the URL, not the JSON body — so the payload lives on the factory config.

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

// Call-time args fill :path / query — body is fixed on the config

const createPost = postAction({

host: 'https://jsonplaceholder.typicode.com',

url: '/posts',

body: { title: 'Hello from postAction', body: 'mates fetchAction family', userId: 1 },

});

const App = () => {

return () => html`

<button class="btn-primary"

?disabled=${createPost.isLoading()}

@click=${() => createPost()}>

${createPost.isLoading() ? 'POSTing…' : 'postAction()'}

</button>

</div>

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

${createPost.error()

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

: createPost.data()

? html`<p class="mono">${JSON.stringify(createPost.data())}</p>`

: nothing

}

</div>

};

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

API — fetchAction family

import { fetchAction, getAction, postAction, putAction, patchAction, deleteAction } from 'mates'

Prop / Option	Type	Default	Description
`fetchAction<T>(config?)`	`AsyncActionReturnType<(params?) => Promise>`	—	asyncAction wrapping Fetch. Respects config.method (defaults to GET). Call-time params merge into request params for path/query.
`getAction<T>(config?)`	`same`	—	fetchAction with method fixed to GET.
`postAction<T>(config?)`	`same`	—	fetchAction with method fixed to POST.
`putAction<T>(config?)`	`same`	—	fetchAction with method fixed to PUT.
`patchAction<T>(config?)`	`same`	—	fetchAction with method fixed to PATCH.
`deleteAction<T>(config?)`	`same`	—	fetchAction with method fixed to DELETE.

FetchActionConfig (FetchRequest & AsyncFetchOptions)

Prop / Option	Type	Default	Description
`host / url / path`	`string`	—	Base host and URL template. :tokens in url are filled from params.
`method`	`string`	—	HTTP method for fetchAction. Helpers set this for you.
`params`	`Record`	—	Default path/query params. Call-time params merge on top (call wins per key).
`body`	`BodyInit \| object \| null`	—	Default request body (JSON-serialized for plain objects). Not overwritten by call-time params.
`cacheLimit / cacheDuration / pollInterval`	`number`	—	Same asyncAction options — enable .cache() and startPolling().

Inherited asyncAction surface

Prop / Option	Type	Default	Description
`data() / isLoading() / error() / status()`	`atoms`	—	Reactive state machine — identical to asyncAction.
`cache(...params) / clearCache()`	`void`	—	Memoized invoke and cache eviction.
`startPolling(...params) / stopPolling()`	`void`	—	Requires pollInterval in config.
`cancel() / subscribe() / interceptBefore/After`	`—`	—	Same semantics as asyncAction.

FetchClient instance methods

Prop / Option	Type	Default	Description
`api.fetchAction / getAction / …`	`same factories`	—	On FetchClient — inherit base host, headers, and interceptors.