action

Synchronous action wrapper with loading and error state.

import { action } from 'mates';

const addToCart = action((item: string, qty = 1) => {
  cart[item] = (cart[item] ?? 0) + qty;
  return { item, qty, total: cart[item] };
});

addToCart('widget', 2);

const unsub = addToCart.__subscribe((result) => {
  console.log('Added:', result);
});

addToCart.interceptBefore((next, item, qty) => {
  if (!item) throw new Error('Item is required');
  return next(item.trim(), qty);
});
addToCart.interceptAfter((result) => ({ ...result, at: Date.now() }));

// Swap the implementation without losing interceptors / subscribers
addToCart.set((item, qty = 1) => ({ item, qty, total: qty }));
addToCart.val();
unsub();

Overview

action wraps a synchronous function and adds observability: subscribers that fire on every call, before/after interceptors for validation and result enrichment, and a consistent callable interface.

The result is still returned synchronously — wrapping a function in action does not change its calling behavior. What you gain is a centralized execution point with hooks for analytics, logging, and side-channel effects without coupling them at the call site.

Subscribe with .__subscribe(fn) (not .subscribe — that name belongs to asyncAction).

Empty input is blocked by interceptBefore (not a custom guard at the click handler). interceptAfter stamps char count. __subscribe logs every success. save.set() swaps the implementation without dropping interceptors or subscribers.

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

import { action } from 'mates';

const App = () => {

const input = atom('');

const saved = atom([]);

const callCount = atom(0);

const implName = atom('plain');

const save = action((text) => {

return { text, savedAt: new Date().toLocaleTimeString() };

});

// Validation lives on the action, not at each call site

save.interceptBefore((next, text) => {

const trimmed = String(text).trim();

if (!trimmed) throw new Error('empty');

return next(trimmed);

});

save.interceptAfter((r) => ({ ...r, chars: r.text.length }));

save.__subscribe((result) => {

if (!result) return; // interceptBefore threw

saved.set((prev) => [result, ...prev].slice(0, 5));

callCount.set((n) => n + 1);

});

const onSave = () => {

try {

save(input());

input.set('');

} catch {

/* empty input blocked by interceptBefore */

}

};

interceptBefore / interceptAfter

Before interceptor trims + uppercases; empty input throws. After interceptor tags the result. Subscriber sees the enriched value.

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

const App = () => {

const log = atom([]);

const save = action((text) => ({ text, at: new Date().toLocaleTimeString() }));

save.interceptBefore((next, text) => {

if (!String(text).trim()) throw new Error('empty');

return next(String(text).trim().toUpperCase());

});

save.interceptAfter((r) => ({ ...r, ok: true }));

save.__subscribe((r) => {

log.set(prev => [`${r.at} → ${r.text}`, ...prev].slice(0, 4));

});

return () => html`

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

try { save(' hello '); } catch (e) { /* empty */ }

}}>Save "hello"</button>

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

try { save(' '); } catch (e) {

log.set(prev => ['blocked: empty', ...prev].slice(0, 4));

}

}}>Save empty</button>

</div>

${log().map(e => html`<div class="mono">${e}</div>`)}

</div>

};

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

API — action

import { action } from 'mates'

Prop / Option	Type	Default	Description
`action(fn)`*	`ActionReturnType`	—	Wraps fn and returns a callable with the same signature. The returned function also exposes __subscribe, interceptBefore, and interceptAfter methods.
`save(arg)`	`ReturnType`	—	Execute fn synchronously, notify all subscribers with the return value, then return that value. Call site behavior is unchanged.
`save.__subscribe(cb)`	`() => void`	—	Register a subscriber called after every invocation. cb receives the return value of fn (or undefined on throw). Returns an unsubscribe function.
`save.interceptBefore(fn)`	`void`	—	Register argument middleware. Receives (next, ...args) — transform or validate args and call next() to continue, or throw to abort execution.
`save.interceptAfter(fn)`	`void`	—	Register result middleware. Receives the return value of fn and must return the (possibly transformed) value that is emitted to subscribers.
`save.val() / save.set(fn)`	`—`	—	Read or replace the underlying function without losing subscribers.

Overview

action — intercept, subscribe, and set()

interceptBefore / interceptAfter