Collection.Array
A reactive, ordered list of values. Collection.Array is its
own type: a sequence of
{ key, value } elements, where every element carries a
unique, stable key. That key makes reactivity reliable. When the list changes, a view built with
Collection.Array.Each stays bound to the right element
across inserts, removals and reorders, because it follows the key rather than the position. You work in
terms of values; the keys are assigned and tracked for you. The operations are pure:
Append, Remove and the rest return a new array and leave the
original untouched.
Contents
Types
Functions
- Collection.Array.Append
- Collection.Array.At
- Collection.Array.Contains
- Collection.Array.Each
- Collection.Array.First
- Collection.Array.From
- Collection.Array.IndexOf
- Collection.Array.Insert
- Collection.Array.IsEmpty
- Collection.Array.IsNotEmpty
- Collection.Array.Last
- Collection.Array.Length
- Collection.Array.Map
- Collection.Array.Push
- Collection.Array.Remove
- Collection.Array.Swap
- Collection.Array.Take
- Collection.Array.ToString
- Collection.Array.Zero
Types
Collection.Array.Element
One entry in a Collection.Array: a value paired with a unique key that gives it a stable identity.
Fields
| Field | Type | Description |
|---|---|---|
key | string | A unique, stable key. Assigned when the element is added and kept for its lifetime; Each uses it to keep a view bound to this element across inserts, removals and reorders. |
value | any | The element's value: what you read, map and render. |
Example
// A Collection.Array is a sequence of { key, value } elements:
// [ { key, value: "red" }, { key, value: "green" }, { key, value: "blue" } ]
const colours = Collection.Array.From("red", "green", "blue");Functions
Collection.Array.Append
A new array with a new element, holding the value, added to the end.
Parameters
| Name | Type | Description |
|---|---|---|
array | Array | The source array. |
value | any | The value to add; it is given a fresh unique key. |
Returns
A new reactive Array; existing elements keep their keys, and the original is left unchanged.
Example
const colours = Collection.Array.From("red", "green");
const more = Collection.Array.Append(colours, "blue");Collection.Array.At
The element at an index, or a fallback when out of range.
Parameters
| Name | Type | Description |
|---|---|---|
array | Array | The array to read. |
index | number | Zero-based position. |
fallback | any | Returned when the index is out of range. |
Returns
A reactive value: the element, or fallback.
Example
const colours = Collection.Array.From("red", "green", "blue");
const second = Collection.Array.At(colours, 1, "none");Collection.Array.Contains
True when the array holds an element equal to the value.
Parameters
| Name | Type | Description |
|---|---|---|
array | Array | The array to search. |
value | any | The value to look for. |
Returns
A reactive boolean.
Example
const colours = Collection.Array.From("red", "green", "blue");
const hasGreen = Collection.Array.Contains(colours, "green");Collection.Array.Each
Runs a block once for each element, in order. The reactive way to render a list.
Parameters
| Name | Type | Description |
|---|---|---|
array | Array | The array to iterate. |
itemCallback | function | Called with each element's value; build DOM for the element here. |
Example
const colours = Collection.Array.From("red", "green", "blue");
Collection.Array.Each(colours, (colour) => {
Reactive.Dom.text(colour);
});Collection.Array.First
The first element, or a fallback when the array is empty.
Parameters
| Name | Type | Description |
|---|---|---|
array | Array | The array to read. |
fallback | any | Returned when the array is empty. |
Returns
A reactive value: the first element, or fallback.
Example
const colours = Collection.Array.From("red", "green", "blue");
const head = Collection.Array.First(colours, "none");Collection.Array.From
Builds a reactive array from the given values, assigning each a fresh unique key.
Parameters
| Name | Type | Description |
|---|---|---|
...values | any | The values of the new array, in order. |
Returns
A reactive Array whose elements wrap the given values, each with a fresh key.
Example
const colours = Collection.Array.From("red", "green", "blue");Collection.Array.IndexOf
The index of the first element equal to the value, or -1.
Parameters
| Name | Type | Description |
|---|---|---|
array | Array | The array to search. |
value | any | The value to look for. |
Returns
A reactive number: the index, or -1 when the value is absent.
Example
const colours = Collection.Array.From("red", "green", "blue");
const i = Collection.Array.IndexOf(colours, "blue");Collection.Array.Insert
A new array with a new element inserted at an index, shifting later elements along.
Parameters
| Name | Type | Description |
|---|---|---|
array | Array | The source array. |
index | number | Where to insert. |
value | any | The value to insert; it is given a fresh unique key. |
Returns
A new reactive Array; the elements around the insertion keep their keys.
Example
const colours = Collection.Array.From("red", "blue");
const withGreen = Collection.Array.Insert(colours, 1, "green");Collection.Array.IsEmpty
True when the array is empty.
Parameters
| Name | Type | Description |
|---|---|---|
array | Array | The array to test. |
Returns
A reactive boolean.
Example
const todo = Reactive.State(Collection.Array.Zero);
const empty = Collection.Array.IsEmpty(todo);Collection.Array.IsNotEmpty
True when the array holds at least one element.
Parameters
| Name | Type | Description |
|---|---|---|
array | Array | The array to test. |
Returns
A reactive boolean.
Example
const todo = Collection.Array.From("write docs");
const hasItems = Collection.Array.IsNotEmpty(todo);Collection.Array.Last
The last element, or a fallback when the array is empty.
Parameters
| Name | Type | Description |
|---|---|---|
array | Array | The array to read. |
fallback | any | Returned when the array is empty. |
Returns
A reactive value: the last element, or fallback.
Example
const colours = Collection.Array.From("red", "green", "blue");
const tail = Collection.Array.Last(colours, "none");Collection.Array.Length
The number of elements in the array.
Parameters
| Name | Type | Description |
|---|---|---|
array | Array | The array to measure. |
Returns
A reactive number: the element count.
Example
const colours = Collection.Array.From("red", "green", "blue");
const count = Collection.Array.Length(colours);Collection.Array.Map
A new array holding the result of running a function on each element's value.
Parameters
| Name | Type | Description |
|---|---|---|
array | Array | The source array. |
transform | function | Called with each element's value; its result becomes the new value. |
Returns
A new reactive Array of the transformed values. Every element keeps its key, so a view built with Each re-renders only the values that changed and leaves the rest of the list in place.
Example
const nums = Collection.Array.From(1, 2, 3);
const doubled = Collection.Array.Map(nums, (n) => n * 2);Collection.Array.Push
Adds a value to the end. An alias for Append, phrased as a stack push.
Parameters
| Name | Type | Description |
|---|---|---|
array | Array | The source array. |
value | any | The value to push; it is given a fresh unique key. |
Returns
A new reactive Array with the value on the end.
Example
const stack = Collection.Array.From(1, 2);
const grown = Collection.Array.Push(stack, 3);Collection.Array.Remove
A new array with the element at an index, and its key, removed.
Parameters
| Name | Type | Description |
|---|---|---|
array | Array | The source array. |
index | number | The index to remove. |
Returns
A new reactive Array; the remaining elements keep their keys.
Example
const colours = Collection.Array.From("red", "green", "blue");
const fewer = Collection.Array.Remove(colours, 1);Collection.Array.Swap
A new array with the elements at two indices exchanged.
Parameters
| Name | Type | Description |
|---|---|---|
array | Array | The source array. |
i | number | First index. |
j | number | Second index. |
Returns
A new reactive Array. Each key travels with its value, so Each treats this as a reorder and moves the existing nodes.
Example
const colours = Collection.Array.From("red", "green", "blue");
const swapped = Collection.Array.Swap(colours, 0, 2);Collection.Array.Take
A new array of the first count elements.
Parameters
| Name | Type | Description |
|---|---|---|
array | Array | The source array. |
count | number | How many elements to keep. |
Returns
A new reactive Array.
Example
const colours = Collection.Array.From("red", "green", "blue");
const firstTwo = Collection.Array.Take(colours, 2);Collection.Array.ToString
A text rendering of the array, for debugging and logs.
Parameters
| Name | Type | Description |
|---|---|---|
array | Array | The array to render. |
Returns
A reactive string.
Example
const colours = Collection.Array.From("red", "green");
const text = Collection.Array.ToString(colours);Collection.Array.Zero
The empty array: a single shared reference holding zero elements.
Returns
An empty reactive Array. The same reference every time, so reusing it stays stable and skips a re-render.
Example
const items = Collection.Array.Zero;