@catbee/utils 2.2.0 → 2.2.1

package/healthz-server/index.cjs

@@ -67,8 +67,10 @@ var HealthzServer = class _HealthzServer {
   server;
   config;
   startedAt = Date.now();
-  /** Whether the health server has successfully started listening (for `/startupz`) */
-  started = false;
+  /** Whether the health HTTP server is currently running and listening on its port */
+  running = false;
+  /** Whether application startup has completed (for `/startupz`) */
+  startupComplete = false;
   /** Whether the service is ready to receive traffic (for `/readyz`) */
   ready = false;
   shuttingDown = false;
@@ -109,7 +111,7 @@ var HealthzServer = class _HealthzServer {
         port: config.port
       }, () => {
         instance.server.off("error", onError);
-        instance.started = true;
+        instance.running = true;
         const addr = instance.server.address();
         if (!addr || typeof addr === "string") {
           instance.cleanup();
@@ -125,9 +127,19 @@ var HealthzServer = class _HealthzServer {
       });
     });
   }
-  /** Whether the health-check server is currently running and started. */
-  static isStarted() {
-    return _global[SINGLETON_KEY]?.started ?? false;
+  /** Whether the Healthz HTTP probe server is currently running and listening on its port. */
+  static isRunning() {
+    return _global[SINGLETON_KEY]?.running ?? false;
+  }
+  /** Mark application startup as completed (switches `/startupz` to 200). */
+  static markStartupComplete() {
+    const instance = _global[SINGLETON_KEY];
+    if (!instance) return;
+    instance.startupComplete = true;
+  }
+  /** Whether application startup has completed (for `/startupz`). */
+  static isStartupComplete() {
+    return _global[SINGLETON_KEY]?.startupComplete ?? false;
   }
   /** Mark the service as ready / not-ready for traffic. */
   static setReady(ready) {
@@ -288,7 +300,7 @@ var HealthzServer = class _HealthzServer {
   }
   /** `/startupz` — Startup probe */
   handleStartup(res, isHead = false) {
-    if (this.started) {
+    if (this.startupComplete) {
       this.sendProbe(res, 200, "ok", [], isHead);
     } else {
       this.sendProbe(res, 503, "unhealthy", [
@@ -296,7 +308,7 @@ var HealthzServer = class _HealthzServer {
           name: "startup",
           ok: false,
           durationMs: 0,
-          error: "Service has not started yet"
+          error: "Application startup not complete"
         }
       ], isHead);
     }
@@ -383,7 +395,8 @@ var HealthzServer = class _HealthzServer {
     process.off("SIGTERM", this.onSigterm);
     process.off("SIGINT", this.onSigint);
     this.ready = false;
-    this.started = false;
+    this.startupComplete = false;
+    this.running = false;
     this.shuttingDown = false;
   }
 };

package/healthz-server/index.d.ts

@@ -219,7 +219,7 @@ declare function resolveConfig(userConfig?: CatbeeHealthzServerConfig): Resolved
  * |-----------|-------------|------------------|-----------|
  * | Liveness  | `/healthz`  | `livenessProbe`  | Runs configured checks; 200 = alive, 503 = unhealthy |
  * | Readiness | `/readyz`   | `readinessProbe` | Checks readiness flag + readiness checks; 503 while not ready |
- * | Startup   | `/startupz` | `startupProbe`   | 200 once the server has successfully started listening; 503 before that |
+ * | Startup   | `/startupz` | `startupProbe`   | 200 once application startup completes (`markStartupComplete()`); 503 while booting |
  *
  * ### Kubernetes Probe Best Practices:
  * - **Liveness (`/healthz`)**: Keep these checks extremely lightweight (e.g. process is responsive,
@@ -229,7 +229,8 @@ declare function resolveConfig(userConfig?: CatbeeHealthzServerConfig): Resolved
  * - **Readiness (`/readyz`)**: Place external dependency checks (DB, Redis, downstream APIs) here via
  *   `readinessChecks`. If a dependency fails, Kubernetes temporarily pulls the pod from service endpoints
  *   without restarting the container, allowing it to recover gracefully.
- * - **Startup (`/startupz`)**: Verifies the health server process has started listening.
+ * - **Startup (`/startupz`)**: Verifies the application has completed its startup sequence
+ *   (signaled via `markStartupComplete()`). Protects slow-starting applications from premature liveness kills.
  *
  * @example
  * ```ts
@@ -237,11 +238,9 @@ declare function resolveConfig(userConfig?: CatbeeHealthzServerConfig): Resolved
  *
  * const addr = await HealthzServer.start({
  *   port: 8282,
- *   // Keep liveness lightweight:
  *   checks: [
  *     { name: 'process', check: () => true },
  *   ],
- *   // Place dependency checks on readiness:
  *   readinessChecks: [
  *     { name: 'database', check: (signal) => db.ping({ signal }) },
  *     { name: 'redis',    check: (signal) => redis.ping({ signal }) },
@@ -249,6 +248,9 @@ declare function resolveConfig(userConfig?: CatbeeHealthzServerConfig): Resolved
  *   shutdownDelayMs: 10_000,
  * });
  *
+ * // Signal application startup complete (switches /startupz to 200):
+ * HealthzServer.markStartupComplete();
+ *
  * // Signal readiness after all background services and migrations are ready:
  * HealthzServer.setReady(true);
  * ```
@@ -257,8 +259,10 @@ declare class HealthzServer {
     private readonly server;
     private readonly config;
     private readonly startedAt;
-    /** Whether the health server has successfully started listening (for `/startupz`) */
-    private started;
+    /** Whether the health HTTP server is currently running and listening on its port */
+    private running;
+    /** Whether application startup has completed (for `/startupz`) */
+    private startupComplete;
     /** Whether the service is ready to receive traffic (for `/readyz`) */
     private ready;
     private shuttingDown;
@@ -274,8 +278,12 @@ declare class HealthzServer {
      * Returns `null` if a server is already running in this process.
      */
     static start(opts?: CatbeeHealthzServerConfig): Promise<HealthzAddressInfo | null>;
-    /** Whether the health-check server is currently running and started. */
-    static isStarted(): boolean;
+    /** Whether the Healthz HTTP probe server is currently running and listening on its port. */
+    static isRunning(): boolean;
+    /** Mark application startup as completed (switches `/startupz` to 200). */
+    static markStartupComplete(): void;
+    /** Whether application startup has completed (for `/startupz`). */
+    static isStartupComplete(): boolean;
     /** Mark the service as ready / not-ready for traffic. */
     static setReady(ready: boolean): void;
     /** Whether the service is currently marked as ready. */

package/healthz-server/index.mjs

@@ -65,8 +65,10 @@ var HealthzServer = class _HealthzServer {
   server;
   config;
   startedAt = Date.now();
-  /** Whether the health server has successfully started listening (for `/startupz`) */
-  started = false;
+  /** Whether the health HTTP server is currently running and listening on its port */
+  running = false;
+  /** Whether application startup has completed (for `/startupz`) */
+  startupComplete = false;
   /** Whether the service is ready to receive traffic (for `/readyz`) */
   ready = false;
   shuttingDown = false;
@@ -107,7 +109,7 @@ var HealthzServer = class _HealthzServer {
         port: config.port
       }, () => {
         instance.server.off("error", onError);
-        instance.started = true;
+        instance.running = true;
         const addr = instance.server.address();
         if (!addr || typeof addr === "string") {
           instance.cleanup();
@@ -123,9 +125,19 @@ var HealthzServer = class _HealthzServer {
       });
     });
   }
-  /** Whether the health-check server is currently running and started. */
-  static isStarted() {
-    return _global[SINGLETON_KEY]?.started ?? false;
+  /** Whether the Healthz HTTP probe server is currently running and listening on its port. */
+  static isRunning() {
+    return _global[SINGLETON_KEY]?.running ?? false;
+  }
+  /** Mark application startup as completed (switches `/startupz` to 200). */
+  static markStartupComplete() {
+    const instance = _global[SINGLETON_KEY];
+    if (!instance) return;
+    instance.startupComplete = true;
+  }
+  /** Whether application startup has completed (for `/startupz`). */
+  static isStartupComplete() {
+    return _global[SINGLETON_KEY]?.startupComplete ?? false;
   }
   /** Mark the service as ready / not-ready for traffic. */
   static setReady(ready) {
@@ -286,7 +298,7 @@ var HealthzServer = class _HealthzServer {
   }
   /** `/startupz` — Startup probe */
   handleStartup(res, isHead = false) {
-    if (this.started) {
+    if (this.startupComplete) {
       this.sendProbe(res, 200, "ok", [], isHead);
     } else {
       this.sendProbe(res, 503, "unhealthy", [
@@ -294,7 +306,7 @@ var HealthzServer = class _HealthzServer {
           name: "startup",
           ok: false,
           durationMs: 0,
-          error: "Service has not started yet"
+          error: "Application startup not complete"
         }
       ], isHead);
     }
@@ -381,7 +393,8 @@ var HealthzServer = class _HealthzServer {
     process.off("SIGTERM", this.onSigterm);
     process.off("SIGINT", this.onSigint);
     this.ready = false;
-    this.started = false;
+    this.startupComplete = false;
+    this.running = false;
     this.shuttingDown = false;
   }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catbee/utils",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "description": "A modular, production-grade utility toolkit for Node.js and TypeScript, designed for robust, scalable applications (including Express-based services). All utilities are tree-shakable and can be imported independently.",
   "publishConfig": {
     "access": "public"

package/server/index.cjs

@@ -1230,6 +1230,21 @@ var ExpressServer = class {
     return healthzServer.HealthzServer.isReady();
   }
   /**
+  * Mark application startup as completed on the Healthz probe server (switches `/startupz` to 200).
+  *
+  * @returns This instance for method chaining
+  */
+  markStartupComplete() {
+    healthzServer.HealthzServer.markStartupComplete();
+    return this;
+  }
+  /**
+  * Whether application startup has completed on the Healthz probe server.
+  */
+  isStartupComplete() {
+    return healthzServer.HealthzServer.isStartupComplete();
+  }
+  /**
   * Get the running HealthzServer instance (if started).
   */
   getHealthzServer() {
@@ -1305,92 +1320,105 @@ var ExpressServer = class {
   */
   async doStart() {
     await this.initPromise;
-    await this.runHook("beforeStart", this.app);
-    const server = this.createServerInstance();
-    this.server = server;
-    return new Promise((resolve, reject) => {
-      let isListening = false;
-      server.on("error", (err) => {
-        if (!isListening) {
-          logger.getLogger().error({
-            err
-          }, "Server failed to start");
-          try {
-            server.removeAllListeners();
-            server.close();
-            if (healthzServer.HealthzServer.isStarted()) {
-              healthzServer.HealthzServer.stop().catch(() => {
-              });
-            }
-          } catch {
-          }
-          this.server = null;
-          this.connections.clear();
-          reject(err);
-        } else {
-          logger.getLogger().error({
-            err
-          }, "Server runtime error");
-        }
-      });
-      this.setupConnectionTracking();
-      Promise.resolve(this.runHook("onServerCreated", server)).then(() => {
-        const onListening = /* @__PURE__ */ __name(async () => {
-          try {
-            if (this.isHealthzServerEnabled()) {
-              const healthzConfig = {
-                ...typeof this.config.healthzServer === "object" ? this.config.healthzServer : {},
-                handleSignals: false,
-                checks: [
-                  ...this.healthzChecks
-                ],
-                readinessChecks: [
-                  ...this.healthzReadinessChecks
-                ]
-              };
-              const addr = await healthzServer.HealthzServer.start(healthzConfig);
-              if (!addr) {
-                throw new Error("Healthz probe server failed to start (already running in this process)");
-              }
-              this.healthzAddress = addr;
-            }
-            this.logServerStartInfo();
-            await this.runHook("afterStart", server);
-            if (this.isHealthzServerEnabled()) {
-              healthzServer.HealthzServer.setReady(true);
-            }
-            isListening = true;
-            resolve(server);
-          } catch (err) {
-            const error = err instanceof Error ? err : new Error(String(err));
+    if (this.isHealthzServerEnabled()) {
+      const healthzConfig = {
+        ...typeof this.config.healthzServer === "object" ? this.config.healthzServer : {},
+        handleSignals: false,
+        checks: [
+          ...this.healthzChecks
+        ],
+        readinessChecks: [
+          ...this.healthzReadinessChecks
+        ]
+      };
+      const addr = await healthzServer.HealthzServer.start(healthzConfig);
+      if (!addr) {
+        throw new Error("Healthz probe server failed to start (already running in this process)");
+      }
+      this.healthzAddress = addr;
+    }
+    try {
+      await this.runHook("beforeStart", this.app);
+      const server = this.createServerInstance();
+      this.server = server;
+      return await new Promise((resolve, reject) => {
+        let isListening = false;
+        server.on("error", async (err) => {
+          if (!isListening) {
             logger.getLogger().error({
-              err: error
-            }, "Server startup failed");
-            if (healthzServer.HealthzServer.isStarted()) {
-              await healthzServer.HealthzServer.stop().catch(() => {
-              });
-            }
+              err
+            }, "Server failed to start");
             try {
               server.removeAllListeners();
               server.close();
+              if (healthzServer.HealthzServer.isRunning()) {
+                await healthzServer.HealthzServer.stop().catch(() => {
+                });
+              }
             } catch {
             }
             this.server = null;
             this.healthzAddress = null;
             this.connections.clear();
-            reject(error);
+            reject(err);
+          } else {
+            logger.getLogger().error({
+              err
+            }, "Server runtime error");
           }
-        }, "onListening");
-        const listenArgs = [
-          this.config.port,
-          this.config.host,
-          onListening
-        ];
-        server.listen(...listenArgs);
-      }).catch((err) => {
-        server.emit("error", err instanceof Error ? err : new Error(String(err)));
+        });
+        this.setupConnectionTracking();
+        Promise.resolve(this.runHook("onServerCreated", server)).then(() => {
+          const onListening = /* @__PURE__ */ __name(async () => {
+            try {
+              this.logServerStartInfo();
+              await this.runHook("afterStart", server);
+              if (this.isHealthzServerEnabled()) {
+                healthzServer.HealthzServer.markStartupComplete();
+                healthzServer.HealthzServer.setReady(true);
+              }
+              isListening = true;
+              resolve(server);
+            } catch (err) {
+              const error = err instanceof Error ? err : new Error(String(err));
+              logger.getLogger().error({
+                err: error
+              }, "Server startup failed");
+              if (healthzServer.HealthzServer.isRunning()) {
+                await healthzServer.HealthzServer.stop().catch(() => {
+                });
+              }
+              try {
+                server.removeAllListeners();
+                server.close();
+              } catch {
+              }
+              this.server = null;
+              this.healthzAddress = null;
+              this.connections.clear();
+              reject(error);
+            }
+          }, "onListening");
+          const listenArgs = [
+            this.config.port,
+            this.config.host,
+            onListening
+          ];
+          server.listen(...listenArgs);
+        }).catch((err) => {
+          server.emit("error", err instanceof Error ? err : new Error(String(err)));
+        });
       });
-    });
+    } catch (err) {
+      if (healthzServer.HealthzServer.isRunning()) {
+        await healthzServer.HealthzServer.stop().catch(() => {
+        });
+      }
+      this.healthzAddress = null;
+      this.server = null;
+      this.connections.clear();
+      throw err;
+    }
   }
   /**
   * Create HTTP or HTTPS server instance (without listening).
@@ -1454,7 +1482,7 @@ var ExpressServer = class {
   * - Monitoring systems are notified
   */
   async stop(force = false) {
-    if (!this.server && !healthzServer.HealthzServer.isStarted()) {
+    if (!this.server && !healthzServer.HealthzServer.isRunning()) {
       logger.getLogger().warn("Stop called but server is not running");
       return;
     }
@@ -1463,7 +1491,7 @@ var ExpressServer = class {
       return;
     }
     this.isShuttingDown = true;
-    if (healthzServer.HealthzServer.isStarted()) {
+    if (healthzServer.HealthzServer.isRunning()) {
       healthzServer.HealthzServer.setReady(false);
     }
     if (this.server) {
@@ -1471,7 +1499,7 @@ var ExpressServer = class {
     }
     try {
       const shutdownDelay = this.getHealthzShutdownDelay();
-      if (shutdownDelay > 0 && !force && healthzServer.HealthzServer.isStarted()) {
+      if (shutdownDelay > 0 && !force && healthzServer.HealthzServer.isRunning()) {
         logger.getLogger().info(`Waiting ${shutdownDelay}ms for load balancer to drain traffic...`);
         await new Promise((resolve) => setTimeout(resolve, shutdownDelay));
       }
@@ -1479,7 +1507,7 @@ var ExpressServer = class {
         await this.gracefulShutdown(force);
       }
     } finally {
-      if (healthzServer.HealthzServer.isStarted()) {
+      if (healthzServer.HealthzServer.isRunning()) {
         await healthzServer.HealthzServer.stop();
         this.healthzAddress = null;
       }

package/server/index.d.ts

@@ -237,6 +237,16 @@ declare class ExpressServer {
      * Whether the service is currently marked as ready for traffic on the Healthz probe server.
      */
     isReady(): boolean;
+    /**
+     * Mark application startup as completed on the Healthz probe server (switches `/startupz` to 200).
+     *
+     * @returns This instance for method chaining
+     */
+    markStartupComplete(): this;
+    /**
+     * Whether application startup has completed on the Healthz probe server.
+     */
+    isStartupComplete(): boolean;
     /**
      * Get the running HealthzServer instance (if started).
      */

package/server/index.mjs

@@ -1222,6 +1222,21 @@ var ExpressServer = class {
     return HealthzServer.isReady();
   }
   /**
+  * Mark application startup as completed on the Healthz probe server (switches `/startupz` to 200).
+  *
+  * @returns This instance for method chaining
+  */
+  markStartupComplete() {
+    HealthzServer.markStartupComplete();
+    return this;
+  }
+  /**
+  * Whether application startup has completed on the Healthz probe server.
+  */
+  isStartupComplete() {
+    return HealthzServer.isStartupComplete();
+  }
+  /**
   * Get the running HealthzServer instance (if started).
   */
   getHealthzServer() {
@@ -1297,92 +1312,105 @@ var ExpressServer = class {
   */
   async doStart() {
     await this.initPromise;
-    await this.runHook("beforeStart", this.app);
-    const server = this.createServerInstance();
-    this.server = server;
-    return new Promise((resolve, reject) => {
-      let isListening = false;
-      server.on("error", (err) => {
-        if (!isListening) {
-          getLogger().error({
-            err
-          }, "Server failed to start");
-          try {
-            server.removeAllListeners();
-            server.close();
-            if (HealthzServer.isStarted()) {
-              HealthzServer.stop().catch(() => {
-              });
-            }
-          } catch {
-          }
-          this.server = null;
-          this.connections.clear();
-          reject(err);
-        } else {
-          getLogger().error({
-            err
-          }, "Server runtime error");
-        }
-      });
-      this.setupConnectionTracking();
-      Promise.resolve(this.runHook("onServerCreated", server)).then(() => {
-        const onListening = /* @__PURE__ */ __name(async () => {
-          try {
-            if (this.isHealthzServerEnabled()) {
-              const healthzConfig = {
-                ...typeof this.config.healthzServer === "object" ? this.config.healthzServer : {},
-                handleSignals: false,
-                checks: [
-                  ...this.healthzChecks
-                ],
-                readinessChecks: [
-                  ...this.healthzReadinessChecks
-                ]
-              };
-              const addr = await HealthzServer.start(healthzConfig);
-              if (!addr) {
-                throw new Error("Healthz probe server failed to start (already running in this process)");
-              }
-              this.healthzAddress = addr;
-            }
-            this.logServerStartInfo();
-            await this.runHook("afterStart", server);
-            if (this.isHealthzServerEnabled()) {
-              HealthzServer.setReady(true);
-            }
-            isListening = true;
-            resolve(server);
-          } catch (err) {
-            const error = err instanceof Error ? err : new Error(String(err));
+    if (this.isHealthzServerEnabled()) {
+      const healthzConfig = {
+        ...typeof this.config.healthzServer === "object" ? this.config.healthzServer : {},
+        handleSignals: false,
+        checks: [
+          ...this.healthzChecks
+        ],
+        readinessChecks: [
+          ...this.healthzReadinessChecks
+        ]
+      };
+      const addr = await HealthzServer.start(healthzConfig);
+      if (!addr) {
+        throw new Error("Healthz probe server failed to start (already running in this process)");
+      }
+      this.healthzAddress = addr;
+    }
+    try {
+      await this.runHook("beforeStart", this.app);
+      const server = this.createServerInstance();
+      this.server = server;
+      return await new Promise((resolve, reject) => {
+        let isListening = false;
+        server.on("error", async (err) => {
+          if (!isListening) {
             getLogger().error({
-              err: error
-            }, "Server startup failed");
-            if (HealthzServer.isStarted()) {
-              await HealthzServer.stop().catch(() => {
-              });
-            }
+              err
+            }, "Server failed to start");
             try {
               server.removeAllListeners();
               server.close();
+              if (HealthzServer.isRunning()) {
+                await HealthzServer.stop().catch(() => {
+                });
+              }
             } catch {
             }
             this.server = null;
             this.healthzAddress = null;
             this.connections.clear();
-            reject(error);
+            reject(err);
+          } else {
+            getLogger().error({
+              err
+            }, "Server runtime error");
           }
-        }, "onListening");
-        const listenArgs = [
-          this.config.port,
-          this.config.host,
-          onListening
-        ];
-        server.listen(...listenArgs);
-      }).catch((err) => {
-        server.emit("error", err instanceof Error ? err : new Error(String(err)));
+        });
+        this.setupConnectionTracking();
+        Promise.resolve(this.runHook("onServerCreated", server)).then(() => {
+          const onListening = /* @__PURE__ */ __name(async () => {
+            try {
+              this.logServerStartInfo();
+              await this.runHook("afterStart", server);
+              if (this.isHealthzServerEnabled()) {
+                HealthzServer.markStartupComplete();
+                HealthzServer.setReady(true);
+              }
+              isListening = true;
+              resolve(server);
+            } catch (err) {
+              const error = err instanceof Error ? err : new Error(String(err));
+              getLogger().error({
+                err: error
+              }, "Server startup failed");
+              if (HealthzServer.isRunning()) {
+                await HealthzServer.stop().catch(() => {
+                });
+              }
+              try {
+                server.removeAllListeners();
+                server.close();
+              } catch {
+              }
+              this.server = null;
+              this.healthzAddress = null;
+              this.connections.clear();
+              reject(error);
+            }
+          }, "onListening");
+          const listenArgs = [
+            this.config.port,
+            this.config.host,
+            onListening
+          ];
+          server.listen(...listenArgs);
+        }).catch((err) => {
+          server.emit("error", err instanceof Error ? err : new Error(String(err)));
+        });
       });
-    });
+    } catch (err) {
+      if (HealthzServer.isRunning()) {
+        await HealthzServer.stop().catch(() => {
+        });
+      }
+      this.healthzAddress = null;
+      this.server = null;
+      this.connections.clear();
+      throw err;
+    }
   }
   /**
   * Create HTTP or HTTPS server instance (without listening).
@@ -1446,7 +1474,7 @@ var ExpressServer = class {
   * - Monitoring systems are notified
   */
   async stop(force = false) {
-    if (!this.server && !HealthzServer.isStarted()) {
+    if (!this.server && !HealthzServer.isRunning()) {
       getLogger().warn("Stop called but server is not running");
       return;
     }
@@ -1455,7 +1483,7 @@ var ExpressServer = class {
       return;
     }
     this.isShuttingDown = true;
-    if (HealthzServer.isStarted()) {
+    if (HealthzServer.isRunning()) {
       HealthzServer.setReady(false);
     }
     if (this.server) {
@@ -1463,7 +1491,7 @@ var ExpressServer = class {
     }
     try {
       const shutdownDelay = this.getHealthzShutdownDelay();
-      if (shutdownDelay > 0 && !force && HealthzServer.isStarted()) {
+      if (shutdownDelay > 0 && !force && HealthzServer.isRunning()) {
         getLogger().info(`Waiting ${shutdownDelay}ms for load balancer to drain traffic...`);
         await new Promise((resolve) => setTimeout(resolve, shutdownDelay));
       }
@@ -1471,7 +1499,7 @@ var ExpressServer = class {
         await this.gracefulShutdown(force);
       }
     } finally {
-      if (HealthzServer.isStarted()) {
+      if (HealthzServer.isRunning()) {
         await HealthzServer.stop();
         this.healthzAddress = null;
       }