lifecycleion 0.0.2 → 0.0.4

package/README.md

@@ -1,4 +1,4 @@
-# Lifecycleion v0.0.2
+# Lifecycleion v0.0.4
 
 [![npm version](https://badge.fury.io/js/lifecycleion.svg)](https://badge.fury.io/js/lifecycleion)
 

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

@@ -900,6 +900,9 @@ var EventEmitterProtected = class {
   }
 };
 
+// src/lib/lifecycle-manager/lifecycle-manager.ts
+var import_ulid2 = require("ulid");
+
 // src/lib/lifecycle-manager/component-lifecycle.ts
 var ComponentLifecycle = class {
   manager;
@@ -1965,6 +1968,7 @@ var LifecycleManager = class extends EventEmitterProtected {
   messageTimeoutMS;
   startupTimeoutMS;
   shutdownOptions;
+  attachSignalsBeforeStartup;
   attachSignalsOnStart;
   detachSignalsOnStop;
   // Component management
@@ -1975,10 +1979,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 = (0, import_ulid2.ulid)();
+  // Resolver for the first logger.exit() deferred during an already-running shutdown.
+  pendingLoggerExitResolve = null;
   shutdownMethod = null;
   lastShutdownResult = null;
   // Signal management
@@ -2004,6 +2013,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;
@@ -2167,6 +2177,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();
@@ -2575,6 +2586,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;
@@ -2688,6 +2700,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", {
@@ -2776,6 +2800,9 @@ var LifecycleManager = class extends EventEmitterProtected {
       if (timeoutHandle) {
         clearTimeout(timeoutHandle);
       }
+      if (didAutoAttachSignalsForBulkStartup) {
+        this.autoDetachSignalsIfIdle("failed bulk startup");
+      }
       this.isStarting = false;
     }
   }
@@ -3020,6 +3047,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 }
           });
@@ -3843,6 +3881,7 @@ var LifecycleManager = class extends EventEmitterProtected {
         stoppedAt: null
       });
       this.componentErrors.set(componentName, null);
+      this.componentStartAttemptTokens.set(componentName, (0, import_ulid2.ulid)());
       const isManualPositionRespected = this.isManualPositionRespected({
         componentName,
         position,
@@ -3994,6 +4033,7 @@ var LifecycleManager = class extends EventEmitterProtected {
       };
     }
     this.isShuttingDown = true;
+    this.shutdownToken = (0, import_ulid2.ulid)();
     this.shutdownMethod = method;
     const isDuringStartup = this.isStarting;
     this.logger.info("Stopping all components", { params: { method } });
@@ -4123,7 +4163,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.
@@ -4264,6 +4316,10 @@ var LifecycleManager = class extends EventEmitterProtected {
     this.logger.entity(name).info("Starting component");
     this.lifecycleEvents.componentStarting(name);
     const timeoutMS = component.startupTimeoutMS;
+    const startAttemptToken = (0, import_ulid2.ulid)();
+    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();
@@ -4278,6 +4334,13 @@ var LifecycleManager = class extends EventEmitterProtected {
                   params: { error }
                 });
               }
+            } else {
+              this.monitorLateStartupCompletion(
+                name,
+                component,
+                startPromise,
+                startAttemptToken
+              );
             }
             Promise.resolve(startPromise).catch(() => {
             });
@@ -4293,15 +4356,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,
@@ -4350,6 +4434,9 @@ var LifecycleManager = class extends EventEmitterProtected {
       if (timeoutHandle) {
         clearTimeout(timeoutHandle);
       }
+      if (didAutoAttachSignalsForComponentStartup) {
+        this.autoDetachSignalsIfIdle("failed component startup");
+      }
     }
   }
   /**
@@ -4846,6 +4933,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
    */