Heroic Lands

Class SohlArray<T>

A tracked array that participates in the SoHL data lifecycle.

SohlArray<T> is an extension of the native Array<T> that supports automatic tracking of parent context and persistence. It is used to hold ordered collections of objects such as Effects or Logic items.

Remarks

The array tracks its parent context (SohlBeing or SohlLogic) and notifies it when changes occur. All iterator methods return an Itr<T> object for functional utilities.

WARNING

Do not assign directly to an index (e.g., arr[0] = value). Instead, use setAt(index, value) to ensure proper lifecycle tracking.

Example

const arr = new SohlArray<ValueModifier>();
arr.push(new ValueModifier());
for (const val of arr) {
  console.log(val);
}

Type Parameters

  • T

Constructors

constructor

Accessors

length

Methods

[iterator] at entries expandingEntries keys map pop push reduce setAt shift splice unshift values

Constructors

constructor

Accessors

length

  • get length(): number

  • The number of elements in the array.

    Reflects the total count of elements in the array. This is a read-only property.

    Returns number

    Example

    console.log(myArray.length); // e.g., 5

Methods

[iterator]

  • "[iterator]"(): Itr<T>

  • The default iterator for SohlArray.

    Allows the array to be iterated using for...of, spreading, or other iterable utilities. Equivalent to .values().

    Returns Itr<T>

    An iterable iterator over the array's elements.

    Example

    for (const item of myArray) {
      console.log(item);
    }

at

  • at(index: number): undefined | T

  • Returns the element at the specified index.

    Allows access to an element by index, including support for negative indices to count from the end.

    Parameters

    • index: number

      The index of the element to retrieve. If negative, counts from the end of the array.

    Returns undefined | T

    The element at the specified index, or undefined if out of bounds.

    Example

    const last = myArray.at(-1); // Gets the last element

entries

  • entries(): Itr<[number, T]>

  • Returns an iterator over key-value pairs [index, element].

    Each iteration yields a tuple containing the index and the corresponding element.

    Returns Itr<[number, T]>

    An iterable iterator of [index, value] pairs.

    Example

    for (const [index, value] of myArray.entries()) {
      console.log(index, value);
    }

expandingEntries

  • expandingEntries(): Itr<[number, T]>

  • Iterates entries while allowing dynamic expansion.

    Provides a breadth-first iterator over all entries in the collection, including new items added during the iteration itself. This allows your logic to traverse all known items and process new ones as they are introduced dynamically.

    Unlike standard .entries() iteration, which operates over a fixed snapshot of the data, expandingEntries() reflects live state. As entries are added, they are queued and subsequently included in the iteration.

    Returns Itr<[number, T]>

    The mutating iterator.

    Remarks

    • This method guarantees that every element currently in the collection or added while iterating will be visited once.
    • The order is breadth-first, preserving logical consistency when traversal depends on the state of prior elements.

    Example

    const arr = new SohlArray<number>(1, 2);

    for (const [i, v] of arr.expandingEntries()) {
      if (v === 2) arr.push(3); // 3 will be included in this same loop
    }

keys

  • keys(): Itr<number>

  • Returns an iterator over the array's keys (indices).

    Yields the numeric indices of each item in the array.

    Returns Itr<number>

    An iterable iterator over the array's indices.

    Example

    for (const index of myArray.keys()) {
      console.log(index);
    }

map

  • map<U>(fn: (item: T, index: number, array: T[]) => U): U[]

  • Creates a new array with the results of calling a function on each element.

    Returns a new array containing the results of applying the callback function to each element. Does not modify the original array.

    Type Parameters

    • U

    Parameters

    • fn: (item: T, index: number, array: T[]) => U

      A function that produces an element of the new array, taking the current item, index, and array.

    Returns U[]

    A new array with transformed elements.

    Example

    const squared = myArray.map(n => n * n);

pop

  • pop(): undefined | T

  • Removes the last element from the array and returns it.

    If the array is empty, returns undefined. The length of the array is decreased by one.

    Returns undefined | T

    The removed element, or undefined if the array was empty.

    Example

    const last = myArray.pop();

push

  • push(...items: T[]): number

  • Adds one or more elements to the end of the array.

    Extends the array by appending new elements. Returns the new length of the array.

    Parameters

    • ...items: T[]

      One or more elements to add to the array.

    Returns number

    The new length of the array.

    Example

    myArray.push("newItem");

reduce

  • reduce<U>(fn: (acc: U, curr: T, index: number, array: T[]) => U, initial: U): U

  • Applies a function against an accumulator and each element to reduce to a single value.

    The callback is applied sequentially to each element of the array and the accumulated result is returned.

    Type Parameters

    • U

    Parameters

    • fn: (acc: U, curr: T, index: number, array: T[]) => U

      A reducer function taking accumulator, current value, index, and array.

    • initial: U

      The initial value to start accumulation.

    Returns U

    The final accumulated value.

    Example

    const sum = myArray.reduce((total, n) => total + n, 0);

setAt

  • setAt(index: number, value: T): void

  • Safely assign a value at the specified index with lifecycle tracking.

    This method replaces the element at the given index and ensures the change is properly tracked for persistence and lifecycle propagation. It integrates with the SoHL system by linking the new value to its parent context and notifying the parent of the update.

    IMPORTANT

    This method should always be used instead of direct assignment (array[index] = value). Direct assignment bypasses lifecycle and persistence hooks, resulting in data that may not be saved or correctly initialized.

    Parameters

    • index: number

      The index in the array to replace.

    • value: T

      The new value to assign to the index.

    Returns void

    Remarks

    • If the value supports tracking, setTracking() is called automatically.
    • Triggers markChanged(index) to notify the parent that this slot has been updated.
    • Maintains internal consistency and enables serialization, rollback, and syncing behavior.

    Throws

    If index exceeds the current array length.

    Example

    const arr = new SohlArray<ValueModifier>();
    arr.setTracking(myLogic, "modifiers");

    // Correct usage — tracked and persisted
    arr.setAt(0, new ValueModifier());

    // Avoid — this bypasses SoHL lifecycle logic
    arr[0] = new ValueModifier();

shift

  • shift(): undefined | T

  • Removes and returns the first element of the array.

    Shifts all remaining elements one position to the left and returns the removed value. If the array is empty, returns undefined.

    Returns undefined | T

    The removed first element, or undefined if the array was empty.

    Example

    const first = myArray.shift();
    console.log(first); // Logs the removed first element

splice

  • splice(start: number, deleteCount?: number, ...items: T[]): T[]

  • Changes the contents of the array by removing or replacing existing elements.

    Removes elements starting at the given index and optionally inserts new elements. Returns an array of the removed elements.

    Parameters

    • start: number

      Index at which to start changing the array.

    • OptionaldeleteCount: number

      Number of elements to remove.

    • ...items: T[]

      Optional items to insert in place of the removed elements.

    Returns T[]

    An array containing the removed elements.

    Example

    myArray.splice(1, 2, "a", "b");

unshift

  • unshift(...items: T[]): number

  • Adds one or more elements to the beginning of the array.

    Inserts the specified elements at the start of the array, shifting existing elements to the right. Returns the new length of the array.

    Parameters

    • ...items: T[]

      One or more elements to add to the beginning of the array.

    Returns number

    The new length of the array after the elements are added.

    Example

    myArray.unshift("a", "b");
    console.log(myArray); // ['a', 'b', ...originalElements]

values

  • values(): Itr<T>

  • Returns an iterator over the array's values.

    Yields each element of the array in numeric index order. Equivalent to the default iterator and Symbol.iterator.

    Returns Itr<T>

    An iterable iterator over the array's elements.

    Example

    for (const value of myArray.values()) {
      console.log(value);
    }

Settings

Member Visibility

On This Page

WARNING
Constructors
Accessors
Methods