lifecycleion 0.0.2 → 0.0.4

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

@@ -697,7 +697,9 @@ interface LifecycleManagerOptions {
     shutdownWarningTimeoutMS?: number;
     /** Default message timeout in ms (default: 5000, 0 = disabled) */
     messageTimeoutMS?: number;
-    /** Auto-attach signals when first component starts (default: false) */
+    /** Auto-attach signals before startAllComponents()/startComponent() begins work, even if startup later fails (default: false) */
+    attachSignalsBeforeStartup?: boolean;
+    /** Auto-attach signals when the first component successfully starts (default: false) */
     attachSignalsOnStart?: boolean;
     /** Auto-detach signals when last component stops (default: false) */
     detachSignalsOnStop?: boolean;
@@ -1003,6 +1005,7 @@ declare class LifecycleManager extends EventEmitterProtected implements Lifecycl
     private readonly messageTimeoutMS;
     private readonly startupTimeoutMS;
     private readonly shutdownOptions?;
+    private readonly attachSignalsBeforeStartup;
     private readonly attachSignalsOnStart;
     private readonly detachSignalsOnStop;
     private components;
@@ -1011,9 +1014,12 @@ declare class LifecycleManager extends EventEmitterProtected implements Lifecycl
     private stalledComponents;
     private componentTimestamps;
     private componentErrors;
+    private componentStartAttemptTokens;
     private isStarting;
     private isStarted;
     private isShuttingDown;
+    private shutdownToken;
+    private pendingLoggerExitResolve;
     private shutdownMethod;
     private lastShutdownResult;
     private processSignalManager;
@@ -1340,6 +1346,10 @@ declare class LifecycleManager extends EventEmitterProtected implements Lifecycl
      */
     private registerComponentInternal;
     private stopAllComponentsInternal;
+    /**
+     * Release a deferred logger.exit() request after shutdown fully settles.
+     */
+    private finalizePendingLoggerExit;
     /**
      * Retry shutdown for a stalled component.
      * Attempts the force phase directly to avoid re-running a failing stop().
@@ -1409,6 +1419,9 @@ declare class LifecycleManager extends EventEmitterProtected implements Lifecycl
      * Used when a required component fails to start during startAllComponents()
      */
     private rollbackStartup;
+    private autoAttachSignals;
+    private autoDetachSignalsIfIdle;
+    private monitorLateStartupCompletion;
     /**
      * Safe emit wrapper - prevents event handler errors from breaking lifecycle
      */

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

@@ -697,7 +697,9 @@ interface LifecycleManagerOptions {
     shutdownWarningTimeoutMS?: number;
     /** Default message timeout in ms (default: 5000, 0 = disabled) */
     messageTimeoutMS?: number;
-    /** Auto-attach signals when first component starts (default: false) */
+    /** Auto-attach signals before startAllComponents()/startComponent() begins work, even if startup later fails (default: false) */
+    attachSignalsBeforeStartup?: boolean;
+    /** Auto-attach signals when the first component successfully starts (default: false) */
     attachSignalsOnStart?: boolean;
     /** Auto-detach signals when last component stops (default: false) */
     detachSignalsOnStop?: boolean;
@@ -1003,6 +1005,7 @@ declare class LifecycleManager extends EventEmitterProtected implements Lifecycl
     private readonly messageTimeoutMS;
     private readonly startupTimeoutMS;
     private readonly shutdownOptions?;
+    private readonly attachSignalsBeforeStartup;
     private readonly attachSignalsOnStart;
     private readonly detachSignalsOnStop;
     private components;
@@ -1011,9 +1014,12 @@ declare class LifecycleManager extends EventEmitterProtected implements Lifecycl
     private stalledComponents;
     private componentTimestamps;
     private componentErrors;
+    private componentStartAttemptTokens;
     private isStarting;
     private isStarted;
     private isShuttingDown;
+    private shutdownToken;
+    private pendingLoggerExitResolve;
     private shutdownMethod;
     private lastShutdownResult;
     private processSignalManager;
@@ -1340,6 +1346,10 @@ declare class LifecycleManager extends EventEmitterProtected implements Lifecycl
      */
     private registerComponentInternal;
     private stopAllComponentsInternal;
+    /**
+     * Release a deferred logger.exit() request after shutdown fully settles.
+     */
+    private finalizePendingLoggerExit;
     /**
      * Retry shutdown for a stalled component.
      * Attempts the force phase directly to avoid re-running a failing stop().
@@ -1409,6 +1419,9 @@ declare class LifecycleManager extends EventEmitterProtected implements Lifecycl
      * Used when a required component fails to start during startAllComponents()
      */
     private rollbackStartup;
+    private autoAttachSignals;
+    private autoDetachSignalsIfIdle;
+    private monitorLateStartupCompletion;
     /**
      * Safe emit wrapper - prevents event handler errors from breaking lifecycle
      */

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

@@ -850,6 +850,9 @@ var EventEmitterProtected = class {
   }
 };
 
+// src/lib/lifecycle-manager/lifecycle-manager.ts
+import { ulid as ulid2 } from "ulid";
+
 // src/lib/lifecycle-manager/component-lifecycle.ts
 var ComponentLifecycle = class {
   manager;
@@ -1915,6 +1918,7 @@ var LifecycleManager = class extends EventEmitterProtected {
   messageTimeoutMS;
   startupTimeoutMS;
   shutdownOptions;
+  attachSignalsBeforeStartup;
   attachSignalsOnStart;
   detachSignalsOnStop;
   // Component management
@@ -1925,10 +1929,15 @@ var LifecycleManager = class extends EventEmitterProtected {
   // State tracking for individual components
   componentTimestamps = /* @__PURE__ */ new Map();
   componentErrors = /* @__PURE__ */ new Map();
+  componentStartAttemptTokens = /* @__PURE__ */ new Map();
   // State flags
   isStarting = false;
   isStarted = false;
   isShuttingDown = false;
+  // Unique token used to detect shutdowns that happened during async start().
+  shutdownToken = ulid2();
+  // Resolver for the first logger.exit() deferred during an already-running shutdown.
+  pendingLoggerExitResolve = null;
   shutdownMethod = null;
   lastShutdownResult = null;
   // Signal management
@@ -1954,6 +1963,7 @@ var LifecycleManager = class extends EventEmitterProtected {
       haltOnStall: true,
       ...options.shutdownOptions
     };
+    this.attachSignalsBeforeStartup = options.attachSignalsBeforeStartup ?? false;
     this.attachSignalsOnStart = options.attachSignalsOnStart ?? false;
     this.detachSignalsOnStop = options.detachSignalsOnStop ?? false;
     this.onReloadRequested = options.onReloadRequested;
@@ -2117,6 +2127,7 @@ var LifecycleManager = class extends EventEmitterProtected {
     this.componentStates.delete(name);
     this.componentTimestamps.delete(name);
     this.componentErrors.delete(name);
+    this.componentStartAttemptTokens.delete(name);
     this.stalledComponents.delete(name);
     this.runningComponents.delete(name);
     this.updateStartedFlag();
@@ -2525,6 +2536,7 @@ var LifecycleManager = class extends EventEmitterProtected {
     this.isStarting = true;
     this.shutdownMethod = null;
     this.lastShutdownResult = null;
+    const didAutoAttachSignalsForBulkStartup = this.attachSignalsBeforeStartup ? this.autoAttachSignals("bulk startup") : false;
     this.logger.info("Starting all components");
     const effectiveTimeout = options?.timeoutMS ?? this.startupTimeoutMS;
     let hasTimedOut = false;
@@ -2638,6 +2650,18 @@ var LifecycleManager = class extends EventEmitterProtected {
           startedComponents.push(name);
         } else if (result.code === "component_already_running") {
           startedComponents.push(name);
+        } else if (result.code === "shutdown_in_progress") {
+          await this.rollbackStartup(startedComponents);
+          return {
+            success: false,
+            startedComponents: [],
+            failedOptionalComponents,
+            skippedDueToDependency: Array.from(skippedDueToDependency),
+            reason: result.reason || "Shutdown triggered during startup",
+            code: "shutdown_in_progress",
+            error: result.error,
+            durationMS: Date.now() - startTime
+          };
         } else {
           if (component.isOptional()) {
             this.logger.entity(name).warn("Optional component failed to start, continuing", {
@@ -2726,6 +2750,9 @@ var LifecycleManager = class extends EventEmitterProtected {
       if (timeoutHandle) {
         clearTimeout(timeoutHandle);
       }
+      if (didAutoAttachSignalsForBulkStartup) {
+        this.autoDetachSignalsIfIdle("failed bulk startup");
+      }
       this.isStarting = false;
     }
   }
@@ -2970,6 +2997,17 @@ var LifecycleManager = class extends EventEmitterProtected {
     this.rootLogger.setBeforeExitCallback(
       async (exitCode, isFirstExit) => {
         if (this.isShuttingDown) {
+          if (isFirstExit && this.pendingLoggerExitResolve === null) {
+            this.logger.debug(
+              "Logger exit called during shutdown, waiting...",
+              {
+                params: { exitCode }
+              }
+            );
+            return await new Promise((resolve) => {
+              this.pendingLoggerExitResolve = resolve;
+            });
+          }
           this.logger.debug("Logger exit called during shutdown, waiting...", {
             params: { exitCode }
           });
@@ -3793,6 +3831,7 @@ var LifecycleManager = class extends EventEmitterProtected {
         stoppedAt: null
       });
       this.componentErrors.set(componentName, null);
+      this.componentStartAttemptTokens.set(componentName, ulid2());
       const isManualPositionRespected = this.isManualPositionRespected({
         componentName,
         position,
@@ -3944,6 +3983,7 @@ var LifecycleManager = class extends EventEmitterProtected {
       };
     }
     this.isShuttingDown = true;
+    this.shutdownToken = ulid2();
     this.shutdownMethod = method;
     const isDuringStartup = this.isStarting;
     this.logger.info("Stopping all components", { params: { method } });
@@ -4073,7 +4113,19 @@ var LifecycleManager = class extends EventEmitterProtected {
       }
       this.isShuttingDown = false;
       this.updateStartedFlag();
+      this.finalizePendingLoggerExit();
+    }
+  }
+  /**
+   * Release a deferred logger.exit() request after shutdown fully settles.
+   */
+  finalizePendingLoggerExit() {
+    if (this.pendingLoggerExitResolve === null || this.isShuttingDown) {
+      return;
     }
+    const resolve = this.pendingLoggerExitResolve;
+    this.pendingLoggerExitResolve = null;
+    resolve({ action: "proceed" });
   }
   /**
    * Retry shutdown for a stalled component.
@@ -4214,6 +4266,10 @@ var LifecycleManager = class extends EventEmitterProtected {
     this.logger.entity(name).info("Starting component");
     this.lifecycleEvents.componentStarting(name);
     const timeoutMS = component.startupTimeoutMS;
+    const startAttemptToken = ulid2();
+    this.componentStartAttemptTokens.set(name, startAttemptToken);
+    const shutdownTokenAtStart = this.shutdownToken;
+    const didAutoAttachSignalsForComponentStartup = this.attachSignalsBeforeStartup ? this.autoAttachSignals("component startup") : false;
     let timeoutHandle;
     try {
       const startPromise = component.start();
@@ -4228,6 +4284,13 @@ var LifecycleManager = class extends EventEmitterProtected {
                   params: { error }
                 });
               }
+            } else {
+              this.monitorLateStartupCompletion(
+                name,
+                component,
+                startPromise,
+                startAttemptToken
+              );
             }
             Promise.resolve(startPromise).catch(() => {
             });
@@ -4243,15 +4306,36 @@ var LifecycleManager = class extends EventEmitterProtected {
       } else {
         await startPromise;
       }
+      if (this.isShuttingDown || shutdownTokenAtStart !== this.shutdownToken) {
+        this.componentStates.set(name, "running");
+        this.runningComponents.add(name);
+        this.stalledComponents.delete(name);
+        this.updateStartedFlag();
+        const timestamps2 = this.componentTimestamps.get(name) ?? {
+          startedAt: null,
+          stoppedAt: null
+        };
+        timestamps2.startedAt = Date.now();
+        this.componentTimestamps.set(name, timestamps2);
+        this.logger.entity(name).warn(
+          "Component finished starting after shutdown began, stopping immediately"
+        );
+        const stopResult = await this.stopComponentInternal(name);
+        return {
+          success: false,
+          componentName: name,
+          reason: "Shutdown triggered during component startup",
+          code: "shutdown_in_progress",
+          error: stopResult.error,
+          status: this.getComponentStatus(name)
+        };
+      }
       this.componentStates.set(name, "running");
       this.runningComponents.add(name);
       this.stalledComponents.delete(name);
       this.updateStartedFlag();
-      if (this.attachSignalsOnStart && this.runningComponents.size === 1 && !this.processSignalManager) {
-        this.logger.info(
-          "Auto-attaching process signals on first component start"
-        );
-        this.attachSignals();
+      if (this.attachSignalsOnStart && this.runningComponents.size === 1) {
+        this.autoAttachSignals("first component start");
       }
       const timestamps = this.componentTimestamps.get(name) ?? {
         startedAt: null,
@@ -4300,6 +4384,9 @@ var LifecycleManager = class extends EventEmitterProtected {
       if (timeoutHandle) {
         clearTimeout(timeoutHandle);
       }
+      if (didAutoAttachSignalsForComponentStartup) {
+        this.autoDetachSignalsIfIdle("failed component startup");
+      }
     }
   }
   /**
@@ -4796,6 +4883,57 @@ var LifecycleManager = class extends EventEmitterProtected {
     }
     this.logger.info("Rollback completed");
   }
+  autoAttachSignals(trigger) {
+    if (this.processSignalManager?.getStatus().isAttached) {
+      return false;
+    }
+    this.logger.info(`Auto-attaching process signals on ${trigger}`);
+    this.attachSignals();
+    return true;
+  }
+  autoDetachSignalsIfIdle(trigger) {
+    if (!this.detachSignalsOnStop || this.runningComponents.size > 0 || !this.processSignalManager?.getStatus().isAttached) {
+      return;
+    }
+    this.logger.info(`Auto-detaching process signals after ${trigger}`);
+    this.detachSignals();
+  }
+  monitorLateStartupCompletion(name, component, startPromise, startAttemptToken) {
+    this.logger.entity(name).warn(
+      "Startup timed out without onStartupAborted, stopping component if startup completes later"
+    );
+    Promise.resolve(startPromise).then(async () => {
+      const timeoutState = this.componentStates.get(name);
+      if (this.getComponent(name) !== component || this.componentStartAttemptTokens.get(name) !== startAttemptToken || this.isComponentRunning(name) || timeoutState !== "starting-timed-out" && timeoutState !== "failed") {
+        return;
+      }
+      this.componentStates.set(name, "running");
+      this.runningComponents.add(name);
+      this.stalledComponents.delete(name);
+      this.updateStartedFlag();
+      const timestamps = this.componentTimestamps.get(name) ?? {
+        startedAt: null,
+        stoppedAt: null
+      };
+      timestamps.startedAt = Date.now();
+      this.componentTimestamps.set(name, timestamps);
+      this.logger.entity(name).warn(
+        "Component completed startup after timeout, stopping automatically"
+      );
+      const stopResult = await this.stopComponentInternal(name);
+      if (!stopResult.success) {
+        this.logger.entity(name).warn("Automatic stop after startup timeout failed", {
+          params: {
+            error: stopResult.error,
+            code: stopResult.code
+          }
+        });
+        return;
+      }
+      this.componentStates.set(name, timeoutState);
+    }).catch(() => {
+    });
+  }
   /**
    * Safe emit wrapper - prevents event handler errors from breaking lifecycle
    */