@hyperfrontend/state-machine/lifecycle-aware-componentlifecycle-aware-component
A component base that exposes initializing, ready, starting, stopping, and active state phases plus per-phase change callbacks.
LifecycleAwareComponent models a stateful component whose visibility to consumers depends on which phase it has reached: for example, a UI element that should only render after ready or a service that needs to drain in-flight work on stopping before becoming inactive. Each phase exposes a typed change callback (InitializingChangeCallback, ReadyChangeCallback, StartingChangeCallback, StoppingChangeCallback, ActiveChangeCallback) so subclasses or wrappers can react when the component crosses a boundary. The component composes the lower-level Events registry under the hood; reach for it when you need a structured lifecycle rather than raw pub/sub.
API Reference§
◇ Classes
Abstract base class for components that need lifecycle state management. Tracks initializing, ready, starting, stopping, and active states.
Constructor
§
new LifecycleAwareComponent(Properties
§
An implementation raises
protected abstract init:Process<Brings the component to the ready phase. An implementation raises
initializing while it works and ready when it finishes, and resolves to the status the run ended with: success, fail or skipped. The base class never calls it, so the subclass decides when initialization happens.§
An implementation raises
abstract start:Process<Starts the component once it is ready. An implementation raises
starting while it works and active once running, and resolves to the status the run ended with: success, fail or skipped. The base class only tracks the flags.§
An implementation raises
abstract stop:Process<Stops a running component. An implementation raises
stopping while it works and lowers active once stopped, and resolves to the status the run ended with: success, fail or skipped. The base class only tracks the flags.Methods
§
clear(Removes every registered status callback across all five flags.
The flags themselves keep their values; only the subscriptions go, so a component can be reused without carrying listeners from its previous owner.
The flags themselves keep their values; only the subscriptions go, so a component can be reused without carrying listeners from its previous owner.
§
onActiveStatusChange(Registers a callback for changes to the active flag.
If the component is already running, the callback is invoked at once with
If the component is already running, the callback is invoked at once with
true. A callback already registered is not added a second time.Parameters
| Name | Type | Description |
|---|---|---|
§callback | ActiveChangeCallback | Called with the flag's new value on every change |
Returns
LifecycleAwareComponentThis component, so registrations can be chained
§
onInitializingStatusChange(Registers a callback for changes to the initializing flag.
If the component is initializing at the time, the callback is invoked at once with
If the component is initializing at the time, the callback is invoked at once with
true, so a late subscriber learns the current phase instead of waiting for the next change. A callback already registered is not added a second time.Parameters
| Name | Type | Description |
|---|---|---|
§callback | InitializingChangeCallback | Called with the flag's new value on every change |
Returns
LifecycleAwareComponentThis component, so registrations can be chained
§
onReadyStatusChange(Registers a callback for changes to the ready flag.
If the component is already ready, the callback is invoked at once with
If the component is already ready, the callback is invoked at once with
true. A callback already registered is not added a second time.Parameters
| Name | Type | Description |
|---|---|---|
§callback | ReadyChangeCallback | Called with the flag's new value on every change |
Returns
LifecycleAwareComponentThis component, so registrations can be chained
§
onStartStatusChange(Registers a callback for changes to the starting flag.
If a start is under way at the time, the callback is invoked at once with
If a start is under way at the time, the callback is invoked at once with
true. A callback already registered is not added a second time.Parameters
| Name | Type | Description |
|---|---|---|
§callback | StartingChangeCallback | Called with the flag's new value on every change |
Returns
LifecycleAwareComponentThis component, so registrations can be chained
§
onStopStatusChange(Registers a callback for changes to the stopping flag.
If a stop is under way at the time, the callback is invoked at once with
If a stop is under way at the time, the callback is invoked at once with
true. A callback already registered is not added a second time.Parameters
| Name | Type | Description |
|---|---|---|
§callback | StoppingChangeCallback | Called with the flag's new value on every change |
Returns
LifecycleAwareComponentThis component, so registrations can be chained
§
protected setInitializing(Records whether initialization is under way and notifies the initializing callbacks.
Setting the value the flag already holds changes nothing and notifies nobody, so the callbacks fire only on a real transition.
Setting the value the flag already holds changes nothing and notifies nobody, so the callbacks fire only on a real transition.
Parameters
| Name | Type | Description |
|---|---|---|
§initializing | boolean | The new value of the flag |
Example
Extending LifecycleAwareComponent
class MyService extends LifecycleAwareComponent {
async doInit() { this.setInitializing(true) }
async doStart() { this.setActive(true) }
}◆ Types
Callback invoked when active state changes
type ActiveChangeCallback = (Callback invoked when initializing state changes
type InitializingChangeCallback = (Callback invoked when ready state changes
type ReadyChangeCallback = (Callback invoked when starting state changes
type StartingChangeCallback = (Callback invoked when stopping state changes
type StoppingChangeCallback = (