ManagedList

Managed lists contain ordered sets of references to other managed objects.

Managed objects

This class is part of a group of managed object classes. Read more about Components for details.

See also

ManagedMap, ManagedObject, ManagedReference.

class ManagedList

extends ManagedObject

Represents a list of managed objects. The objects in the list are ordered and unique, ensuring that there are no gaps or repeated list items.

Child references

If a managed object property that is decorated with @managedChild gets assigned a ManagedList instance, the parent-child relationship will extend to the items in this ManagedList. In other words, the items in a ManagedList that is itself a managed child object, will become managed children of the list itself.

In this case, removing objects from the ManagedList object will destroy these objects. Adding objects to the ManagedList will ‘move’ them from their current parent, if any.

Example

The following example shows how events that are emitted on list items can be observed from a parent component.

class MyComponent extends Component {
  @managedChild
  myList = new ManagedList().propagateEvents();
}
MyComponent.observe(class {
  constructor (public readonly c: MyComponent) { }
  onMyListChange(e: ManagedEvent) {
    console.log(`Event: ${e.name}`);
    console.log(`Count: ${this.c.myList.count}`);
  }
})

let c = new MyComponent();
c.myList.add(new ManagedRecord());
c.myList.first().emit(CHANGE);

Constructor

<T extends ManagedObject = ManagedObject>(...objects: T[]): ManagedList<T>

.propagateEvents()

[1]. (f?: (this: this, e: ManagedEvent) => void | ManagedEvent | ManagedEvent[]): this
[2]. (...types: (ManagedEvent | (new (...args: any[]) => ManagedEvent))[]): this

[1] Propagate events from all objects in this list by emitting them on the list object itself, optionally restricted to given types of events or a filter function

[2] Propagate events from all objects in this list by emitting them on the list object itself, optionally restricted to given types of events or a filter function.

.restrict()

<T extends ManagedObject>(classType: ManagedObjectConstructor<T>): ManagedList<T>

Ensure that objects in the list are all instances of given class (or a sub class), and restrict newly added objects in the list to instances of given class. Given class must be a sub class of ManagedObject.

.count

number

The number of objects in this list.

.add()

(...targets: T[]): this

Add one or more objects (or managed lists or maps) to the end of this list.

.insert()

(target: T, before?: T): this

Insert an object (or managed list or map) into this list.

  • target — the object to be added to the list.

  • before — the object before which the target object should be inserted; if undefined, the object is appended to the end of the list.

.remove()

(target: T): this

Remove given object from this list.

Note: No error is thrown if the object was not included in the list at all.

.splice()

[1]. (target?: T, stop?: T, ...objects: T[]): T[]
[2]. (target?: T, removeCount?: number, ...objects: T[]): T[]

[1] Remove objects from given target until (but not including) second argument, and optionally insert given objects in their place. Returns the objects that were removed.

[2] Remove given object and following objects up to given number of objects, and optionally insert given objects in their place. Returns the objects that were removed.

Note: If stop is undefined, all objects after and including target are removed. If target is undefined, the objects are added to the back of the list.

.replace()

(objects: Iterable<T>): this

Replace the objects in this list with the objects in given array or other list, using a series of calls to remove() and insert() and/or reordering objects that are already in the list.

.clear()

(): this

Remove all objects from this list.

.includes()

(target: T): boolean

Returns true if given object is currently included in this list.

.first()

(): T

Returns the first object in the list, or undefined if the list is empty.

.last()

(): T

Returns the last object in the list, or undefined if the list is empty.

.get()

(index: number): T

Returns the object at given position in the list (0 based).

Note: This operation is very inefficient on longer lists, do not recurse over all the objects in a list using this method; see ManagedList.forEach instead, or use a for (let object of ...) statement.

.find()

(managedId: number): T

Returns the object with given ID (see ManagedObject.managedId).

.take()

(n: number, startingFrom?: T): T[]

Returns an array with given number of objects, counting from the start of the list or from the position of given object.

Returns an empty array if an object is specified but not found in the list.

  • n — the number of objects to include in the result.

  • startingFrom — the first object to be included in the result (optional).

.takeLast()

(n: number, endingAt?: T): T[]

Returns an array with given number of objects taken from the end of the list, or the same number of objects up to and including given object.

Returns an empty array if an object is specified but not found in the list.

  • n — the number of objects to include in the result.

  • endingAt — the last object to be included in the result (optional).

.indexOf()

(target: T): number

Returns the index of given object in this list (0 based), or -1 if the component is not included in the list at all.

.toArray()

(): T[]

Returns an array with all objects currently in this list.

.toJSON()

(): any

Returns an array representation of this list (alias of toArray method).

.some()

(callback: (target: T) => any): boolean

Returns true if given callback function returns a truthy value for at least one of the objects in this list.

.every()

(callback: (target: T) => any): boolean

Returns true if given callback function returns a truthy value for every object in this list (or if the list is empty).

.forEach()

(callback: (target: T) => void): void

Iterates over the objects in this list and invokes given callback for each object (alternative to for…of statement).

  • callback — the function to be called, with a single object as the only argument.

Note: The behavior of this method is undefined if objects are inserted immediately after the current object, or if objects beyond the current object are removed by the callback function. Removing the current object or any previous objects during the iteration is safe and will not disrupt the control flow.

.map()

<TResult>(callback: (target: T) => TResult): TResult[]

Iterates over the objects in this list and invokes given callback for each object, then returns an array with all callback return values.

  • callback — the function to be called, with a single object as the only argument.

Note: The behavior of this method is undefined if the list is changed by the callback function.

.pluck()

<K extends keyof T>(propertyName: K): T[K][]

Returns an array with the values of given property for all objects in the list.

.__@iterator()

(): Iterator<T>

Iterator symbol property to use managed list with ‘for…of’ statement.

Note: The behavior of the iterator is undefined if objects are inserted immediately after the current object, or if objects beyond the current object are removed. Removing the current object or any previous objects during the iteration is safe and will not disrupt the control flow.

.weakRef()

(): this

Stop newly referenced objects from becoming child objects even if this ManagedList instance itself is held through a child reference (by a parent object); this can be used to automatically dereference list items when the parent object is destroyed.

.managedId

number

Inherited from ManagedObject.managedId.

.managedState

ManagedState

Inherited from ManagedObject.managedState.

.getReferenceCount() protected

(): number

Inherited from ManagedObject.getReferenceCount.

.getManagedReferrers() protected

(): ManagedObject[]

Inherited from ManagedObject.getManagedReferrers.

.getManagedParent() protected

[1]. (): ManagedObject
[2]. <TParent extends ManagedObject>(ParentClass: ManagedObjectConstructor<TParent>): TParent

Inherited from ManagedObject.getManagedParent.

.emit()

<TEvent extends ManagedEvent = ManagedEvent, TConstructorArgs extends any[] = any[]>(e: string | TEvent | (new (...args: TConstructorArgs) => TEvent), ...constructorArgs: TConstructorArgs): this

Inherited from ManagedObject.emit.

.propagateChildEvents() protected

[1]. (f?: (this: this, e: ManagedEvent, propertyName: string) => void | ManagedEvent | ManagedEvent[]): this
[2]. (...types: (ManagedEvent | (new (...args: any[]) => ManagedEvent))[]): this

Inherited from ManagedObject.propagateChildEvents.

.activateManagedAsync() protected

(): Promise<any>

Inherited from ManagedObject.activateManagedAsync.

.deactivateManagedAsync() protected

(): Promise<void>

Inherited from ManagedObject.deactivateManagedAsync.

.destroyManagedAsync() protected

(): Promise<void>

Inherited from ManagedObject.destroyManagedAsync.

.onManagedStateActivatingAsync() protected

(): Promise<void>

Inherited from ManagedObject.onManagedStateActivatingAsync.

.onManagedStateActiveAsync() protected

(): Promise<void>

Inherited from ManagedObject.onManagedStateActiveAsync.

.onManagedStateDeactivatingAsync() protected

(): Promise<void>

Inherited from ManagedObject.onManagedStateDeactivatingAsync.

.onManagedStateInactiveAsync() protected

(): Promise<void>

Inherited from ManagedObject.onManagedStateInactiveAsync.

.onManagedStateDestroyingAsync() protected

(): Promise<void>

Inherited from ManagedObject.onManagedStateDestroyingAsync.