hassanzohdy/atom/atoms

createAtom<Value, Actions>(options: AtomOptions<Value, Actions>): Atom<Value, Actions>

type AtomOptions<V, A> = {
  key: string;
  default: V;
  actions?: A & ThisType<Atom<V, A>>;
  beforeUpdate?: (next: V, prev: V, atom: Atom<V, A>) => V | void;
  onUpdate?: (callback: AtomChangeCallback<V, A>) => EventSubscription;
  get?: (key: string, defaultValue?: V, atomValue?: V) => V;
  persist?: PersistOption<V>;
  persistHydration?: "immediate" | "deferred";  // when the stored value is read; default "immediate"
  register?: boolean;                          // false = local atom, kept out of the global registry
};

const counter = createAtom({
  key: "counter",
  default: 0,
  actions: {
    increment() { this.update(this.value + 1); },
    decrement() { this.update(this.value - 1); },
    addTen()    { this.update(prev => prev + 10); },
  },
});
counter.increment();
counter.value; // 1

const user = createAtom({
  key: "auth.user",
  default: { name: "Anon", lastSeen: 0 },
});
user.watch("name", (next, prev) => console.log(`Name: ${prev} → ${next}`));
user.merge({ name: "Alice" });
// "Name: Anon → Alice"

const port = createAtom({
  key: "config.port",
  default: 3000,
  beforeUpdate(next) {
    if (next < 1 || next > 65535) return; // void = keep next
    return Math.floor(next);
  },
});
port.update(8443.7);  // value becomes 8443
port.update(999999);  // ignored, stays 8443

getAtom("auth.user");           // Atom | undefined
atomsList();                    // Atom[]
atomsObject();                  // Record<string, Atom>