mongez-atom-collections

name

mongez-atom-collections

description

How to use `atomCollection` to manage array-typed atoms with built-in mutation verbs like `push`, `pop`, `remove`, `map`, and `replace`. TRIGGER when: code imports or calls `atomCollection`, or invokes `push`, `unshift`, `pop`, `shift`, `replace`, `remove`, `removeItem`, `removeAll`, `map`, `forEach`, `index`, `get(indexOrPredicate)`, `length` on an atom, or uses `AtomCollectionActions` / `CollectionOptions` types; user asks "how do I manage an array as atom state", "how do I push/pop/remove items in an atom", or "what's the difference between createAtom and atomCollection"; `import { atomCollection } from "@mongez/atom"`. SKIP: scalar/object atoms (use `mongez-atom-atoms` or `mongez-atom-defining-atoms`); computed array views over collections (use `mongez-atom-derived` / `mongez-atom-derived-atoms`); React-list rendering hooks (live in `@mongez/react-atom`).

Atom Collections

atomCollection<T>(options) is a thin layer over createAtom that ships array-mutation verbs as actions.

Signature

atomCollection<Value>(options: CollectionOptions<Value>): Atom<Value[], AtomCollectionActions<Value>>

type CollectionOptions<V> = Omit<AtomOptions<V[], AtomCollectionActions<V>>, "default"> & {
  default?: V[];   // defaults to []
};

Actions

Action	Description
push(...items)	Append.
unshift(...items)	Prepend.
pop() / shift()	Drop last / first.
replace(index, item)	Overwrite at index.
remove(indexOrPredicate)	Drop one by index or (item, index, array) => boolean.
removeItem(item)	Strict-equality remove of the first occurrence.
removeAll(item)	Remove every occurrence of item (strict equality). Mutates and triggers update.
map(cb)	In-place map: rewrites the value AND returns the new array.
forEach(cb)	Read-only iteration.
index(predicate)	findIndex wrapper.
get(indexOrPredicate)	Single-element read.
length	Property getter — current size.

Example

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

const todos = atomCollection<Todo>({
  key: "todos",
  default: [],
  actions: {
    toggle(this: Atom<Todo[]>, id: number) {
      this.update(this.value.map(t => t.id === id ? { ...t, done: !t.done } : t));
    },
  },
});

todos.push({ id: 1, text: "Buy bread", done: false });
todos.toggle(1);
todos.remove((t) => t.done);

Gotchas

• map is mutating despite the name — it rewrites the value AND returns the new array. Use atom.value.map(...) if you want a pure transform.
• The length action is exposed as a property getter, not a function. Read it as todos.length, not todos.length().