Documentation

ManagedObject

ManagedObject is the base class of most other framework classes, including Component.

class ManagedObject

Base class for objects that have their own unique ID, life cycle including active/inactive and destroyed states, and managed references to other instances.

Note: To learn more about components and managed objects, refer to this guide.

Constructor

(): ManagedObject

.observe() static

<T extends ManagedObject, C extends ManagedObjectConstructor<T>>(this: C, Observer: new (instance: T) => any): C

Static method to be used on subclasses of ManagedObject: add an observer to all instances of this class and derived classes. This amends properties of this class with dynamic setters to invoke a handler when any change or event occurs. A new observer (instance of the observer class) is created for each instance the first time an observed change occurs.

This function finds all methods on the observer class (but NOT on base classes, i.e. extending an observer class does not consider any methods on the original observer class) and turns the following methods into handlers for changes and/or events:

  • Any method decorated with the @onPropertyChange decorator. Methods are invoked with arguments for the current property value, an optional event reference (i.e. change event), and the observed property name.

  • Any method decorated with the @onPropertyEvent decorator. Methods are invoked with arguments for the current property value, and an event reference (any type of event that occurred on the property/ies with names specified in the call to the decorator).

  • Any method that takes the form on[PropertyName]Change where propertyName is the name of the observed property (must have a lowercase first character); or on_[propertyName]Change where propertyName is the exact name of the observed property. Methods are invoked with arguments for the current property value, and an optional event reference (i.e. change event).

  • Any method that takes the form on[EventName], which is invoked with a single ManagedEvent argument. The event name (ManagedEvent.name property) must match exactly, with the exception of the onChange method which is invoked for all events that derive from ManagedChangeEvent, and onEvent which is invoked for all events. As a special case, the onActive method is called immediately after instantiation if the observed object was already active.

  • Any method as above with an ...Async suffix, which is invoked asynchronously and should return a Promise. Asynchronous property change handlers are not invoked twice with the same value. If the value has been changed and then changed back before invoking the handler, no handler is called at all. Handlers can be rate limited using the @rateLimit decorator.

Note: Since instances of classes that derive from the target class are also observed, make sure that the observer does not depend on any functionality that may be overridden or fundamentally changed by any derived class.

Note: This function is available as ManagedObject.observe (static) on observable classes. See also ManagedObject.handle for a simpler way to handle events emitted directly by instances of a managed object class.

.handle() static

[1]. <T extends ManagedObject>(this: ManagedObjectConstructor<T>, handler: (this: T, e: ManagedEvent) => void): void
[2]. <T extends ManagedObject>(this: ManagedObjectConstructor<T>, handlers: { [eventName: string]: (this: T, e: ManagedEvent) => void; }): void

[1] Attach an event handler to be invoked for all events that are emitted on all instances of a class.

[2] Attach event handlers for all instances of a derived class. The event name (ManagedEvent.name property) is used to find an event handler in given object.

.managedId

number

Unique ID of this managed object (read only).

.managedState

ManagedState

The current lifecycle state of this managed object.

Note: This property is read-only. To change the state of a managed object (i.e. to move its lifecycle between active/inactive and destroyed states), use the activateManagedAsync, deactivateManagedAsync, and destroyManagedAsync methods. If any additional logic is required when moving between states, override the onManagedStateActivatingAsync, onManagedStateActiveAsync, onManagedStateDeactivatingAsync, onManagedStateInactiveAsync and/or onManagedStateDestroyingAsync methods in any class that derives from ManagedObject.

Note: This property cannot be observed directly. Observer classes (see ManagedObject.observe) should use methods such as onActive to observe lifecycle state.

.getReferenceCount() protected

(): number

Returns the current number of managed references that point to this object.

Note: Observers (see ManagedObject.observe) may use an onReferenceCountChangeAsync method to observe this value asynchronously.

.getManagedReferrers() protected

(): ManagedObject[]

Returns an array of unique managed objects that contain managed references to this object (see @managed, @managedChild, @managedDependency, and @compose decorators).

.getManagedParent() protected

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

[1] Returns the managed object that contains a managed child reference that points to this instance (see @managedChild and @compose decorators).

The object itself is never returned, even if it contains a managed child reference that points to itself.

[2] Returns the managed object that contains a managed child reference that points to this instance (see @managedChild decorator). If a class argument is specified, parent references are recursed until a parent of given type is found.

The object itself is never returned, even if it contains a managed child reference that points to itself (or if parents recursively reference the object or each other).

Note: The reference to the managed parent (but not its events) can be observed (see ManagedObject.observe) using an onManagedParentChange or onManagedParentChangeAsync method on the observer.

.emit()

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

Emit an event. If an event constructor is given, a new instance is created using given constructor arguments (rest parameters). If an event name (string) is given, a new default event instance is created with given name. This method may be overridden in derived classes to use a different default event class.

Use the ManagedEvent.freeze method to freeze event instances before emitting.

See ManagedObject.handle and ManagedObject.observe (static methods to be used on subclasses of ManagedObject) for ways to handle events.

Note: There is a limit to the number of events that can be emitted recursively; avoid calling this method on the same object from within an event handler.

.propagateChildEvents() protected

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

[1] Propagate events from managed child objects that are referenced as properties of this object (see @managedChild decorator) by emitting events on this object itself.

If a function is specified, the function is used to transform one event to one or more others, possibly including the same event, or stop propagation if the function returns undefined. The function will receive the event itself as its first argument, and the name of the property that references the emitting object as its second argument.

The core Active, Inactive, Destroyed, and ManagedParentChange events cannot be propagated.

[2] Propagate events from managed child objects that are referenced as properties of this object (see @managedChild decorator) by emitting events on this object itself. Only propagated events that extend given event types are propagated.

The core Active, Inactive, Destroyed, and ManagedParentChange events cannot be propagated.

Note: Calling this method a second time replaces any existing propagation rule entirely.

.activateManagedAsync() protected

(): Promise<any>

Activate this managed object (i.e. change state to ACTIVATING and then to ACTIVATED).

.deactivateManagedAsync() protected

(): Promise<void>

Deactivate this managed object, if it is currently active (i.e. change state to DEACTIVATING and then to DEACTIVATED).

.destroyManagedAsync() protected

(): Promise<void>

Destroy this managed object (i.e. change state to DESTROYING and then to DESTROYED, clear all managed references from and to this object, and destroy all managed children).

Note: Managed child objects are automatically destroyed when their parent’s reference (decorated with @managedChild) is cleared or changed, or the child object is removed from a managed list or map that is itself a managed child, OR when the parent object itself is destroyed. Managed objects are also automatically destroyed when one or more of their own properties (those decorated with @managedDependency) are cleared or changed, or the dependency object itself is destroyed.

.onManagedStateActivatingAsync() protected

(): Promise<void>

Callback invoked when changing state to ‘active’, to be overridden.

.onManagedStateActiveAsync() protected

(): Promise<void>

Callback invoked immediately after state has changed to ‘active’ and before any other state transitions, to be overridden.

.onManagedStateDeactivatingAsync() protected

(): Promise<void>

Callback invoked when changing state to ‘inactive’, to be overridden.

.onManagedStateInactiveAsync() protected

(): Promise<void>

Callback invoked immediately after state has changed to ‘inactive’ and before any other state transitions, to be overridden.

.onManagedStateDestroyingAsync() protected

(): Promise<void>

Callback invoked when changing state to ‘destroyed’, to be overridden.