@catbee/utils 2.2.1 → 2.3.0

package/healthz-server/index.d.ts

@@ -26,28 +26,42 @@
  * A health check function that can be synchronous or asynchronous.
  * Receives an AbortSignal that is triggered when `checkTimeoutMs` is exceeded.
  *
- * > **Cancellation Note**: Cancellation is cooperative. The check function must listen to
- * > `signal.aborted` or pass `signal` to underlying asynchronous APIs (e.g. database drivers, `fetch`).
- * > Synchronous CPU-bound loops or operations that ignore `signal` cannot be forcibly stopped by JavaScript.
+ * > **Cancellation & Timeout Semantics**:
+ * > When `checkTimeoutMs` expires, the HTTP probe response immediately fast-fails with 503
+ * > and aborts the supplied `AbortSignal`.
+ * >
+ * > However, runtime cancellation in JavaScript is **strictly cooperative**. The probe server cannot
+ * > preemptively interrupt executing JavaScript or force-cancel asynchronous work that does not listen
+ * > to the signal. If a check executes asynchronous tasks without passing `signal`
+ * > (e.g., `await db.query(...)` without `{ signal }`), that task will continue running in the background.
+ * > To prevent background resource leaks, always pass `signal` to underlying drivers/clients
+ * > (e.g. `fetch(url, { signal })`, database clients, HTTP clients) or check `signal?.aborted`.
  *
- * - Return `true` (or resolve to true) to signal healthy.
+ * - Return `true` (or resolve to true, or resolve void without error) to signal healthy.
  * - Return `false` (or resolve to false) to signal unhealthy.
  * - Throw an error (or reject) to signal unhealthy with an error message.
  */
-type HealthCheckFn = (signal?: AbortSignal) => boolean | Promise<boolean>;
+type HealthCheckFn = (signal?: AbortSignal) => boolean | void | Promise<boolean | void>;
 /**
  * A readiness check function.
  * Receives an AbortSignal that is triggered when `checkTimeoutMs` is exceeded.
  *
- * > **Cancellation Note**: Cancellation is cooperative. The check function must listen to
- * > `signal.aborted` or pass `signal` to underlying asynchronous APIs (e.g. database drivers, `fetch`).
- * > Synchronous CPU-bound loops or operations that ignore `signal` cannot be forcibly stopped by JavaScript.
+ * > **Cancellation & Timeout Semantics**:
+ * > When `checkTimeoutMs` expires, the HTTP probe response immediately fast-fails with 503
+ * > and aborts the supplied `AbortSignal`.
+ * >
+ * > However, runtime cancellation in JavaScript is **strictly cooperative**. The probe server cannot
+ * > preemptively interrupt executing JavaScript or force-cancel asynchronous work that does not listen
+ * > to the signal. If a check executes asynchronous tasks without passing `signal`
+ * > (e.g., `await db.query(...)` without `{ signal }`), that task will continue running in the background.
+ * > To prevent background resource leaks, always pass `signal` to underlying drivers/clients
+ * > (e.g. `fetch(url, { signal })`, database clients, HTTP clients) or check `signal?.aborted`.
  *
- * - Return `true` (or resolve to true) to signal ready.
+ * - Return `true` (or resolve to true, or resolve void without error) to signal ready.
  * - Return `false` (or resolve to false) to signal not ready.
  * - Throw an error (or reject) to signal not ready with an error.
  */
-type ReadinessCheckFn = (signal?: AbortSignal) => boolean | Promise<boolean>;
+type ReadinessCheckFn = (signal?: AbortSignal) => boolean | void | Promise<boolean | void>;
 /**
  * A named health check with an associated check function.
  */
@@ -56,10 +70,11 @@ interface NamedCheck {
     name: string;
     /**
      * Check function — return false or throw to indicate failure.
+     * Resolving void without throwing is considered healthy/ready.
      * Receives an AbortSignal that is triggered when the check times out.
-     * Cancellation via the signal is cooperative.
+     * Cancellation via the signal is cooperative; pass `signal` to underlying operations.
      */
-    check: (signal?: AbortSignal) => boolean | Promise<boolean>;
+    check: (signal?: AbortSignal) => boolean | void | Promise<boolean | void>;
 }
 /**
  * Result of a single named health check.
@@ -148,14 +163,27 @@ interface CatbeeHealthzServerConfig {
     /**
      * Custom liveness check function. Runs *in addition to* `checks`.
      * Return `false` or throw to indicate unhealthy.
+     * Can also be provided via `onLivenessCheck`.
      */
     onHealthCheck?: HealthCheckFn;
+    /**
+     * Symmetrical alias for `onHealthCheck` — custom liveness check function.
+     * Runs *in addition to* `checks` on `/healthz`.
+     * Return `false` or throw to indicate unhealthy.
+     */
+    onLivenessCheck?: HealthCheckFn;
     /**
      * Custom readiness check function. Runs *in addition to* `readinessChecks`.
      * Return `false` or throw to indicate not ready.
      */
     onReadinessCheck?: ReadinessCheckFn;
-    /** Timeout (ms) per individual check before it's considered failed
+    /**
+     * Timeout (ms) per individual check before it's considered failed.
+     *
+     * When exceeded, the probe immediately fast-fails with status 503 and triggers
+     * `abort()` on the check's `AbortSignal`. Note that cancellation is cooperative;
+     * checks should forward `signal` to downstream clients (e.g. database drivers, fetch)
+     * to avoid orphaned background execution.
      *  - **default**: `5000`
      *  - **env**: `HEALTHZ_CHECK_TIMEOUT_MS`
      */
@@ -194,8 +222,9 @@ interface HealthzAddressInfo {
  * "omitted" (-> fall back to `checks`) is distinguishable from
  * "explicitly empty" (-> run nothing).
  */
-interface ResolvedHealthzConfig extends Required<Omit<CatbeeHealthzServerConfig, 'onHealthCheck' | 'onReadinessCheck' | 'readinessChecks'>> {
+interface ResolvedHealthzConfig extends Required<Omit<CatbeeHealthzServerConfig, 'onHealthCheck' | 'onLivenessCheck' | 'onReadinessCheck' | 'readinessChecks'>> {
     onHealthCheck?: CatbeeHealthzServerConfig['onHealthCheck'];
+    onLivenessCheck?: CatbeeHealthzServerConfig['onLivenessCheck'];
     onReadinessCheck?: CatbeeHealthzServerConfig['onReadinessCheck'];
     readinessChecks?: CatbeeHealthzServerConfig['readinessChecks'];
 }
@@ -259,6 +288,8 @@ declare class HealthzServer {
     private readonly server;
     private readonly config;
     private readonly startedAt;
+    /** Running address info for the Healthz probe server */
+    private addressInfo;
     /** Whether the health HTTP server is currently running and listening on its port */
     private running;
     /** Whether application startup has completed (for `/startupz`) */
@@ -266,6 +297,9 @@ declare class HealthzServer {
     /** Whether the service is ready to receive traffic (for `/readyz`) */
     private ready;
     private shuttingDown;
+    private readonly livenessChecks;
+    private readonly readinessChecks;
+    private stoppingPromise?;
     private readonly onSigterm;
     private readonly onSigint;
     private constructor();
@@ -279,33 +313,96 @@ declare class HealthzServer {
      */
     static start(opts?: CatbeeHealthzServerConfig): Promise<HealthzAddressInfo | null>;
     /** Whether the Healthz HTTP probe server is currently running and listening on its port. */
+    isRunning(): 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). */
+    markStartupComplete(): this;
+    /** Mark application startup as completed (switches `/startupz` to 200). */
     static markStartupComplete(): void;
+    /** Set application startup completion status. */
+    setStartupComplete(complete: boolean): this;
+    /** Set application startup completion status. */
+    static setStartupComplete(complete: boolean): void;
+    /** Whether application startup has completed (for `/startupz`). */
+    isStartupComplete(): boolean;
     /** Whether application startup has completed (for `/startupz`). */
     static isStartupComplete(): boolean;
     /** Mark the service as ready / not-ready for traffic. */
+    setReady(ready: boolean): this;
+    /** Mark the service as ready / not-ready for traffic. */
     static setReady(ready: boolean): void;
     /** Whether the service is currently marked as ready. */
+    isReady(): boolean;
+    /** Whether the service is currently marked as ready. */
     static isReady(): boolean;
+    /** Get address info of this health server instance. */
+    getAddress(): HealthzAddressInfo | null;
+    /** Get address info of the active singleton health server. */
+    static getAddress(): HealthzAddressInfo | null;
+    /** Get port the health server is listening on. */
+    getPort(): number | undefined;
+    /** Get port the active singleton health server is listening on. */
+    static getPort(): number | undefined;
+    /** Get configured host. */
+    getHost(): string | undefined;
+    /** Get configured host of the active singleton health server. */
+    static getHost(): string | undefined;
+    /** Get full URL for this health server instance. */
+    getUrl(): string | undefined;
+    /** Get full URL for the active singleton health server. */
+    static getUrl(): string | undefined;
+    /** Gracefully stop this health server instance. */
+    stop(): Promise<void>;
     /** Gracefully stop the health-check server. */
     static stop(): Promise<void>;
     static getInstance(): HealthzServer | undefined;
     /**
      * Register a named check on this HealthzServer instance dynamically.
+     * If a check with the same name already exists in the target probe, it is updated in-place.
      *
      * @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;
+    /**
+     * Unregister a named check on this HealthzServer instance.
+     *
+     * @param name - The name of the check to remove
+     * @param type - Which probe to remove from ('liveness', 'readiness', or 'both')
+     * @returns This instance for chaining
+     */
+    unregisterCheck(name: string, type?: 'liveness' | 'readiness' | 'both'): this;
+    /**
+     * Get all registered checks on this instance.
+     */
+    getChecks(): {
+        liveness: NamedCheck[];
+        readiness: NamedCheck[];
+    };
     /**
      * Register a named check on the active singleton HealthzServer instance (if started).
+     * If a check with the same name already exists in the target probe, it is updated in-place.
      *
      * @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;
+    /**
+     * Unregister a named check on the active singleton HealthzServer instance (if started).
+     *
+     * @param name - Name of the check to remove
+     * @param type - Which probe to remove from ('liveness', 'readiness', or 'both')
+     */
+    static unregisterCheck(name: string, type?: 'liveness' | 'readiness' | 'both'): void;
+    /**
+     * Get all registered checks on the active singleton HealthzServer instance.
+     */
+    static getChecks(): {
+        liveness: NamedCheck[];
+        readiness: NamedCheck[];
+    };
     private handleRequest;
     /** `/healthz` — Liveness probe */
     private handleLiveness;
@@ -316,6 +413,13 @@ declare class HealthzServer {
     private runChecks;
     private sendProbe;
     private sendJson;
+    /**
+     * Executes a check function with timeout and cooperative cancellation.
+     *
+     * Note on cancellation: The AbortController aborts when `ms` expires, which signals cooperative
+     * consumers (e.g., fetch, pg, ioredis) to terminate their work. The attached .catch() on checkPromise
+     * prevents unhandled rejections if the check promise rejects after the timeout has already resolved.
+     */
     private executeCheck;
     private initiateShutdown;
     private cleanup;