atom

Core reactive primitive — reads track, writes notify (including same-value set). Lock, silent writes, and derived atoms included.

import { atom } from 'mates';

const count = atom(0);
const profile = atom({ name: 'Ada', score: 0 });

count();                     // reactive read (preferred)
count.get();                 // same
count.val;                   // same

count.set(5);                // replace + notify
count.set(prev => prev + 1); // updater
count.set(99, true);         // silent — value changes, no notify
count.val = 10;              // shorthand for count.set(10)

profile.update(p => { p.score += 10; }); // in-place (objects/arrays)

// Derived — pass a function; recomputes when deps change
const double = atom(() => count() * 2);

count.lock();                // block further set/update
count.unlock();              // re-enable writes

Overview

atom is the foundational reactive unit in Mates. It is a plain callable function object — calling it reads the value and registers a reactive dependency so the enclosing template, memo, or effect re-runs whenever the value changes.

Create atoms in the component outer function (or at module level for app-wide state). Read them with count(), count.get(), or count.val — all three are equivalent reactive reads. Write with .set() (value or updater) or .update() for in-place object/array mutation.

Passing a function to atom() creates a derived atom. The function runs immediately; any atoms read inside become dependencies, and the derived value recomputes whenever they change. Derived atoms can chain.

Same-value writes still notify. Unlike some frameworks, count.set(count()) is treated as a change and re-runs subscribers. Use a silent write (set(v, true)) when you must mutate without notifying.

atom vs nearby APIs

API	Mutability	Prefer when
`atom`	Mutable + notify	Default for reactive values and small objects.
`iAtom` / `signal`	Deep-frozen on set	Configs / read-models where in-place mutation should fail.
`memo(fn)`	Derived only	Same runner as `atom(() => …)`; clearer “computed” intent.
`asyncAtom`	Async data + status	Keyed fetch/refetch with loading/error — not a plain value cell.

Creating and reading atoms

Atoms are reactive variables. Read them in the template with atom() — any template that reads an atom will re-render when it changes.

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

const App = () => {

const count = atom(0);

const name = atom("Ada");

return () => html`

<div>

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

<p class="muted m-t-5">Hello, ${name()}!</p>

</div>

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

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

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

</div>

<input

.value=${name()}

@input=${(e) => name.set(e.target.value)}

placeholder="Enter your name..."

</div>

};

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

Derived atoms

Pass a function to atom() to create a computed value that auto-recomputes when its dependencies change.

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

const App = () => {

const celsius = atom(0);

const fahrenheit = atom(() => Math.round((celsius() * 9) / 5 + 32));

const kelvin = atom(() => Math.round(celsius() + 273.15));

return () => html`

Celsius: <strong>${celsius()}°C</strong>

<input type="range" style=${"--v:" + celsius()} min="0" max="100"

.value=${celsius()}

@input=${(e) => celsius.set(+e.target.value)}

</label>

<span class="overline">Fahrenheit</span>

<span class="card-title">${fahrenheit()}°F</span>

</div>

<span class="overline">Kelvin</span>

<span class="card-title">${kelvin()} K</span>

</div>

};

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

In-place update for objects

profile.update(draft => …) mutates the live object/array and notifies. Prefer this for nested field edits; use set() to replace the whole value.

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

const App = () => {

const profile = atom({ name: "Ada", score: 0 });

return () => html`

<p><strong>${profile().name}</strong> — score ${profile().score}</p>

profile.update(p => { p.score += 10; })

}>+10 score</button>

profile.update(p => { p.name = p.name === "Ada" ? "Grace" : "Ada"; })

}>Rename</button>

</div>

};

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

Lock and unlock writes

While locked, set/update are blocked. Unlock with the same passcode to write again.

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

const App = () => {

const count = atom(0);

const locked = atom(false);

const toggleLock = () => {

if (locked()) { count.unlock(); locked.set(false); }

else { count.lock(); locked.set(true); }

};

return () => html`

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

<p class="muted m-t-5">${locked() ? "Locked — set() is blocked" : "Unlocked"}</p>

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

<button @click=${toggleLock}>${locked() ? "Unlock" : "Lock"}</button>

</div>

};

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

API — atom

import { atom } from 'mates'

Prop / Option	Type	Default	Description
`atom(initial)`	`AtomType`	—	Create a mutable atom with an initial value. The returned object is callable: reading it registers a reactive dependency in templates, effects, and other derived atoms.
`atom(() => expr)`	`AtomType`	—	Create a derived/computed atom. The function runs immediately and any atoms read inside become dependencies — the value recomputes whenever they change. Functionally the same reactive runner as memo(fn); prefer this form for inline derived values inside components.
`atom(initial, config)`	`AtomType`	—	Optional AtomConfig: { freeze?: boolean; skipRestrictedContextCheck?: boolean }. freeze deep-freezes on set and makes update() throw. skipRestrictedContextCheck bypasses the setup-context guard (advanced).
`count()`	`T`	—	Primary reactive read. Registers as a dependency so the enclosing template, effect, or derived atom re-runs when the value changes.
`count.get()`	`T`	—	Explicit reactive read — identical behavior to count(). Use when a callable form is awkward (e.g. passing the getter).
`count.val`	`T`	—	Property-form reactive read (same as count()). Also a setter shorthand: count.val = 5 is equivalent to count.set(5).
`count.set(value, silently?)`	`void`	—	Replace the stored value and notify subscribers. Setting the same value still notifies. Pass silently true to commit without notification. Blocked while locked.
`count.set(fn, silently?)`	`void`	—	Updater form — receives the previous value and must return the next. Prefer this when the new value depends on the old one.
`count.update(fn, silently?)`	`void`	—	In-place mutation helper for objects and arrays: fn receives the live draft, mutates it, then subscribers are notified (unless silent). No-op on primitives/null. Throws if created with { freeze: true }.
`count.lock(passcode?)`	`void`	—	Block further set/update. Default passcode is "default". Writes while locked log an error and are ignored.
`count.unlock(passcode?)`	`void`	—	Re-enable writes. Throws if passcode does not match the lock passcode.
`count.freeze()`	`void`	—	Deep-freeze the current value in place (does not enable freeze-on-set unless you also used config.freeze).
`count.__subscribe(fn)`	`() => void`	—	Manual subscription; returns unsubscribe. Prefer template reads, effect(), or on() in components so cleanup is automatic.
`count.toJSON()`	`string`	—	JSON.stringify of the current value.
`count.name`	`string`	—	Writable label (default "atom") for DevTools / debugging.
`count.__version__`	`number`	—	Increments on notifying writes.
`count.__id__`	`number`	—	Unique numeric id for this atom instance.

AtomConfig

Prop / Option	Type	Default	Description
`freeze`	`boolean`	`false`	If true, values are deep-frozen on set; update() throws.
`skipRestrictedContextCheck`	`boolean`	`false`	Allow create inside templates / effects / memos. Only for advanced directive authors.