lifecycleion 0.0.1 → 0.0.3

package/README.md

@@ -1,4 +1,4 @@
-# Lifecycleion v0.0.1
+# Lifecycleion v0.0.3
 
 [![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,13 @@ 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)();
   shutdownMethod = null;
   lastShutdownResult = null;
   // Signal management
@@ -2004,6 +2011,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 +2175,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 +2584,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;
@@ -2598,7 +2608,7 @@ var LifecycleManager = class extends EventEmitterProtected {
         const err = error;
         const code = err instanceof DependencyCycleError ? "dependency_cycle" : "unknown_error";
         this.logger.error("Failed to resolve startup order", {
-          params: { error: err.message }
+          params: { error: err }
         });
         return {
           success: false,
@@ -2688,10 +2698,22 @@ 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", {
-              params: { error: result.error?.message }
+              params: { error: result.error }
             });
             this.lifecycleEvents.componentStartFailedOptional(
               name,
@@ -2707,7 +2729,7 @@ var LifecycleManager = class extends EventEmitterProtected {
             });
           } else {
             this.logger.entity(name).error("Required component failed to start, rolling back", {
-              params: { error: result.error?.message }
+              params: { error: result.error }
             });
             await this.rollbackStartup(startedComponents);
             return {
@@ -2776,6 +2798,9 @@ var LifecycleManager = class extends EventEmitterProtected {
       if (timeoutHandle) {
         clearTimeout(timeoutHandle);
       }
+      if (didAutoAttachSignalsForBulkStartup) {
+        this.autoDetachSignalsIfIdle("failed bulk startup");
+      }
       this.isStarting = false;
     }
   }
@@ -3190,7 +3215,9 @@ var LifecycleManager = class extends EventEmitterProtected {
     } catch (error) {
       const durationMS = Date.now() - startTime;
       const err = error;
-      this.logger.entity(name).error("Health check failed", { params: { error: err.message } });
+      this.logger.entity(name).error("Health check failed", {
+        params: { error: err }
+      });
       this.lifecycleEvents.componentHealthCheckFailed(name, err);
       return {
         name,
@@ -3337,7 +3364,9 @@ var LifecycleManager = class extends EventEmitterProtected {
         result = component.onMessage(payload, from);
       } catch (error) {
         const err = error instanceof Error ? error : new Error(String(error));
-        this.logger.entity(componentName).error("Message handler failed", { params: { error: err, from } });
+        this.logger.entity(componentName).error("Message handler failed", {
+          params: { error: err, from }
+        });
         this.lifecycleEvents.componentMessageFailed(componentName, from, err, {
           timedOut: false,
           code: "error",
@@ -3770,7 +3799,7 @@ var LifecycleManager = class extends EventEmitterProtected {
           startupOrder2 = this.getStartupOrderInternal();
         } catch (error) {
           this.logger.warn("Failed to compute startup order in error handler", {
-            params: { error: error instanceof Error ? error.message : error }
+            params: { error }
           });
           startupOrder2 = [];
         }
@@ -3839,6 +3868,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,
@@ -3990,6 +4020,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 } });
@@ -4005,7 +4036,7 @@ var LifecycleManager = class extends EventEmitterProtected {
       this.logger.warn(
         "Could not resolve shutdown order, using registration order",
         {
-          params: { error: error.message }
+          params: { error }
         }
       );
       shutdownOrder = this.components.map((c) => c.getName()).reverse();
@@ -4063,7 +4094,7 @@ var LifecycleManager = class extends EventEmitterProtected {
             stoppedComponents.push(name);
           } else {
             this.logger.entity(name).error("Component failed to stop, continuing with others", {
-              params: { error: result2.error?.message }
+              params: { error: result2.error }
             });
             const stallInfo = this.stalledComponents.get(name);
             if (stallInfo) {
@@ -4260,6 +4291,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();
@@ -4274,6 +4309,13 @@ var LifecycleManager = class extends EventEmitterProtected {
                   params: { error }
                 });
               }
+            } else {
+              this.monitorLateStartupCompletion(
+                name,
+                component,
+                startPromise,
+                startAttemptToken
+              );
             }
             Promise.resolve(startPromise).catch(() => {
             });
@@ -4289,15 +4331,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,
@@ -4319,7 +4382,7 @@ var LifecycleManager = class extends EventEmitterProtected {
       if (err instanceof ComponentStartTimeoutError && err.additionalInfo.componentName === name) {
         this.componentStates.set(name, "starting-timed-out");
         this.logger.entity(name).error("Component startup timed out", {
-          params: { error: err.message }
+          params: { error: err }
         });
         this.lifecycleEvents.componentStartTimeout(name, err, {
           timeoutMS,
@@ -4328,7 +4391,7 @@ var LifecycleManager = class extends EventEmitterProtected {
       } else {
         this.componentStates.set(name, "registered");
         this.logger.entity(name).error("Component failed to start", {
-          params: { error: err.message }
+          params: { error: err }
         });
         this.lifecycleEvents.componentStartFailed(name, err, {
           reason: err.message
@@ -4346,6 +4409,9 @@ var LifecycleManager = class extends EventEmitterProtected {
       if (timeoutHandle) {
         clearTimeout(timeoutHandle);
       }
+      if (didAutoAttachSignalsForComponentStartup) {
+        this.autoDetachSignalsIfIdle("failed component startup");
+      }
     }
   }
   /**
@@ -4457,7 +4523,7 @@ var LifecycleManager = class extends EventEmitterProtected {
           this.lifecycleEvents.componentShutdownWarningCompleted(name);
         }).catch((error) => {
           this.logger.entity(name).warn("Shutdown warning phase failed", {
-            params: { error: error.message }
+            params: { error }
           });
         });
       }
@@ -4480,7 +4546,7 @@ var LifecycleManager = class extends EventEmitterProtected {
         }).catch((error) => {
           statuses.set(name, "rejected");
           this.logger.entity(name).warn("Shutdown warning phase failed", {
-            params: { error: error.message }
+            params: { error }
           });
         })
       );
@@ -4603,7 +4669,7 @@ var LifecycleManager = class extends EventEmitterProtected {
         };
       } else {
         this.logger.entity(name).warn("Graceful shutdown threw error", {
-          params: { error: err.message }
+          params: { error: err }
         });
         return {
           success: false,
@@ -4747,7 +4813,7 @@ var LifecycleManager = class extends EventEmitterProtected {
         this.lifecycleEvents.componentShutdownForceTimeout(name, timeoutMS);
       } else {
         this.logger.entity(name).error("Force shutdown failed - stalled", {
-          params: { error: err.message }
+          params: { error: err }
         });
       }
       this.lifecycleEvents.componentStalled(name, stallInfo, {
@@ -4836,12 +4902,63 @@ var LifecycleManager = class extends EventEmitterProtected {
       const result = await this.stopComponentInternal(name);
       if (!result.success) {
         this.logger.entity(name).warn("Failed to stop component during rollback, continuing", {
-          params: { error: result.error?.message }
+          params: { error: result.error }
         });
       }
     }
     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
    */
@@ -4860,7 +4977,7 @@ var LifecycleManager = class extends EventEmitterProtected {
       startupOrder = this.getStartupOrderInternal();
     } catch (error) {
       this.logger.warn("Failed to compute startup order in error handler", {
-        params: { error: error instanceof Error ? error.message : error }
+        params: { error }
       });
       startupOrder = [];
     }
@@ -4883,7 +5000,7 @@ var LifecycleManager = class extends EventEmitterProtected {
       startupOrder = this.getStartupOrderInternal();
     } catch (error) {
       this.logger.warn("Failed to compute startup order in error handler", {
-        params: { error: error instanceof Error ? error.message : error }
+        params: { error }
       });
       startupOrder = [];
     }