@sebspark/health-check 1.0.7 → 1.0.8

package/dist/index.d.mts

@@ -0,0 +1,382 @@
+import { Router } from "express";
+
+//#region src/types.d.ts
+type DependencyStatusValue = 'ok' | 'degraded' | 'error';
+type StatusValue = DependencyStatusValue | 'unknown' | 'draining';
+type Impact = 'critical' | 'non_critical';
+type Mode = 'inline' | 'polled' | 'async';
+type Status = {
+  status: StatusValue;
+};
+type System = {
+  hostname: string;
+  platform: NodeJS.Platform;
+  release: string;
+  arch: string;
+  uptime: number;
+  loadavg: [number, number, number];
+  totalmem: number;
+  freemem: number;
+  memUsedRatio: number;
+  cpus: {
+    count: number;
+    model?: string;
+    speedMHz?: number;
+  };
+};
+type Process = {
+  pid: number;
+  node: string;
+  uptime: number;
+  memory: NodeJS.MemoryUsage;
+};
+type Liveness = Status & {
+  timestamp: string;
+  system: System;
+  process: Process;
+};
+type Freshness = {
+  lastChecked: string;
+  lastSuccess: string | null;
+};
+type Observed = {
+  latencyMs: number | null;
+  [k: string]: unknown;
+};
+type CheckError = {
+  code: string;
+  message: string;
+};
+type DependencyCheck = Status & {
+  impact: Impact;
+  mode: Mode;
+  freshness: Freshness;
+  observed?: Observed;
+  details?: Record<string, unknown>;
+  error?: CheckError | null;
+  since?: string | null;
+};
+type ReadinessSummary = {
+  critical: {
+    ok: number;
+    failing: number;
+  };
+  nonCritical: {
+    ok: number;
+    degraded: number;
+    failing: number;
+  };
+  degradedReasons: string[];
+};
+type ReadinessPayload = Status & {
+  timestamp: string;
+  service?: {
+    name?: string;
+    version?: string;
+    instanceId?: string;
+  };
+  summary: ReadinessSummary;
+  checks: Record<string, DependencyCheck>;
+};
+type HealthSummary = Status & Pick<ReadinessPayload, 'summary' | 'checks'> & Pick<Liveness, 'system' | 'process'> & {
+  timestamp: string;
+};
+declare class TimeoutError extends Error {
+  constructor();
+}
+declare class UnknownError extends Error {
+  constructor();
+}
+//#endregion
+//#region src/dependency-monitor.d.ts
+/**
+ * Base configuration shared by all dependency monitor modes.
+ */
+type BaseConfig = {
+  /**
+   * Importance of the dependency:
+   * - `'critical'` → service cannot run without it
+   * - `'non_critical'` → service is degraded but still functional if it fails
+   */
+  impact: Impact;
+  /**
+   * Polling interval in milliseconds.
+   * - Required for polled and async modes
+   * - Must not be set for inline mode
+   */
+  pollRate?: number;
+  /**
+   * Polling interval in milliseconds for failed calls.
+   * - Defaults to pollRate for polled and async modes
+   * - Must not be set for inline mode
+   */
+  retryRate?: number;
+  /**
+   * Maximum response time in milliseconds considered healthy.
+   * - A call resolving within this time window **and** returning `"ok"` → status `"ok"`
+   * - A call resolving after this but **before** `timeoutLimitMs` → status `"degraded"`
+   */
+  healthyLimitMs: number;
+  /**
+   * Absolute upper bound in milliseconds; beyond this a call is considered `"error"`.
+   * - Inline: the awaited call is raced with a timeout and rejected past this limit
+   * - Polled/Async: escalate `unknown` → `degraded` at `healthyLimitMs`, then `"error"` at `timeoutLimitMs`
+   * - Any late `"ok"` result after this limit is ignored
+   */
+  timeoutLimitMs: number;
+};
+/**
+ * Inline mode configuration (no polling).
+ * `syncCall` runs **only** when {@link DependencyMonitor.check} is invoked.
+ */
+type SyncInlineConfig = BaseConfig & {
+  /** Performs the check immediately when {@link DependencyMonitor.check} is called. */
+  syncCall: () => Promise<DependencyStatusValue | Error>;
+  asyncCall?: never;
+  pollRate?: undefined;
+  retryRate?: undefined;
+};
+/**
+ * Polled mode configuration.
+ * `syncCall` runs on an interval (`pollRate`) and results are cached.
+ */
+type SyncPolledConfig = BaseConfig & {
+  /** Performs the check at each poll interval. */
+  syncCall: () => Promise<DependencyStatusValue | Error>;
+  /** Polling interval in milliseconds. */
+  pollRate: number;
+  asyncCall?: never;
+};
+/**
+ * Async mode configuration.
+ * `asyncCall` starts a check and must report via the provided callback.
+ */
+type AsyncConfig = BaseConfig & {
+  /**
+   * Starts an asynchronous check. Must call `reportResponse` once a result is available.
+   * The callback may be invoked with a `DependencyStatusValue` or an `Error`.
+   */
+  asyncCall: (reportResponse: (status: DependencyStatusValue | Error) => void | Promise<void>) => void | Promise<void>;
+  /** Polling interval in milliseconds. */
+  pollRate: number;
+  syncCall?: never;
+};
+/**
+ * Discriminated configuration for a dependency monitor.
+ * - {@link SyncInlineConfig} → inline checks on demand
+ * - {@link SyncPolledConfig} → synchronous checks on a fixed interval
+ * - {@link AsyncConfig} → asynchronous checks that report back via callback
+ */
+type DependencyMonitorConfig = SyncInlineConfig | SyncPolledConfig | AsyncConfig;
+/**
+ * Tracks the health of a single dependency in one of three modes:
+ *
+ * - **inline**: `syncCall` executed only when {@link check} is called
+ * - **polled**: `syncCall` executed on `pollRate`; latest result cached
+ * - **async**: `asyncCall` executed on `pollRate`, result returned via callback
+ *
+ * The monitor:
+ * - classifies results using `healthyLimitMs` and `timeoutLimitMs`
+ * - records freshness (`lastChecked`, `lastSuccess`)
+ * - records observed latency (ms) when applicable
+ *
+ * Status interpretation:
+ * - `"ok"` only if returned `"ok"` **and** latency ≤ `healthyLimitMs`
+ * - `"degraded"` if returned `"degraded"` **or** latency > `healthyLimitMs` but ≤ `timeoutLimitMs`
+ * - `"error"` if returned `"error"`, an `Error`, or exceeded `timeoutLimitMs`
+ * - `"unknown"` is the initial state before first successful/failed result (polled/async)
+ */
+declare class DependencyMonitor {
+  /** Immutable configuration for this monitor. */
+  private readonly config;
+  /** Operational mode determined from the configuration. */
+  private readonly mode;
+  /** Last computed status (starts as `"unknown"` until first result). */
+  private status;
+  /** Optional error details from the last failure. */
+  private error?;
+  /** Last observed metrics (e.g., latency). */
+  private observed?;
+  /** Freshness timestamps for last check/success. */
+  private freshness?;
+  /** Indicates whether this monitor has been disposed. */
+  private isDisposed;
+  /** Internal timer handle for polling/retry. */
+  private timeout?;
+  /**
+   * Create a new {@link DependencyMonitor}.
+   * @param config Monitor configuration (inline, polled, or async).
+   */
+  constructor(config: DependencyMonitorConfig);
+  /** Impact of this dependency (critical/non_critical). */
+  get impact(): Impact;
+  /**
+   * Run one check cycle depending on the configured mode.
+   * - Inline: no-op here (runs in {@link check})
+   * - Polled/Async: invoked automatically and re-scheduled as needed
+   */
+  private doCheck;
+  /**
+   * Execute a synchronous (inline/polled) check and update internal state.
+   * Classification:
+   * - OK if `"ok"` and latency ≤ `healthyLimitMs`
+   * - Degraded if `"degraded"` or latency between `(healthyLimitMs, timeoutLimitMs]`
+   * - Error if `"error"`, `Error`, or timeout exceeded
+   */
+  private doSyncCheck;
+  /**
+   * Execute an asynchronous check (async mode).
+   * - Initializes timers to escalate `unknown` → `degraded` → `error`
+   *   if no callback result arrives within the thresholds.
+   * - On callback, clears timers and classifies the result with latency.
+   */
+  private doAsyncCheck;
+  /**
+   * Normalize a successful dependency response into status + metadata.
+   * @param response Returned status value or Error from the dependency
+   * @param duration Measured latency in milliseconds
+   */
+  private handleDependencyResponse;
+  /**
+   * Normalize a failed dependency result into `"error"` and update metadata.
+   * @param error Error thrown/returned or synthesized (e.g., timeout)
+   */
+  private handleDependencyError;
+  /**
+   * Get a snapshot of the dependency’s current health.
+   * - Inline mode: executes the `syncCall` (single-flight guarded)
+   * - Polled/Async: returns the cached result
+   * @throws if the monitor has been disposed
+   */
+  check(): Promise<DependencyCheck>;
+  /** Symbol-based disposer for use with `using`. */
+  [Symbol.dispose](): void;
+  /**
+   * Dispose the monitor:
+   * - Clears any scheduled timers
+   * - Prevents further checks from running
+   */
+  dispose(): void;
+}
+//#endregion
+//#region src/health-monitor.d.ts
+interface HealthMonitorConfig {
+  throttle: number;
+}
+/**
+ * HealthMonitor wires up standard health check endpoints for an Express app.
+ *
+ * It provides three endpoints under `/health`:
+ * - /ping → lightweight always-OK response (`{ status: "ok" }`)
+ * - /live → liveness probe (`{ status, uptime, timestamp }`)
+ * - /ready → readiness probe with dependency checks (`{ status, checks }`)
+ *
+ * Dependencies can be added via {@link addDependency} with a {@link DependencyMonitorConfig}.
+ * Each dependency is wrapped in a {@link DependencyMonitor} and tracked for readiness.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import express from 'express'
+ * import { HealthMonitor } from './health-monitor'
+ *
+ * const app = express()
+ * const monitor = new HealthMonitor()
+ *
+ * monitor.addDependency('db', {
+ *   impact: 'critical',
+ *   syncCall: async () => {
+ *     await db.ping()
+ *     return 'ok'
+ *   }
+ * })
+ *
+ * app.use(monitor.router)
+ * app.listen(3000)
+ * ```
+ */
+declare class HealthMonitor {
+  private readonly _router;
+  private readonly dependencies;
+  /**
+   * Create a new HealthMonitor instance with its own router and dependency map.
+   */
+  constructor(config?: HealthMonitorConfig);
+  /**
+   * Register a named dependency to be checked as part of readiness.
+   *
+   * @param name - Identifier for the dependency (e.g. "postgres", "redis").
+   * @param dependency - DependencyMonitor
+   * @returns this for chaining
+   *
+   * @example
+   * ```ts
+   * monitor.addDependency('redis', new DependencyMonitor({
+   *   impact: 'critical',
+   *   pollRate: 5000,
+   *   syncCall: async () => redis.ping() ? 'ok' : 'error'
+   * }))
+   * ```
+   */
+  addDependency(name: string, dependency: DependencyMonitor): this;
+  /**
+   * Internal: create the Express router with /health routes.
+   */
+  private createRouter;
+  /**
+   * Static ping check — always returns `{ status: "ok" }`.
+   */
+  ping(): Status;
+  /**
+   * Liveness probe: reports uptime and current timestamp.
+   */
+  live(): Liveness;
+  /**
+   * Readiness probe: runs all registered dependencies in parallel
+   * and aggregates their results into an overall status.
+   *
+   * - Any **critical error** → `"error"`
+   * - Else any **critical degraded** or any non-critical degraded/error → `"degraded"`
+   * - Else → `"ok"`
+   *
+   * @returns Object with overall `status` and per-dependency `checks`
+   *
+   * @example
+   * ```json
+   * {
+   *   "status": "ok",
+   *   "checks": {
+   *     "postgres": {
+   *       "status": "ok",
+   *       "impact": "critical",
+   *       "mode": "inline",
+   *       "freshness": {
+   *         "lastChecked": "2025-08-19T12:00:00Z",
+   *         "lastSuccess": "2025-08-19T12:00:00Z"
+   *       },
+   *       "observed": { "latencyMs": 12 }
+   *     }
+   *   }
+   * }
+   * ```
+   */
+  ready(): Promise<ReadinessPayload>;
+  health(): Promise<HealthSummary>;
+  /**
+   * Accessor for the Express router that exposes /health endpoints.
+   */
+  get router(): Router;
+  /**
+   * Symbol-based disposer for use with `using`.
+   */
+  [Symbol.dispose](): void;
+  /**
+   * Dispose of the monitor:
+   * - marks as disposed
+   * - (future: could also stop all dependency monitors)
+   */
+  dispose(): void;
+}
+//#endregion
+export { AsyncConfig, CheckError, DependencyCheck, DependencyMonitor, DependencyMonitorConfig, DependencyStatusValue, Freshness, HealthMonitor, HealthMonitorConfig, HealthSummary, Impact, Liveness, Mode, Observed, Process, ReadinessPayload, ReadinessSummary, Status, StatusValue, SyncInlineConfig, SyncPolledConfig, System, TimeoutError, UnknownError };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/dependency-monitor.ts","../src/health-monitor.ts"],"sourcesContent":[],"mappings":"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"}