State Management

Map of Mates state: atom, iAtom, typed factories, collections, asyncAtom, molecule, useState, store, memo, effect, and scopes.

import { atom, iAtom, memo, effect, useState, store } from 'mates';

// Start here — fine-grained reactive cell
const count = atom(0);
count(); count.set(n => n + 1);

// Immutable variant (deep-freeze on set)
const config = iAtom({ theme: 'dark' });

// Derived + side effects
const double = memo(() => count() * 2);
effect(() => console.log(count()));

// Object-shaped local / shared state when methods group naturally
const form = useState({ name: '', submit() { /* … */ } });
const session = store({ userId: null as string | null });

Overview

Mates state is built around atom — a callable reactive cell. Read with count() inside templates, memos, and effects; write with .set() / .update(). Same-value writes still notify.

Specialize from there: iAtom for deep-frozen configs, atom.number / atom.array / atom.list for helpers, asyncAtom for keyed fetches, and molecule to walk nested atom bags. Reach for useState / store when state is naturally an object with methods, and scope to share down the tree without prop drilling.

Create atoms in the component outer function. SPA module-level atoms are shared client singletons; SSR App.ts module scope throws. Never inside the template. See Restricted Usage.

Choose a primitive

API	Role	Prefer when
`atom`	Core cell	Default reactive value — counters, fields, small objects.
`iAtom` / `signal`	Frozen	Configs / payloads where in-place mutation must fail.
`atom.number` … `atom.object`	Typed helpers	Domain methods (incr, toggle, push, setItem, …).
`atom.list` / Map / Set / stack	Collections	Keyed lists, native Map/Set, LIFO/FIFO.
`asyncAtom`	Async resource	Keyed fetch with status / loading / refetch.
`useState` / `store`	Object state	Local vs module-level bags with methods.
`memo` / `effect`	Derived / effects	Computed values and reactive side effects.

Default: plain atom

Most UI state starts as atom(value). Read in the template; set from events.

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

const App = () => {

const count = atom(0);

return () => html`

<h1>${count()}</h1>

<button class="btn-primary" @click=${() => count.set(n => n + 1)}>+1</button>

<button @click=${() => count.set(0)}>Reset</button>

</div>

};

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

Typed factories (preview)

atom.number / atom.bool / atom.string add small helpers on top of the same atom engine. Full API on Typed atom.* factories.

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

const App = () => {

const n = atom.number(0);

const on = atom.bool(false);

const label = atom.string('off');

return () => html`

<p class="muted m-t-5">${label()} · bool=${on()}</p>

<button @click=${() => {

on.toggle();

label.set(on() ? 'on' : 'off');

}}>toggle</button>

</div>

};

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

API — State family (map)

import { atom, iAtom, asyncAtom, molecule, memo, effect } from 'mates'

Prop / Option	Type	Default	Description
`atom(initial)`	`AtomType`	—	Core mutable reactive cell. See /docs/state/atoms.
`iAtom(initial) / signal`	`IAtomType`	—	Deep-frozen atom + reset(). See /docs/state/iatom.
`atom.number / .bool / .string / .array / .object`	`typed AtomType`	—	Shape helpers. See /docs/state/typed-atoms.
`atom.list / .advancedList / .stack / .queue / .Map / .Set`	`collection types`	—	Collections. See /docs/state/collections.
`asyncAtom(fetcher, options)`	`AsyncAtomReturnType`	—	Keyed async resource. See /docs/state/async-atom.
`molecule.every / .some / .each`	`helpers`	—	Walk nested atom bags. See /docs/state/molecule.
`memo(fn) / effect(fn)`	`derived / effect`	—	Computed values and side effects. See /docs/state/memo.
`useState / store / scope`	`object / shared`	—	Object bags and hierarchical sharing — dedicated leaves.