Lists, stacks, maps

atom.list, advancedList, stack, queue, Map, and Set — collection-shaped reactive state.

import { atom, createList, advancedList } from 'mates';

// Keyed object list — unique readonly id (or custom keyName)
const todos = atom.list([{ name: 'Ship' }]);
todos.add({ name: 'Docs' });
todos.updateItem(/* key or index */, (row) => { row.name = 'Shipped'; });
// todos.set / todos.update throw — use setList / updateItem

// Primitives → keyed rows via createList
atom.list(createList(['a', 'b']));

// Search / filter / sort / page controller
const al = advancedList(users, { pageSize: 10, searchKeys: ['name'] });
al.searchInput.set('ada');

const stack = atom.stack<number>();
stack.push(1); stack.pop();

const q = atom.queue<string>();
q.enqueue('a'); q.dequeue();

const scores = atom.Map([['ada', 10]]);
scores.set('grace', 12);

const tags = atom.Set(['ts']);
tags.add('js');

Overview

Collection factories sit on the atom namespace: atom.list, atom.advancedList, atom.stack, atom.queue, atom.Map, and atom.Set (capitalized to avoid clashing with instance .set / .map).

atom.list is for ordered UI rows with unique readonly keys (default id). Raw .set/.update throw — use setList, add, updateItem, etc. Primitives must go through createList first.

advancedList wraps a list with search, filters, sort, and pagination (static local pipeline or remote load). Map/Set are reactive wrappers around the native collections.

Which collection?

API	Shape	Prefer when
`atom.array`	T[]	General arrays — see typed factories.
`atom.list`	Keyed rows	Dynamic UI lists needing stable unique ids.
`advancedList`	Controller	Search / filter / sort / page (or remote load).
`atom.stack` / `.queue`	LIFO / FIFO	Undo stacks, job queues.
`atom.Map` / `.Set`	Native Map/Set	Keyed bags / unique membership with reactive reads.

atom.list — keyed rows

Unique readonly id stamped on add. updateItem mutates a row; delete by key.

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

const App = () => {

const todos = atom.list([

{ name: 'Write docs', done: false },

{ name: 'Ship', done: false },

]);

return () => html`

${todos.render((row) => html`

<label>

<input type="checkbox" .checked=${row.done}

@change=${() => todos.updateItem(row.id, (r) => { r.done = !r.done; })} />

${row.name}

</label>

<button class="btn-ghost" @click=${() => todos.delete(row.id)}>×</button>

</li>

`)}

</ul>

<button class="btn-primary" @click=${() => todos.add({ name: 'New', done: false })}>

add

</button>

<button @click=${() => todos.clear()}>clear</button>

</div>

<p class="muted m-t-5">size=${todos.size} · keyName=${todos.keyName}</p>

</div>

};

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

stack + queue

LIFO push/pop vs FIFO enqueue/dequeue.

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

const App = () => {

const stack = atom.stack(['a', 'b']);

const queue = atom.queue(['x', 'y']);

return () => html`

<span class="overline">stack (LIFO)</span>

<span class="card-title">[${stack.toArray().join(', ')}]</span>

</div>

<span class="overline">queue (FIFO)</span>

<span class="card-title">[${queue.toArray().join(', ')}]</span>

</div>

<button class="btn-primary" @click=${() => stack.push(String(stack.size + 1))}>push</button>

<button @click=${() => stack.pop()}>pop</button>

<button class="btn-primary" @click=${() => queue.enqueue(String(queue.size + 1))}>enqueue</button>

<button @click=${() => queue.dequeue()}>dequeue</button>

</div>

};

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

Map + Set

Native-shaped reactive collections. Reads (size, iteration, get/has) track.

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

const App = () => {

const scores = atom.Map([['Ada', 10], ['Grace', 8]]);

const tags = atom.Set(['docs', 'state']);

return () => html`

Map: ${[...scores.entries()].map(([k, v]) => k + '=' + v).join(', ')}

</p>

scores.set('Ada', (scores.get('Ada') ?? 0) + 1)

}>Ada +1</button>

<button @click=${() => tags.delete('docs')}>delete docs</button>

</div>

<p class="muted m-t-5">map.size=${scores.size} · set.size=${tags.size}</p>

</div>

};

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

API — Collections

import { atom, createList, ensureListItemKey, advancedList } from 'mates'

Prop / Option	Type	Default	Description
`atom.list(initial?, keyName?)`	`ListAtomType`	—	Keyed object list. Default keyName "id". Alias createListAtom.
`createList(items?, keyName?)`	`ListRow[]`	—	Build keyed rows from primitives or objects before atom.list.
`ensureListItemKey(item, keyName?)`	`ListRow`	—	Stamp one row’s key readonly.
`atom.advancedList(initial?, options?)`	`AdvancedListController`	—	Search/filter/sort/page controller. Alias advancedList().
`atom.stack(initial?)`	`StackAtomType`	—	LIFO stack. Alias createStackAtom.
`atom.queue(initial?)`	`QueueAtomType`	—	FIFO queue. Alias createQueueAtom.
`atom.Map(entries?, config?)`	`MapAtomType`	—	Reactive Map. Alias mapAtom. Capital M.
`atom.Set(values?, config?)`	`SetAtomType`	—	Reactive Set. Alias setAtom. Capital S.

ListAtomType

Prop / Option	Type	Default	Description
`.keyName`	`K`	—	Property used as stable key.
`.setList(value \| updater, silently?)`	`void`	—	Replace list; stamps missing keys; throws on duplicate keys. Raw set/update throw.
`.add(item)`	`string`	—	Append; returns key; throws on duplicate.
`.delete(keyOrIndex)`	`ListAtomType`	—	Remove by key or index.
`.getItem / .has`	`row \| boolean`	—	Lookup (first match); no notify.
`.move / .updateItem / .updateAll`	`ListAtomType`	—	Reorder / mutate rows (key field stays readonly).
`.deleteItems / .clear / .sort / .sortAndSet / .forEach / .render`	`varies`	—	Bulk ops + lit-html render (default key = keyName).
`.size / .toJSON()`	`number / string`	—	Length and JSON stringify.

AdvancedListOptions / controller

Prop / Option	Type	Default	Description
`options.pageSize / searchDelay / paginationStyle`	`number / ms / 'page'\|'lazy'`	`20 / 300 / 'page'`	Paging and search debounce.
`options.searchKeys / filterFn / sortFn / load`	`hooks`	—	Static pipeline fields, or remote load(ctx) => T[].
`al.list / al.source / al.searchInput / al.search`	`atoms`	—	Visible rows, full source, immediate vs debounced query.
`al.filters / al.sort / al.page / al.pageSize`	`atoms`	—	Controls. page is paginationAtom (1-based).
`al.total / al.hasMore / al.loading / al.error`	`atoms`	—	Status atoms (dynamic mode uses loading/error).
`al.load / al.reload / al.getSignal / al.dispose`	`fns`	—	Manual fetch, AbortSignal, cleanup.

StackAtomType / QueueAtomType

Prop / Option	Type	Default	Description
`stack.push / .pop / .peek / .top / .clear / .toArray`	`LIFO`	—	peek/top are synonyms; size / isEmpty accessors.
`queue.enqueue / .dequeue / .offer / .poll / .peek / .front`	`FIFO`	—	offer≈enqueue, poll≈dequeue, peek≈front; size / isEmpty / clear / toArray.

MapAtomType / SetAtomType

Prop / Option	Type	Default	Description
`Map: set / delete / clear + native reads`	`Map`	—	Mutations notify; get/has/size/iteration track dependencies.
`map.update(fn) / map.updateItem(key, fn)`	`MapAtomType`	—	Batch in-place map mutation; mutate object value at key.
`Set: add / delete / clear + native reads`	`Set`	—	Mutations notify; has/size/iteration track.
`set.update(fn) / set.updateItem(item, fn)`	`SetAtomType`	—	Batch mutation; mutate object item by reference.
`.__isAtom___ / .__version__`	`meta`	—	Underlying atom handle / version (non-enumerable).