iAtom / signal

Immutable atom — deep-freezes every value; no update(). Use for configs and read-models where mutation should fail loudly.

import { iAtom, signal } from 'mates';

// iAtom and signal are identical exports — use either name.
const config = iAtom({ theme: 'dark', locale: 'en' });

config();                              // read (reactive)
config.get();                          // same
config.val;                            // same

config.set({ theme: 'light', locale: 'en' }); // replace + deep-freeze
config.set(prev => ({ ...prev, theme: 'light' })); // updater + spread

config.reset();                        // restore frozen initial (same ref)
config.lock();                         // inherits atom lock/unlock
config.unlock();

// config.update(...)  // ❌ does not exist — TypeScript error
Object.isFrozen(config());             // true — deep-frozen on every write

Overview

iAtom (also exported as signal) is an immutable atom built on atom({ freeze: true }). Plain atom values are mutable by default — you can call .update() or mutate objects in place. With iAtom, every value written via .set() is deep-frozen, including the initial value and nested objects/arrays.

That turns accidental mutation into a runtime error (TypeError: Cannot assign to read only property in strict mode) instead of a silent bug where the UI never updates because nothing notified the atom.

The read API matches atom: call the atom, use .get(), or read .val. The write path is replace-only: pass a new value or an updater that returns a new object. There is no .update(). .reset() restores the frozen initial value (same reference — no clone). lock / unlock / freeze are inherited from atom.

API differences from atom

Member	Status	Notes
`()` / `.get()` / `.val`	same	Reactive reads work identically.
`.set(value)`	same + freeze	Deep-freezes the incoming value before storing.
`.set(prev => next)`	same + freeze	Updater fn — use spread to derive new objects.
`.update()`	removed	Does not exist on iAtom — use `.set()` with a new value.
`.reset()`	iAtom only	Restores the frozen initial reference (no clone).
`.lock` / `.unlock`	inherited	Same passcode semantics as `atom`.

Immutable config object

Every set() call deep-freezes the new value. Use spread in the updater to change one field without mutating the previous object.

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

const App = () => {

const config = iAtom({ theme: 'dark', fontSize: 16, lang: 'en' });

const log = atom([]);

const update = (key, val) => {

config.set(prev => ({ ...prev, [key]: val }));

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

};

return () => html`

<span class="label">Current config (frozen object)</span>

${JSON.stringify(config(), null, 2)}</pre>

<span class="hint">isFrozen: ${Object.isFrozen(config())}</span>

</div>

<button class="btn-ghost" @click=${() => update('theme', config().theme === 'dark' ? 'light' : 'dark')}>

Toggle theme

</button>

<button class="btn-ghost" @click=${() => update('fontSize', config().fontSize + 2)}>

Font +2

</button>

<button class="btn-ghost" @click=${() => update('lang', config().lang === 'en' ? 'fr' : 'en')}>

Toggle lang

</button>

</div>

<span class="overline">Change log</span>

${log().length === 0

? html`<div class="mono subtle">No changes yet…</div>`

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

}

Mutation fails — replace instead

Try a direct property write (blocked by freeze), then fix it with set() + spread. Nested objects are frozen too.

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

const App = () => {

const settings = iAtom({ theme: 'dark', nested: { debug: true } });

const message = iAtom('Try mutating — then replace with set()');

const tryMutate = () => {

try {

settings().theme = 'light';

message.set('Mutation appeared to work (non-strict) — but Object.isFrozen is still true');

} catch (e) {

message.set('Blocked: ' + (e && e.message ? e.message : String(e)));

}

};

const replaceCorrectly = () => {

settings.set(prev => ({

...prev,

theme: prev.theme === 'dark' ? 'light' : 'dark',

nested: { ...prev.nested },

}));

message.set('Replaced via set() + spread — the right pattern');

};

return () => html`

${JSON.stringify(settings(), null, 2)}</pre>

frozen: ${Object.isFrozen(settings())} / nested: ${Object.isFrozen(settings().nested)}

</span>

</div>

<p class="muted">${message()}</p>

<button class="btn-danger" @click=${tryMutate}>Try direct mutation</button>

reset() to frozen initial

After edits, reset() restores the exact initial frozen reference.

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

const App = () => {

const cfg = iAtom({ api: 'https://v1.example', retries: 3 });

return () => html`

<pre class="mono">${JSON.stringify(cfg(), null, 2)}</pre>

cfg.set(prev => ({ ...prev, api: 'https://v2.example', retries: prev.retries + 1 }))

}>Bump version</button>

<button @click=${() => cfg.reset()}>reset()</button>

</div>

<p class="muted m-t-5">reset() restores the frozen initial reference — no clone.</p>

</div>

};

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

API — iAtom

import { iAtom, signal } from 'mates'

Prop / Option	Type	Default	Description
`iAtom(initial, config?)`*	`IAtomType`	—	Creates an immutable atom. Initial value is deep-frozen immediately. Optional AtomConfig (freeze is always on). Identical to signal(initial).
`signal(initial, config?)`	`IAtomType`	—	Alias for iAtom — same implementation, either name is fine.
`config()`	`Readonly`	—	Read the current frozen value reactively. Registers as a dependency in templates, effects, and derived atoms.
`config.get()`	`Readonly`	—	Explicit reactive read — identical to config().
`config.val`	`Readonly`	—	Property-form reactive read — identical to config().
`config.set(value, silently?)`	`void`	—	Replace the stored value. Incoming value is deep-frozen recursively, then subscribers are notified (unless silently true).
`config.set(fn, silently?)`	`void`	—	Updater form — receives the current frozen value as prev and must return a new object/array/primitive. Result is deep-frozen. Use spread — do not mutate prev.
`config.reset()`	`void`	—	Restore the frozen initial value (same reference — no clone). Notifies subscribers.
`config.lock(passcode?)`	`void`	—	Block further set (default passcode "default"). Inherited from atom.
`config.unlock(passcode?)`	`void`	—	Re-enable writes; throws on passcode mismatch.
`config.freeze()`	`void`	—	Deep-freeze the current value in place (already frozen after each set).
`config.__subscribe(fn)`	`() => void`	—	Manual subscription; returns unsubscribe. Prefer template reads / effect / on.
`config.toJSON()`	`string`	—	JSON.stringify of the current value.
`config.name`	`string`	`"iAtom"`	Writable label.
`config.__version__ / __id__ / __isAtom___`	`meta`	—	Same introspection fields as atom.

iAtom vs atom

Prop / Option	Type	Default	Description
`atom(value)`	`AtomType`	—	Mutable atom. Supports set(), update() (in-place), lock/unlock. No freeze guarantee — ideal for local UI state.
`iAtom(value)`	`IAtomType`	—	Immutable atom. Omits update(). Adds reset(). Every written value is deep-frozen. Prefer for configs, server payloads, and shared read-models.
`df(value)`	`T`	—	Re-export of deepFreeze for manual freezing outside iAtom.