mongez-atom-defining-atoms

name

mongez-atom-defining-atoms

description

How to create atoms with `createAtom` and `atomCollection` — options, actions, typing, object helpers, and the built-in mutation API. TRIGGER when: code imports or calls `createAtom` or `atomCollection`, uses `Atom<V>` / `AtomOptions` generics, or invokes `merge`, `change`, `silentChange`, `silentUpdate`, `beforeUpdate`, `watch`, `onChange`, `onReset`, `clone`, `destroy`; user asks "how do I create an atom", "how do I type an atom", "how do I add actions/methods to my atom", or "how do I subscribe to atom changes"; `import { createAtom, atomCollection } from "@mongez/atom"`. SKIP: deep reference of every base method (use `mongez-atom-atoms` for full surface); array verb specifics (use `mongez-atom-collections`); computed atoms (use `mongez-atom-derived` / `mongez-atom-derived-atoms`); SSR stores (use `mongez-atom-atom-store` / `mongez-atom-stores`); persistence (use `mongez-atom-persist` / `mongez-atom-persistence`); React hooks (live in `@mongez/react-atom`).

Defining Atoms

When to use

Load this skill when the user is:

• Creating a new atom with createAtom or atomCollection
• Adding typed actions to an atom
• Using merge, change, watch, silentUpdate, or beforeUpdate
• Subscribing to changes with onChange or onReset
• Working with reset, destroy, or clone

Install

yarn add @mongez/atom
# peer deps: @mongez/events @mongez/reinforcements

Basic atom

import { createAtom } from "@mongez/atom";

const counter = createAtom({
  key: "counter",       // required; must be globally unique
  default: 0,           // required; determines the type of Value
});

counter.value;          // 0
counter.update(5);      // emits update event
counter.update(prev => prev + 1);  // functional update
counter.silentUpdate(0);           // no update event fired
counter.reset();        // back to default (0), emits reset event
counter.silentReset();  // back to default, no update event (reset event still fires)

Typed atoms

Atom<V> is a generic. The default value drives inference; annotate when the inferred type is too narrow:

type Theme = "light" | "dark";

const themeAtom = createAtom({
  key: "ui.theme",
  default: "light" as Theme,   // widen "light" to Theme
});

themeAtom.update("dark");   // OK
themeAtom.update("blue");   // compile error

For objects:

type User = { name: string; age: number };

const userAtom = createAtom({
  key: "user",
  default: { name: "Anon", age: 0 } satisfies User,
});

Object-atom helpers (only on Atom)

When Value is an object or array, these extra methods exist. Calling them on a primitive atom (Atom<boolean>, Atom<number>) is a compile error.

const user = createAtom({
  key: "user",
  default: { name: "Anon", role: "viewer" as "viewer" | "admin" },
});

// Shallow merge — triggers update event
user.merge({ role: "admin" });

// Set one key — triggers update event
user.change("name", "Alice");

// Set one key silently — no update event
user.silentChange("name", "Bob");

// Read one key (supports dot-notation via @mongez/reinforcements)
user.get("name");          // "Bob"

// Subscribe to changes on one key only
const sub = user.watch("role", (next, prev) => {
  console.log("role changed from", prev, "to", next);
});
sub.unsubscribe();   // stop watching

Actions (verbs on the atom)

Actions turn an atom into a command object. this inside each action is the atom instance.

import { createAtom, type Atom } from "@mongez/atom";

const sidebar = createAtom({
  key: "ui.sidebar",
  default: false,
  actions: {
    open()   { this.update(true); },
    close()  { this.update(false); },
    toggle() { this.update(!this.value); },
  },
});

sidebar.open();
sidebar.toggle();
sidebar.value;   // false

TypeScript infers action types from the actions object — no extra type annotations needed for simple cases.

Actions with arguments

type CartItem = { id: string; price: number; qty: number };

const cart = createAtom({
  key: "cart",
  default: [] as CartItem[],
  actions: {
    addItem(item: CartItem) {
      this.update([...this.value, item]);
    },
    setQty(id: string, qty: number) {
      this.update(this.value.map(i => i.id === id ? { ...i, qty } : i));
    },
    removeItem(id: string) {
      this.update(this.value.filter(i => i.id !== id));
    },
  },
});

cart.addItem({ id: "a", price: 10, qty: 1 });
cart.setQty("a", 3);
cart.removeItem("a");

Getter actions (computed properties)

Use ES5 property descriptors (get keyword inside the actions object). These are installed as real getters on the atom instance:

const cart = createAtom({
  key: "cart2",
  default: [] as CartItem[],
  actions: {
    get total() {
      return this.value.reduce((sum, i) => sum + i.price * i.qty, 0);
    },
  },
});

cart.total;   // number — no () needed

atomCollection — arrays with built-in mutation verbs

Use atomCollection instead of createAtom when the value is an array. It pre-installs all common mutation helpers:

import { atomCollection } from "@mongez/atom";

type Todo = { id: number; text: string; done: boolean };

const todos = atomCollection<Todo>({ key: "todos" /* default: [] */ });

todos.push({ id: 1, text: "Buy bread", done: false });
todos.unshift({ id: 0, text: "Wake up", done: true });
todos.pop();                            // removes last
todos.shift();                          // removes first
todos.remove(t => t.done);             // by predicate
todos.remove(2);                        // by index
todos.removeItem(someRef);              // by reference equality
todos.removeAll(someRef);               // all occurrences
todos.replace(0, { id: 0, text: "Wake up EARLY", done: true });
todos.map(t => ({ ...t, done: true })); // maps + updates + triggers event
todos.get(0);                           // get by index
todos.get(t => t.id === 1);            // get by predicate
todos.index(t => t.id === 1);          // findIndex
todos.forEach(t => console.log(t));    // read-only iteration
todos.length;                           // number
todos.value;                            // Todo[]

You can still add custom actions alongside the built-in ones:

const todos2 = atomCollection<Todo>({
  key: "todos2",
  actions: {
    markAllDone() {
      this.update(this.value.map(t => ({ ...t, done: true })));
    },
  },
});

Subscriptions

const counter = createAtom({ key: "c", default: 0 });

// onChange — fires on every update
const sub = counter.onChange((next, prev, atom) => {
  console.log(next, prev);
});
sub.unsubscribe();

// onReset — fires when reset() or silentReset() is called
counter.onReset(atom => console.log("reset"));

// onDestroy — fires when destroy() is called
counter.onDestroy(atom => console.log("destroyed"));

beforeUpdate hook

Intercept and transform (or reject) every incoming value before it is stored:

const boundedAngle = createAtom({
  key: "angle",
  default: 0,
  beforeUpdate(next, prev, atom) {
    return ((next % 360) + 360) % 360;  // clamp to [0, 360)
  },
});

boundedAngle.update(450);
boundedAngle.value;   // 90

Return undefined (or nothing) to let the original value through unchanged.

Clone and destroy

const a = createAtom({ key: "original", default: 42 });

const b = a.clone();          // key: "original.clone.1"; registered globally
const c = a.clone({ register: false }); // isolated clone, not in registry

a.destroy();  // removes from registry, triggers delete event, unsubscribes all listeners

Key pitfalls

• default must be a complete value — no Partial<V> defaults. AtomOptions.default: V, not Partial<V>.
• update() short-circuits when newValue === currentValue (strict reference equality). Always pass a new object/array reference for object atoms. merge() and change() do this for you.
• silentUpdate still runs beforeUpdate — it only suppresses the update event emission.
• reset() triggers both an update event (with the default value) and a reset event. silentReset() only triggers the reset event.
• Actions are bound to the atom with .bind(atom) at creation time. Arrow functions in actions also work but this will be undefined — use regular functions so this resolves correctly.
• atomCollection.map() mutates and updates the atom. It is not a read-only .map(). Use todos.value.map(...) if you only want to read.