API Referenceclass

class ObservableList

A data structure that contains an ordered set of observable objects.

class ObservableList<
  T extends ObservableObject = ObservableObject,
> extends ObservableObject;

Description

Lists of observable objects — instances of ObservableObject — can be represented using regular arrays. However, often a ‘list of objects’ needs to be more restrictive, especially in the context of a UI framework. An observable list is useful in the following cases:

• The list should only contain instances of a certain type, or at least only ObservableObject instances.
• The list shouldn’t contain any duplicates, gaps, or undefined values.
• The list should be observable: actions can be taken when items are added, removed, or reordered.
• Events from (attached) list items should be ‘propagated’ on the list, to avoid having to add event listeners for all items — see ObservableEvent.
• List items should be able to bind to the object containing the (attached) list — see Binding.

Observable lists are used in many places throughout the framework, such as to reference view objects within a UIContainer object. Observable lists can also be used by application code to efficiently represent lists of data models or other records.

Attaching list items — By default, objects aren’t attached to the list, so they could be attached to other objects themselves and still be part of an observable list. However, you can enable automatic attachment of objects in a list using the ObservableList.attachItems() method. This ensures that objects in a list are only attached to the list itself, and are unlinked when they’re removed from the list (and removed from the list when they’re no longer attached to it, e.g. when moved to another auto-attaching list).

Events — Since ObservableList itself inherits from ObservableObject, a list can emit events, too. When any objects are added, moved, or removed, a change event is emitted. The event names are either Change, Add, or Remove, with objects referenced by added or removed event data properties if possible. In addition, for auto-attaching lists (see ObservableList.attachItems()) any events that are emitted by an object are re-emitted on the list itself. The ObservableEvent.source property can be used to find the object that originally emitted the event.

Nested lists — Observable lists can contain (and even attach to) other observable lists, which allows for building nested or recursive data structures that fully support bindings and events.

Examples

// Create a list, add and remove objects
let a = Object.assign(new ObservableObject(), { foo: "a" })
let b = Object.assign(new ObservableObject(), { foo: "b" })
let list = new ObservableList(a, b);

let c = Object.assign(new ObservableObject(), { foo: "c" })
list.add(c);
list.length // => 3

list.remove(b);
list.length // => 2

let a = list.map(record => record.foo);
a // => ["a", "c"]

// Lists can be iterated using for...of, too
for (let item of list) {
  // ...do something for each item
}

Constructor

• new ObservableList()
  Creates a new observable list containing the provided objects.

Instance members

• length
  The number of objects in the list.
• [Symbol.iterator]
  Iterator symbol, alias of objects() method.
• beforeUnlink()
  Unlink handler, clears the list when unlinked.
• objects()
  Returns an iterable iterator for this list.
• add()
  Adds the provided objects to the end of the list.
• insert()
  Inserts the provided object into the list, before the specified reference object.
• remove()
  Removes the specified object from the list.
• replaceAt()
  Removes the specified object and following objects, and inserts the provided objects in their place.
• replace()
  Replaces the specified item with another object in-place.
• replaceAll()
  Replaces (or moves) all items in this list with the specified items.
• clear()
  Removes all items from the list.
• reverse()
  Reverses all items in the list.
• sort()
  Sorts the list using the provided callback.
• first()
  Returns the first object in the list.
• last()
  Returns the last object in the list.
• get()
  Returns the object that’s at the specified position in the list.
• take()
  Returns a number of objects from the list.
• takeLast()
  Returns a number of objects from the list.
• indexOf()
  Returns the index position (0-based) of the specified object in this list.
• includes()
  Returns true if this list contains the specified object.
• find()
  Returns the first object in the list for which the provided callback returns true.
• some()
  Returns true if the provided callback returns true for at least one object in the list.
• every()
  Returns true if the provided callback returns true for all objects in the list.
• forEach()
  Calls the provided callback for each object in the list.
• map()
  Returns an array of return values of the provided callback for all objects in the list.
• filter()
  Returns an array of objects for which the provided callback function returns true.
• toArray()
  Returns an array that contains all objects in the list.
• toJSON()
  Returns an array that contains all objects in the list.
• restrict()
  Restricts the type of objects that can be added to this list.
• attachItems()
  Enable (or disable) automatic attachment of new objects to the list itself.

Inherited members

• emit()
  Emits an event, immediately calling all event handlers.
• emitChange()
  Emits a change event.
• listen()
  Adds a handler for all events emitted by this object.
• listenOnce()
  Returns a promise for a single event with the provided name.
• listenAsync()
  Adds a handler for all events emitted by this object, and returns an async iterable.
• observe()
  Observes a property, a bound property from an attached parent, or an observable object.
• observeAsync()
  Observes one or more targets asynchronously, batching or debouncing/throttling updates.
• attach() protected
  Attaches the specified observable object to this object.
• isUnlinked()
  Returns true if the object has been unlinked.
• unlink()
  Unlinks this observable object.