@catbee/utils 2.1.1 → 2.2.0

package/README.md

@@ -55,7 +55,7 @@ const config = new ServerConfigBuilder()
   .withCors({ origin: '*' })
   .enableRateLimit({ max: 50, windowMs: 60000 })
   .enableRequestLogging({ ignorePaths: ['/healthz', '/metrics'] })
-  .withHealthCheck({ path: '/health', detailed: true })
+  .enableHealthzServer({ port: 8282 })
   .enableOpenApi('./openapi.yaml', { mountPath: '/docs' })
   .withGlobalHeaders({ 'X-Powered-By': 'Catbee' })
   .withGlobalPrefix('/api')

package/config/index.cjs

@@ -27,6 +27,7 @@
 var env = require('@catbee/utils/env');
 var id = require('@catbee/utils/id');
 var object = require('@catbee/utils/object');
+var healthzServer = require('@catbee/utils/healthz-server');
 
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
@@ -78,10 +79,9 @@ var defaultServerConfig = {
     verbose: env.Env.getBoolean("SERVER_OPENAPI_VERBOSE", false),
     withGlobalPrefix: env.Env.getBoolean("SERVER_OPENAPI_WITH_GLOBAL_PREFIX", false)
   },
-  healthCheck: {
-    path: env.Env.get("SERVER_HEALTH_CHECK_PATH", "/healthz"),
-    detailed: env.Env.getBoolean("SERVER_HEALTH_CHECK_DETAILED_OUTPUT", true),
-    withGlobalPrefix: env.Env.getBoolean("SERVER_HEALTH_CHECK_WITH_GLOBAL_PREFIX", false)
+  healthzServer: {
+    enable: env.Env.getBoolean("SERVER_HEALTHZ_ENABLE", env.Env.getBoolean("HEALTHZ_ENABLE", false)),
+    ...healthzServer.getDefaultHealthzConfig()
   },
   requestTimeout: env.Env.getDuration("SERVER_REQUEST_TIMEOUT_MS", 0),
   responseTime: {
@@ -98,8 +98,7 @@ var defaultServerConfig = {
     enable: env.Env.getBoolean("SERVER_SERVICE_VERSION_ENABLE", false),
     headerName: env.Env.get("SERVER_SERVICE_VERSION_HEADER_NAME", "x-service-version"),
     version: env.Env.get("${npm_package_version}", "0.0.0")
-  },
-  skipHealthzChecksValidation: env.Env.getBoolean("SERVER_SKIP_HEALTHZ_CHECKS_VALIDATION", false)
+  }
 };
 var defaultCatbeeConfig = {
   logger: {

package/config/index.mjs

@@ -25,6 +25,7 @@
 import { Env } from '@catbee/utils/env';
 import { uuid } from '@catbee/utils/id';
 import { deepClone, deepObjMerge } from '@catbee/utils/object';
+import { getDefaultHealthzConfig } from '@catbee/utils/healthz-server';
 
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
@@ -76,10 +77,9 @@ var defaultServerConfig = {
     verbose: Env.getBoolean("SERVER_OPENAPI_VERBOSE", false),
     withGlobalPrefix: Env.getBoolean("SERVER_OPENAPI_WITH_GLOBAL_PREFIX", false)
   },
-  healthCheck: {
-    path: Env.get("SERVER_HEALTH_CHECK_PATH", "/healthz"),
-    detailed: Env.getBoolean("SERVER_HEALTH_CHECK_DETAILED_OUTPUT", true),
-    withGlobalPrefix: Env.getBoolean("SERVER_HEALTH_CHECK_WITH_GLOBAL_PREFIX", false)
+  healthzServer: {
+    enable: Env.getBoolean("SERVER_HEALTHZ_ENABLE", Env.getBoolean("HEALTHZ_ENABLE", false)),
+    ...getDefaultHealthzConfig()
   },
   requestTimeout: Env.getDuration("SERVER_REQUEST_TIMEOUT_MS", 0),
   responseTime: {
@@ -96,8 +96,7 @@ var defaultServerConfig = {
     enable: Env.getBoolean("SERVER_SERVICE_VERSION_ENABLE", false),
     headerName: Env.get("SERVER_SERVICE_VERSION_HEADER_NAME", "x-service-version"),
     version: Env.get("${npm_package_version}", "0.0.0")
-  },
-  skipHealthzChecksValidation: Env.getBoolean("SERVER_SKIP_HEALTHZ_CHECKS_VALIDATION", false)
+  }
 };
 var defaultCatbeeConfig = {
   logger: {

package/healthz-server/index.cjs

@@ -36,10 +36,11 @@ function getDefaultHealthzConfig() {
     healthzPath: env.Env.get("HEALTHZ_PATH", "") || env.Env.get("SERVER_HEALTHZ_PATH", "") || env.Env.get("SERVER_HEALTH_CHECK_PATH", "/healthz"),
     readyzPath: env.Env.get("HEALTHZ_READYZ_PATH", "") || env.Env.get("SERVER_READYZ_PATH", "/readyz"),
     startupzPath: env.Env.get("HEALTHZ_STARTUPZ_PATH", "") || env.Env.get("SERVER_STARTUPZ_PATH", "/startupz"),
-    detailed: env.Env.getBoolean("HEALTHZ_DETAILED", env.Env.getBoolean("SERVER_HEALTH_CHECK_DETAILED_OUTPUT", true)),
+    detailed: env.Env.getBoolean("HEALTHZ_DETAILED", env.Env.getBoolean("SERVER_HEALTHZ_DETAILED", env.Env.getBoolean("SERVER_HEALTH_CHECK_DETAILED_OUTPUT", true))),
     checks: [],
-    checkTimeoutMs: env.Env.getDuration("HEALTHZ_CHECK_TIMEOUT_MS", 5e3),
-    shutdownDelayMs: env.Env.getDuration("HEALTHZ_SHUTDOWN_DELAY_MS", 5e3)
+    checkTimeoutMs: env.Env.getDuration("HEALTHZ_CHECK_TIMEOUT_MS", env.Env.getDuration("SERVER_HEALTHZ_CHECK_TIMEOUT_MS", 5e3)),
+    shutdownDelayMs: env.Env.getDuration("HEALTHZ_SHUTDOWN_DELAY_MS", env.Env.getDuration("SERVER_HEALTHZ_SHUTDOWN_DELAY_MS", 5e3)),
+    handleSignals: true
   };
 }
 __name(getDefaultHealthzConfig, "getDefaultHealthzConfig");
@@ -76,8 +77,16 @@ var HealthzServer = class _HealthzServer {
   constructor(config) {
     this.config = config;
     this.server = http.createServer((req, res) => this.handleRequest(req, res));
-    process.once("SIGTERM", this.onSigterm);
-    process.once("SIGINT", this.onSigint);
+    if (this.config.handleSignals !== false) {
+      process.once("SIGTERM", this.onSigterm);
+      process.once("SIGINT", this.onSigint);
+    }
+  }
+  /**
+  * Returns default Healthz server configuration resolved from environment variables.
+  */
+  static getDefaultConfig() {
+    return getDefaultHealthzConfig();
   }
   /**
   * Boot the health-check server.
@@ -148,6 +157,34 @@ var HealthzServer = class _HealthzServer {
   static getInstance() {
     return _global[SINGLETON_KEY];
   }
+  /**
+  * Register a named check on this HealthzServer instance dynamically.
+  *
+  * @param check - The named check to register
+  * @param type - Which probe to attach this check to ('readiness', 'liveness', or 'both')
+  * @returns This instance for chaining
+  */
+  registerCheck(check, type = "readiness") {
+    if (type === "liveness" || type === "both") {
+      this.config.checks.push(check);
+    }
+    if (type === "readiness" || type === "both") {
+      this.config.readinessChecks ??= [
+        ...this.config.checks
+      ];
+      this.config.readinessChecks.push(check);
+    }
+    return this;
+  }
+  /**
+  * Register a named check on the active singleton HealthzServer instance (if started).
+  *
+  * @param check - The named check to register
+  * @param type - Which probe to attach this check to ('readiness', 'liveness', or 'both')
+  */
+  static registerCheck(check, type = "readiness") {
+    _global[SINGLETON_KEY]?.registerCheck(check, type);
+  }
   async handleRequest(req, res) {
     const isHead = req.method === "HEAD";
     if (req.method !== "GET" && !isHead) {

package/healthz-server/index.d.ts

@@ -169,6 +169,13 @@ interface CatbeeHealthzServerConfig {
      *  - **env**: `HEALTHZ_SHUTDOWN_DELAY_MS`
      */
     shutdownDelayMs?: number;
+    /**
+     * Whether the HealthzServer should register its own SIGTERM/SIGINT process signal listeners.
+     * When managed by an orchestrating server (such as Catbee ExpressServer), set this to `false`
+     * to prevent signal listener conflicts and allow coordinated teardown.
+     *  - **default**: `true`
+     */
+    handleSignals?: boolean;
 }
 /**
  * Address information returned after the server starts listening.
@@ -179,6 +186,29 @@ interface HealthzAddressInfo {
     port: number;
 }
 
+/**
+ * Resolved configuration with all defaults applied.
+ * Internal-only — consumers interact with `CatbeeHealthzServerConfig`.
+ *
+ * `readinessChecks` is kept as `NamedCheck[] | undefined` so that
+ * "omitted" (-> fall back to `checks`) is distinguishable from
+ * "explicitly empty" (-> run nothing).
+ */
+interface ResolvedHealthzConfig extends Required<Omit<CatbeeHealthzServerConfig, 'onHealthCheck' | 'onReadinessCheck' | 'readinessChecks'>> {
+    onHealthCheck?: CatbeeHealthzServerConfig['onHealthCheck'];
+    onReadinessCheck?: CatbeeHealthzServerConfig['onReadinessCheck'];
+    readinessChecks?: CatbeeHealthzServerConfig['readinessChecks'];
+}
+/**
+ * Loads default Healthz server configuration from environment variables.
+ */
+declare function getDefaultHealthzConfig(): ResolvedHealthzConfig;
+/**
+ * Merge user-supplied configuration with environment-resolved defaults.
+ * Undefined user values do not override resolved defaults.
+ */
+declare function resolveConfig(userConfig?: CatbeeHealthzServerConfig): ResolvedHealthzConfig;
+
 /**
  * Standalone HTTP health-check server designed for Kubernetes probes
  * and microservice orchestration.
@@ -235,6 +265,10 @@ declare class HealthzServer {
     private readonly onSigterm;
     private readonly onSigint;
     private constructor();
+    /**
+     * Returns default Healthz server configuration resolved from environment variables.
+     */
+    static getDefaultConfig(): ResolvedHealthzConfig;
     /**
      * Boot the health-check server.
      * Returns `null` if a server is already running in this process.
@@ -249,6 +283,21 @@ declare class HealthzServer {
     /** Gracefully stop the health-check server. */
     static stop(): Promise<void>;
     static getInstance(): HealthzServer | undefined;
+    /**
+     * Register a named check on this HealthzServer instance dynamically.
+     *
+     * @param check - The named check to register
+     * @param type - Which probe to attach this check to ('readiness', 'liveness', or 'both')
+     * @returns This instance for chaining
+     */
+    registerCheck(check: NamedCheck, type?: 'liveness' | 'readiness' | 'both'): this;
+    /**
+     * Register a named check on the active singleton HealthzServer instance (if started).
+     *
+     * @param check - The named check to register
+     * @param type - Which probe to attach this check to ('readiness', 'liveness', or 'both')
+     */
+    static registerCheck(check: NamedCheck, type?: 'liveness' | 'readiness' | 'both'): void;
     private handleRequest;
     /** `/healthz` — Liveness probe */
     private handleLiveness;
@@ -264,28 +313,5 @@ declare class HealthzServer {
     private cleanup;
 }
 
-/**
- * Resolved configuration with all defaults applied.
- * Internal-only — consumers interact with `CatbeeHealthzServerConfig`.
- *
- * `readinessChecks` is kept as `NamedCheck[] | undefined` so that
- * "omitted" (-> fall back to `checks`) is distinguishable from
- * "explicitly empty" (-> run nothing).
- */
-interface ResolvedHealthzConfig extends Required<Omit<CatbeeHealthzServerConfig, 'onHealthCheck' | 'onReadinessCheck' | 'readinessChecks'>> {
-    onHealthCheck?: CatbeeHealthzServerConfig['onHealthCheck'];
-    onReadinessCheck?: CatbeeHealthzServerConfig['onReadinessCheck'];
-    readinessChecks?: CatbeeHealthzServerConfig['readinessChecks'];
-}
-/**
- * Loads default Healthz server configuration from environment variables.
- */
-declare function getDefaultHealthzConfig(): ResolvedHealthzConfig;
-/**
- * Merge user-supplied configuration with environment-resolved defaults.
- * Undefined user values do not override resolved defaults.
- */
-declare function resolveConfig(userConfig?: CatbeeHealthzServerConfig): ResolvedHealthzConfig;
-
 export { HealthzServer, getDefaultHealthzConfig, resolveConfig };
 export type { CatbeeHealthzServerConfig, CheckResult, HealthCheckFn, HealthzAddressInfo, NamedCheck, ProbeResponse, ProbeStatus, ReadinessCheckFn, ResolvedHealthzConfig };

package/healthz-server/index.mjs

@@ -34,10 +34,11 @@ function getDefaultHealthzConfig() {
     healthzPath: Env.get("HEALTHZ_PATH", "") || Env.get("SERVER_HEALTHZ_PATH", "") || Env.get("SERVER_HEALTH_CHECK_PATH", "/healthz"),
     readyzPath: Env.get("HEALTHZ_READYZ_PATH", "") || Env.get("SERVER_READYZ_PATH", "/readyz"),
     startupzPath: Env.get("HEALTHZ_STARTUPZ_PATH", "") || Env.get("SERVER_STARTUPZ_PATH", "/startupz"),
-    detailed: Env.getBoolean("HEALTHZ_DETAILED", Env.getBoolean("SERVER_HEALTH_CHECK_DETAILED_OUTPUT", true)),
+    detailed: Env.getBoolean("HEALTHZ_DETAILED", Env.getBoolean("SERVER_HEALTHZ_DETAILED", Env.getBoolean("SERVER_HEALTH_CHECK_DETAILED_OUTPUT", true))),
     checks: [],
-    checkTimeoutMs: Env.getDuration("HEALTHZ_CHECK_TIMEOUT_MS", 5e3),
-    shutdownDelayMs: Env.getDuration("HEALTHZ_SHUTDOWN_DELAY_MS", 5e3)
+    checkTimeoutMs: Env.getDuration("HEALTHZ_CHECK_TIMEOUT_MS", Env.getDuration("SERVER_HEALTHZ_CHECK_TIMEOUT_MS", 5e3)),
+    shutdownDelayMs: Env.getDuration("HEALTHZ_SHUTDOWN_DELAY_MS", Env.getDuration("SERVER_HEALTHZ_SHUTDOWN_DELAY_MS", 5e3)),
+    handleSignals: true
   };
 }
 __name(getDefaultHealthzConfig, "getDefaultHealthzConfig");
@@ -74,8 +75,16 @@ var HealthzServer = class _HealthzServer {
   constructor(config) {
     this.config = config;
     this.server = createServer((req, res) => this.handleRequest(req, res));
-    process.once("SIGTERM", this.onSigterm);
-    process.once("SIGINT", this.onSigint);
+    if (this.config.handleSignals !== false) {
+      process.once("SIGTERM", this.onSigterm);
+      process.once("SIGINT", this.onSigint);
+    }
+  }
+  /**
+  * Returns default Healthz server configuration resolved from environment variables.
+  */
+  static getDefaultConfig() {
+    return getDefaultHealthzConfig();
   }
   /**
   * Boot the health-check server.
@@ -146,6 +155,34 @@ var HealthzServer = class _HealthzServer {
   static getInstance() {
     return _global[SINGLETON_KEY];
   }
+  /**
+  * Register a named check on this HealthzServer instance dynamically.
+  *
+  * @param check - The named check to register
+  * @param type - Which probe to attach this check to ('readiness', 'liveness', or 'both')
+  * @returns This instance for chaining
+  */
+  registerCheck(check, type = "readiness") {
+    if (type === "liveness" || type === "both") {
+      this.config.checks.push(check);
+    }
+    if (type === "readiness" || type === "both") {
+      this.config.readinessChecks ??= [
+        ...this.config.checks
+      ];
+      this.config.readinessChecks.push(check);
+    }
+    return this;
+  }
+  /**
+  * Register a named check on the active singleton HealthzServer instance (if started).
+  *
+  * @param check - The named check to register
+  * @param type - Which probe to attach this check to ('readiness', 'liveness', or 'both')
+  */
+  static registerCheck(check, type = "readiness") {
+    _global[SINGLETON_KEY]?.registerCheck(check, type);
+  }
   async handleRequest(req, res) {
     const isHead = req.method === "HEAD";
     if (req.method !== "GET" && !isHead) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catbee/utils",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "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"