Reference

Collections

The API and behaviour of the List, Dictionary, NameValuePair and LinkedList structures that come with @motifx/core.

The core exports three small collection classes. They are not reactive; for a reactive list use reactive([]) (Reactivity). For querying, see Collection Queries.

List<T>

An array wrapper that gives add/remove events and does membership checks backed by a Set.

In the example, the list keeps the ids of the open notes:

import { List } from "@motifx/core";

const open = new List<number>();
open.ItemAdded = (id) => console.log("opened", id);
open.Add(3);              // 0 — the index of the added item
open.AddBefore(1);        // adds at the front
open.Insert(1, 2);        // inserts at the index
open.has(3);              // true
open.item(0);             // 1
open.count;               // 3
open.items;               // the inner array (not a copy)
import { List } from "@motifx/core";

const open = new List();
open.ItemAdded = (id) => console.log("opened", id);
open.Add(3);              // 0 — the index of the added item
open.AddBefore(1);        // adds at the front
open.Insert(1, 2);        // inserts at the index
open.has(3);              // true
open.item(0);             // 1
open.count;               // 3
open.items;               // the inner array (not a copy)
Member Description
Add(item) Appends at the end and returns the index; ItemAdded(item) is called.
AddBefore(item) Adds at the front; ItemAddedBefore(item) is called. The return value is newLength − 1 (not the index of the added item).
Insert(index, item) Inserts at the given index; ItemSplice(index, item) is called. Returns the empty array that splice returns.
remove(item) Removes the item and returns the removed item as a one-element array; if the item is not in the list, it does nothing and returns an empty array.
removeIndex(index) Removes the item at the index; returns the removed items as an array.
clear() Removes everything; returns the new, empty inner array.
has(item) / indexOf(item) / item(index) Membership (Set, O(1)) / index / the item at an index.
FindFromKey(key, value) The items where item[key] === value.
forEach(fn) / filter(fn) The array counterparts; filter returns a new array.
ReverseClone() Returns a reversed copy of the items; the list's order does not change.
items / count The inner array / the length.
Dispose() Empties the inner array (the Set is kept).
ItemAdded, ItemAddedBefore, ItemSplice Assignable callbacks; called after the corresponding addition.

Removals give no events. items gives the inner array; if it is changed from outside, it gets out of step with has.

Dictionary<K, V> and NameValuePair<K, V>

A key-value dictionary that keeps NameValuePair pairs in a List. Keys are compared with ==, and lookup is linear.

In the example, the dictionary keeps unsaved drafts by note id:

import { Dictionary } from "@motifx/core";

const drafts = new Dictionary<number, string>();
drafts.OnItemAdded = (id, text) => console.log(id, text.length);
drafts.Add(3, "Milk, bread");
drafts.has(3);              // true
drafts.item(3);             // NameValuePair { Key: 3, value: "Milk, bread" }
drafts.item(3)?.value;      // "Milk, bread"
drafts.remove(3);
import { Dictionary } from "@motifx/core";

const drafts = new Dictionary();
drafts.OnItemAdded = (id, text) => console.log(id, text.length);
drafts.Add(3, "Milk, bread");
drafts.has(3);              // true
drafts.item(3);             // NameValuePair { Key: 3, value: "Milk, bread" }
drafts.item(3)?.value;      // "Milk, bread"
drafts.remove(3);
Member Description
Add(key, value) Adds a pair (the same key can repeat; there is no check), returns the index from List.Add; OnItemAdded(key, value) is called.
has(key) Whether the key exists (==).
item(key) The first matching NameValuePair, or undefined.
remove(key) Removes all pairs whose key matches.
removeIndex(index) Removes the pair at the index (zero-based); returns the removed pairs as an array.
clear() Removes everything.
forEach(fn) / filter(fn) / find(fn) Walking, filtering and finding over the NameValuePairs.
values The underlying List<NameValuePair<K, V>>.
OnItemAdded An assignable callback.

NameValuePair<K, V> is a plain class with two fields: Key (capital K) and value.

LinkedList<T>

A doubly linked, circular list. The add operations return a function that cuts the link; it is designed for "add, then remove with the handle in hand" patterns such as listener lists.

In the example, the list keeps cleanup functions to be run later:

import { LinkedList } from "@motifx/core";

const cleanups = new LinkedList<() => void>();
const unlinkTimer = cleanups.push(() => clearInterval(timer));                       // to the end
const unlinkKeys = cleanups.unshift(() => document.removeEventListener("keydown", onKey)); // to the front
for (const run of cleanups) run();   // the keyboard listener first, then the timer
unlinkTimer();                       // removes the timer; a second call does nothing
cleanups.size;                       // 1
import { LinkedList } from "@motifx/core";

const cleanups = new LinkedList();
const unlinkTimer = cleanups.push(() => clearInterval(timer));                       // to the end
const unlinkKeys = cleanups.unshift(() => document.removeEventListener("keydown", onKey)); // to the front
for (const run of cleanups) run();   // the keyboard listener first, then the timer
unlinkTimer();                       // removes the timer; a second call does nothing
cleanups.size;                       // 1
Member Description
push(value) / unshift(value) Adds at the end / at the front; returns a function that removes that node (calling it again does nothing).
pop() / shift() Removes from the end / from the front and returns the value; undefined if empty.
clear() Removes everything; removal functions obtained earlier stop having any effect.
size / isEmpty() The number of elements / whether it is empty.
[Symbol.iterator] Walks from start to end (for…of, spreading). Removing while walking is safe; an added item may be seen in that same walk.

There is no index access; if you need access by index, use List or a plain array.

See also

API Reference, Collection Queries.

Next step

For a container that places and swaps a single piece of dynamic content, go on to Frame.