lifecycleion 0.0.14 → 0.0.16

package/dist/lib/lifecycle-manager/index.d.cts

@@ -438,13 +438,20 @@ interface ValueResult<T = unknown> {
     code: 'found' | 'not_found' | 'stopped' | 'stalled' | 'no_handler' | 'error';
 }
 type EventEmitterSurface = Pick<EventEmitterProtected, 'on' | 'once' | 'hasListener' | 'hasListeners' | 'listenerCount'>;
+/**
+ * Public value lookup surface shared by LifecycleManager and component-scoped
+ * lifecycle references.
+ */
+interface LifecycleValueProvider {
+    getValue<T = unknown>(componentName: string, key: string, options?: GetValueOptions): ValueResult<T>;
+}
 /**
  * Common lifecycle interface shared by LifecycleManager and ComponentLifecycle
  *
  * Keep in sync with public LifecycleManager API and ComponentLifecycle proxy.
  * Purpose: define the shared surface both expose to avoid drift across the two.
  */
-interface LifecycleCommon extends EventEmitterSurface {
+interface LifecycleCommon extends EventEmitterSurface, LifecycleValueProvider {
     hasComponent(name: string): boolean;
     isComponentRunning(name: string): boolean;
     getComponentNames(): string[];
@@ -479,7 +486,6 @@ interface LifecycleCommon extends EventEmitterSurface {
     broadcastMessage(payload: unknown, options?: BroadcastOptions): Promise<BroadcastResult[]>;
     checkComponentHealth(name: string): Promise<HealthCheckResult>;
     checkAllHealth(): Promise<HealthReport>;
-    getValue<T = unknown>(componentName: string, key: string, options?: GetValueOptions): ValueResult<T>;
 }
 /**
  * Component-scoped lifecycle interface injected into BaseComponent
@@ -546,7 +552,7 @@ interface UnregisterOptions {
  * Options for starting all components
  */
 interface StartupOptions {
-    /** Allow start even if stalled components exist (default: false) */
+    /** Allow bulk startup to proceed by skipping stalled components (default: false) */
     ignoreStalledComponents?: boolean;
     /** Global timeout for entire startup process in milliseconds (default: constructor's startupTimeoutMS) */
     timeoutMS?: number;
@@ -960,6 +966,8 @@ declare abstract class BaseComponent {
     private _unexpectedStopHandler?;
     /** @internal Incremented whenever the unexpected-stop handler is re-armed or cleared. */
     private _unexpectedStopGeneration;
+    /** @internal Flag indicating whether this component is currently registered with a LifecycleManager */
+    private _isRegistered;
     /**
      * Create a new component
      *
@@ -972,6 +980,12 @@ declare abstract class BaseComponent {
     _setUnexpectedStopHandler(handler: (error?: Error) => boolean): void;
     /** @internal Called by LifecycleManager when stop begins or component is unregistered. */
     _clearUnexpectedStopHandler(): void;
+    /** @internal Called by LifecycleManager when registering the component. */
+    _markRegistered(): void;
+    /** @internal Called by LifecycleManager when unregistering the component. */
+    _markUnregistered(): void;
+    /** @internal Check if the component is registered with any LifecycleManager. */
+    _isRegisteredWithManager(): boolean;
     /**
      * Start the component
      *
@@ -2404,4 +2418,4 @@ declare const lifecycleManagerErrCodes: {
     readonly StopTimeout: "StopTimeout";
 };
 
-export { BaseComponent, type BaseOperationResult, type BroadcastOptions, type BroadcastResult, type ComponentHealthResult, ComponentNotFoundError, type ComponentOperationFailureCode, type ComponentOperationResult, type ComponentOptions, ComponentRegistrationError, type ComponentSignalResult, type ComponentStallInfo, ComponentStartTimeoutError, ComponentStartupError, type ComponentState, type ComponentStatus, ComponentStopTimeoutError, type ComponentValueResult, DependencyCycleError, type DependencyValidationResult, type ForceShutdownContext, type GetValueOptions, type HealthCheckResult, type HealthReport, type InsertComponentAtResult, type InsertPosition, InvalidComponentNameError, LifecycleManager, type LifecycleManagerEmit, type LifecycleManagerEventMap, type LifecycleManagerEventName, LifecycleManagerEvents, type LifecycleManagerOptions, type LifecycleManagerStatus, type MessageResult, MissingDependencyError, type RegisterComponentResult, type RegisterOptions, type RegistrationFailureCode, type RepeatedShutdownRequestPolicy, type RestartComponentOptions, type RestartResult, type SendMessageOptions, type ShutdownEscalationStatus, type ShutdownMethod, type ShutdownResult, type SignalBroadcastResult, type StartComponentOptions, type StartupOptions, type StartupOrderFailureCode, type StartupOrderResult, type StartupResult, StartupTimeoutError, type StopAllOptions, type StopComponentOptions, type SystemState, type UnregisterComponentResult, type UnregisterFailureCode, type UnregisterOptions, type ValueResult, lifecycleManagerErrCodes, lifecycleManagerErrPrefix, lifecycleManagerErrTypes };
+export { BaseComponent, type BaseOperationResult, type BroadcastOptions, type BroadcastResult, type ComponentHealthResult, ComponentNotFoundError, type ComponentOperationFailureCode, type ComponentOperationResult, type ComponentOptions, ComponentRegistrationError, type ComponentSignalResult, type ComponentStallInfo, ComponentStartTimeoutError, ComponentStartupError, type ComponentState, type ComponentStatus, ComponentStopTimeoutError, type ComponentValueResult, DependencyCycleError, type DependencyValidationResult, type ForceShutdownContext, type GetValueOptions, type HealthCheckResult, type HealthReport, type InsertComponentAtResult, type InsertPosition, InvalidComponentNameError, LifecycleManager, type LifecycleManagerEmit, type LifecycleManagerEventMap, type LifecycleManagerEventName, LifecycleManagerEvents, type LifecycleManagerOptions, type LifecycleManagerStatus, type LifecycleValueProvider, type MessageResult, MissingDependencyError, type RegisterComponentResult, type RegisterOptions, type RegistrationFailureCode, type RepeatedShutdownRequestPolicy, type RestartComponentOptions, type RestartResult, type SendMessageOptions, type ShutdownEscalationStatus, type ShutdownMethod, type ShutdownResult, type SignalBroadcastResult, type StartComponentOptions, type StartupOptions, type StartupOrderFailureCode, type StartupOrderResult, type StartupResult, StartupTimeoutError, type StopAllOptions, type StopComponentOptions, type SystemState, type UnregisterComponentResult, type UnregisterFailureCode, type UnregisterOptions, type ValueResult, lifecycleManagerErrCodes, lifecycleManagerErrPrefix, lifecycleManagerErrTypes };

package/dist/lib/lifecycle-manager/index.d.ts

@@ -438,13 +438,20 @@ interface ValueResult<T = unknown> {
     code: 'found' | 'not_found' | 'stopped' | 'stalled' | 'no_handler' | 'error';
 }
 type EventEmitterSurface = Pick<EventEmitterProtected, 'on' | 'once' | 'hasListener' | 'hasListeners' | 'listenerCount'>;
+/**
+ * Public value lookup surface shared by LifecycleManager and component-scoped
+ * lifecycle references.
+ */
+interface LifecycleValueProvider {
+    getValue<T = unknown>(componentName: string, key: string, options?: GetValueOptions): ValueResult<T>;
+}
 /**
  * Common lifecycle interface shared by LifecycleManager and ComponentLifecycle
  *
  * Keep in sync with public LifecycleManager API and ComponentLifecycle proxy.
  * Purpose: define the shared surface both expose to avoid drift across the two.
  */
-interface LifecycleCommon extends EventEmitterSurface {
+interface LifecycleCommon extends EventEmitterSurface, LifecycleValueProvider {
     hasComponent(name: string): boolean;
     isComponentRunning(name: string): boolean;
     getComponentNames(): string[];
@@ -479,7 +486,6 @@ interface LifecycleCommon extends EventEmitterSurface {
     broadcastMessage(payload: unknown, options?: BroadcastOptions): Promise<BroadcastResult[]>;
     checkComponentHealth(name: string): Promise<HealthCheckResult>;
     checkAllHealth(): Promise<HealthReport>;
-    getValue<T = unknown>(componentName: string, key: string, options?: GetValueOptions): ValueResult<T>;
 }
 /**
  * Component-scoped lifecycle interface injected into BaseComponent
@@ -546,7 +552,7 @@ interface UnregisterOptions {
  * Options for starting all components
  */
 interface StartupOptions {
-    /** Allow start even if stalled components exist (default: false) */
+    /** Allow bulk startup to proceed by skipping stalled components (default: false) */
     ignoreStalledComponents?: boolean;
     /** Global timeout for entire startup process in milliseconds (default: constructor's startupTimeoutMS) */
     timeoutMS?: number;
@@ -960,6 +966,8 @@ declare abstract class BaseComponent {
     private _unexpectedStopHandler?;
     /** @internal Incremented whenever the unexpected-stop handler is re-armed or cleared. */
     private _unexpectedStopGeneration;
+    /** @internal Flag indicating whether this component is currently registered with a LifecycleManager */
+    private _isRegistered;
     /**
      * Create a new component
      *
@@ -972,6 +980,12 @@ declare abstract class BaseComponent {
     _setUnexpectedStopHandler(handler: (error?: Error) => boolean): void;
     /** @internal Called by LifecycleManager when stop begins or component is unregistered. */
     _clearUnexpectedStopHandler(): void;
+    /** @internal Called by LifecycleManager when registering the component. */
+    _markRegistered(): void;
+    /** @internal Called by LifecycleManager when unregistering the component. */
+    _markUnregistered(): void;
+    /** @internal Check if the component is registered with any LifecycleManager. */
+    _isRegisteredWithManager(): boolean;
     /**
      * Start the component
      *
@@ -2404,4 +2418,4 @@ declare const lifecycleManagerErrCodes: {
     readonly StopTimeout: "StopTimeout";
 };
 
-export { BaseComponent, type BaseOperationResult, type BroadcastOptions, type BroadcastResult, type ComponentHealthResult, ComponentNotFoundError, type ComponentOperationFailureCode, type ComponentOperationResult, type ComponentOptions, ComponentRegistrationError, type ComponentSignalResult, type ComponentStallInfo, ComponentStartTimeoutError, ComponentStartupError, type ComponentState, type ComponentStatus, ComponentStopTimeoutError, type ComponentValueResult, DependencyCycleError, type DependencyValidationResult, type ForceShutdownContext, type GetValueOptions, type HealthCheckResult, type HealthReport, type InsertComponentAtResult, type InsertPosition, InvalidComponentNameError, LifecycleManager, type LifecycleManagerEmit, type LifecycleManagerEventMap, type LifecycleManagerEventName, LifecycleManagerEvents, type LifecycleManagerOptions, type LifecycleManagerStatus, type MessageResult, MissingDependencyError, type RegisterComponentResult, type RegisterOptions, type RegistrationFailureCode, type RepeatedShutdownRequestPolicy, type RestartComponentOptions, type RestartResult, type SendMessageOptions, type ShutdownEscalationStatus, type ShutdownMethod, type ShutdownResult, type SignalBroadcastResult, type StartComponentOptions, type StartupOptions, type StartupOrderFailureCode, type StartupOrderResult, type StartupResult, StartupTimeoutError, type StopAllOptions, type StopComponentOptions, type SystemState, type UnregisterComponentResult, type UnregisterFailureCode, type UnregisterOptions, type ValueResult, lifecycleManagerErrCodes, lifecycleManagerErrPrefix, lifecycleManagerErrTypes };
+export { BaseComponent, type BaseOperationResult, type BroadcastOptions, type BroadcastResult, type ComponentHealthResult, ComponentNotFoundError, type ComponentOperationFailureCode, type ComponentOperationResult, type ComponentOptions, ComponentRegistrationError, type ComponentSignalResult, type ComponentStallInfo, ComponentStartTimeoutError, ComponentStartupError, type ComponentState, type ComponentStatus, ComponentStopTimeoutError, type ComponentValueResult, DependencyCycleError, type DependencyValidationResult, type ForceShutdownContext, type GetValueOptions, type HealthCheckResult, type HealthReport, type InsertComponentAtResult, type InsertPosition, InvalidComponentNameError, LifecycleManager, type LifecycleManagerEmit, type LifecycleManagerEventMap, type LifecycleManagerEventName, LifecycleManagerEvents, type LifecycleManagerOptions, type LifecycleManagerStatus, type LifecycleValueProvider, type MessageResult, MissingDependencyError, type RegisterComponentResult, type RegisterOptions, type RegistrationFailureCode, type RepeatedShutdownRequestPolicy, type RestartComponentOptions, type RestartResult, type SendMessageOptions, type ShutdownEscalationStatus, type ShutdownMethod, type ShutdownResult, type SignalBroadcastResult, type StartComponentOptions, type StartupOptions, type StartupOrderFailureCode, type StartupOrderResult, type StartupResult, StartupTimeoutError, type StopAllOptions, type StopComponentOptions, type SystemState, type UnregisterComponentResult, type UnregisterFailureCode, type UnregisterOptions, type ValueResult, lifecycleManagerErrCodes, lifecycleManagerErrPrefix, lifecycleManagerErrTypes };

package/dist/lib/lifecycle-manager/index.js

@@ -1427,6 +1427,7 @@ var LIFECYCLE_MANAGER_LOG_REQUIRED_COMPONENT_UNEXPECTED_STOP_DURING_STARTUP = "R
 var LIFECYCLE_MANAGER_MESSAGE_REGISTER_SHUTDOWN_IN_PROGRESS = "Cannot register component while shutdown is in progress (isShuttingDown=true).";
 var LIFECYCLE_MANAGER_MESSAGE_REGISTER_REQUIRED_DEPENDENCY_DURING_STARTUP = "Cannot register component during startup when it is a required dependency for other components.";
 var LIFECYCLE_MANAGER_MESSAGE_DUPLICATE_COMPONENT_INSTANCE = "Component instance is already registered.";
+var LIFECYCLE_MANAGER_MESSAGE_DUPLICATE_COMPONENT_INSTANCE_EXTERNAL = "Component instance is already registered with another lifecycle manager.";
 
 // src/lib/process-signal-manager.ts
 import { ulid } from "ulid";
@@ -2216,6 +2217,7 @@ var LifecycleManager = class extends EventEmitterProtected {
     }
     this.components = this.components.filter((c) => c.getName() !== name);
     component._clearUnexpectedStopHandler();
+    component._markUnregistered();
     this.componentStates.delete(name);
     this.componentTimestamps.delete(name);
     this.componentErrors.delete(name);
@@ -3934,12 +3936,16 @@ var LifecycleManager = class extends EventEmitterProtected {
           targetFound: void 0
         });
       }
-      if (this.hasComponentInstance(component)) {
-        this.logger.entity(componentName).warn("Component instance already registered");
+      if (component._isRegisteredWithManager()) {
+        const isRegisteredHere = this.hasComponentInstance(component);
+        const message = isRegisteredHere ? LIFECYCLE_MANAGER_MESSAGE_DUPLICATE_COMPONENT_INSTANCE : LIFECYCLE_MANAGER_MESSAGE_DUPLICATE_COMPONENT_INSTANCE_EXTERNAL;
+        this.logger.entity(componentName).warn(
+          isRegisteredHere ? "Component instance already registered" : "Component instance already registered with another lifecycle manager"
+        );
         this.lifecycleEvents.componentRegistrationRejected({
           name: componentName,
           reason: "duplicate_instance",
-          message: LIFECYCLE_MANAGER_MESSAGE_DUPLICATE_COMPONENT_INSTANCE,
+          message,
           registrationIndexBefore,
           registrationIndexAfter: registrationIndexBefore,
           requestedPosition: isInsertAction ? { position, targetComponentName } : void 0,
@@ -3951,7 +3957,7 @@ var LifecycleManager = class extends EventEmitterProtected {
           targetComponentName,
           registrationIndexBefore,
           code: "duplicate_instance",
-          reason: LIFECYCLE_MANAGER_MESSAGE_DUPLICATE_COMPONENT_INSTANCE,
+          reason: message,
           targetFound: void 0
         });
       }
@@ -4064,6 +4070,7 @@ var LifecycleManager = class extends EventEmitterProtected {
         getValueInternal: (compName, key, from) => this.getValueInternal(compName, key, from)
       };
       component.lifecycle = new ComponentLifecycle(this, componentName, internalCallbacks);
+      component._markRegistered();
       this.componentStates.set(componentName, "registered");
       this.componentTimestamps.set(componentName, {
         startedAt: null,
@@ -6340,6 +6347,8 @@ var BaseComponent = class {
   _unexpectedStopHandler;
   /** @internal Incremented whenever the unexpected-stop handler is re-armed or cleared. */
   _unexpectedStopGeneration = 0;
+  /** @internal Flag indicating whether this component is currently registered with a LifecycleManager */
+  _isRegistered = false;
   /**
    * Create a new component
    *
@@ -6392,6 +6401,19 @@ var BaseComponent = class {
     this._unexpectedStopHandler = void 0;
     this.reportUnexpectedStop = () => false;
   }
+  /** @internal Called by LifecycleManager when registering the component. */
+  _markRegistered() {
+    this._isRegistered = true;
+  }
+  /** @internal Called by LifecycleManager when unregistering the component. */
+  _markUnregistered() {
+    this._isRegistered = false;
+    this.lifecycle = void 0;
+  }
+  /** @internal Check if the component is registered with any LifecycleManager. */
+  _isRegisteredWithManager() {
+    return this._isRegistered;
+  }
   /**
    * Get component name
    */