@sebspark/health-check 0.1.0

package/dist/index.js

@@ -0,0 +1,367 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  HealthMonitor: () => HealthMonitor,
+  TimeoutError: () => TimeoutError,
+  UnknownError: () => UnknownError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/health-monitor.ts
+var import_express = require("express");
+
+// src/static-checks.ts
+var import_node_os = __toESM(require("os"));
+var ping = () => ({ status: "ok" });
+var liveness = () => {
+  const cpus = import_node_os.default.cpus();
+  const total = import_node_os.default.totalmem();
+  const free = import_node_os.default.freemem();
+  return {
+    status: "ok",
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    system: {
+      hostname: import_node_os.default.hostname(),
+      platform: import_node_os.default.platform(),
+      release: import_node_os.default.release(),
+      arch: import_node_os.default.arch(),
+      uptime: import_node_os.default.uptime(),
+      loadavg: import_node_os.default.loadavg(),
+      totalmem: total,
+      freemem: free,
+      memUsedRatio: total > 0 ? (total - free) / total : 0,
+      cpus: {
+        count: cpus.length,
+        model: cpus[0]?.model,
+        speedMHz: cpus[0]?.speed
+      }
+    },
+    process: {
+      pid: process.pid,
+      node: process.versions.node,
+      uptime: process.uptime(),
+      memory: process.memoryUsage()
+      // rss, heapTotal, heapUsed, external, arrayBuffers
+    }
+  };
+};
+
+// src/types.ts
+var TimeoutError = class extends Error {
+  constructor() {
+    super("timeout");
+    this.name = "TimeoutError";
+  }
+};
+var UnknownError = class extends Error {
+  constructor() {
+    super("unknown");
+    this.name = "UnknownError";
+  }
+};
+
+// src/timing.ts
+var throttle = (fn, ms) => {
+  let current = null;
+  let clearHandle = null;
+  const wrapped = (...args) => {
+    if (!current) {
+      current = fn(...args);
+      if (clearHandle) {
+        clearTimeout(clearHandle);
+        clearHandle = null;
+      }
+      current.finally(() => {
+        if (ms > 0) {
+          clearHandle = setTimeout(() => {
+            current = null;
+            clearHandle = null;
+          }, ms);
+        } else {
+          current = null;
+        }
+      });
+    }
+    return current;
+  };
+  return wrapped;
+};
+
+// src/health-monitor.ts
+var HealthMonitor = class {
+  _router;
+  dependencies;
+  isDisposed = false;
+  /**
+   * Create a new HealthMonitor instance with its own router and dependency map.
+   */
+  constructor(config) {
+    this._router = this.createRouter();
+    this.dependencies = /* @__PURE__ */ new Map();
+    const thr = config ? config.throttle : 10;
+    if (thr > 0) {
+      this.ready = throttle(this.ready.bind(this), thr);
+    }
+  }
+  /**
+   * 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, dependency) {
+    this.dependencies.set(name, dependency);
+    return this;
+  }
+  /**
+   * Internal: create the Express router with /health routes.
+   */
+  createRouter() {
+    const router = (0, import_express.Router)();
+    router.get("/health", async (_req, res, next) => {
+      try {
+        const health = await this.health();
+        res.status(200).json(health);
+      } catch (err) {
+        next(err);
+      }
+    });
+    router.get("/health/ping", (_req, res, next) => {
+      try {
+        res.status(200).json(this.ping());
+      } catch (err) {
+        next(err);
+      }
+    });
+    router.get("/health/live", (_req, res, next) => {
+      try {
+        res.status(200).json(this.live());
+      } catch (err) {
+        next(err);
+      }
+    });
+    router.get("/health/ready", async (_req, res, next) => {
+      try {
+        const readiness = await this.ready();
+        res.status(200).json(readiness);
+      } catch (err) {
+        next(err);
+      }
+    });
+    const errorHandler = (err, _req, res, _next) => {
+      const message = err instanceof Error ? err.message : String(err);
+      res.status(500).json({
+        status: "error",
+        error: { message }
+      });
+    };
+    router.use(errorHandler);
+    return router;
+  }
+  /**
+   * Static ping check — always returns `{ status: "ok" }`.
+   */
+  ping() {
+    return ping();
+  }
+  /**
+   * Liveness probe: reports uptime and current timestamp.
+   */
+  live() {
+    return 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 }
+   *     }
+   *   }
+   * }
+   * ```
+   */
+  async ready() {
+    const entries = Array.from(this.dependencies.entries());
+    const settled = await Promise.allSettled(
+      entries.map(async ([name, monitor]) => {
+        const check = await monitor.check();
+        return [name, check];
+      })
+    );
+    const checks = {};
+    for (let i = 0; i < settled.length; i++) {
+      const s = settled[i];
+      const [name] = entries[i];
+      if (s.status === "fulfilled") {
+        const [, check] = s.value;
+        checks[name] = check;
+      } else {
+        checks[name] = {
+          status: "error",
+          impact: this.dependencies.get(name)?.impact,
+          mode: "polled",
+          freshness: {
+            lastChecked: (/* @__PURE__ */ new Date()).toISOString(),
+            lastSuccess: null
+          },
+          observed: void 0,
+          error: {
+            code: "CHECK_FAILED",
+            message: String(s.reason ?? "unknown error")
+          }
+        };
+      }
+    }
+    let criticalOk = 0;
+    let criticalFailing = 0;
+    let nonCritOk = 0;
+    let nonCritDegraded = 0;
+    let nonCritFailing = 0;
+    const degradedReasons = [];
+    for (const [name, c] of Object.entries(checks)) {
+      const isCritical = c.impact === "critical";
+      if (c.status === "ok") {
+        if (isCritical) criticalOk++;
+        else nonCritOk++;
+      } else if (c.status === "degraded") {
+        if (isCritical)
+          criticalFailing++;
+        else nonCritDegraded++;
+        degradedReasons.push(`${name}:degraded`);
+      } else {
+        if (isCritical) criticalFailing++;
+        else nonCritFailing++;
+        degradedReasons.push(`${name}:${c.error?.code ?? "error"}`);
+      }
+    }
+    const summary = {
+      critical: { ok: criticalOk, failing: criticalFailing },
+      nonCritical: {
+        ok: nonCritOk,
+        degraded: nonCritDegraded,
+        failing: nonCritFailing
+      },
+      degradedReasons
+    };
+    let status = "ok";
+    const values = Object.values(checks);
+    const anyCriticalError = values.some(
+      (c) => c.impact === "critical" && c.status === "error"
+    );
+    const anyDegradedOrError = values.some(
+      (c) => c.status === "degraded" || c.status === "error"
+    );
+    const anyCriticalDegraded = values.some(
+      (c) => c.impact === "critical" && c.status === "degraded"
+    );
+    if (anyCriticalError) status = "error";
+    else if (anyCriticalDegraded || anyDegradedOrError) status = "degraded";
+    const payload = {
+      status,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      // service: { name, version, instanceId } // (optional; if you add config later)
+      summary,
+      checks
+    };
+    return payload;
+  }
+  async health() {
+    const { status, checks, summary } = await this.ready();
+    const { timestamp, system, process: process2 } = this.live();
+    return {
+      status,
+      timestamp,
+      system,
+      process: process2,
+      checks,
+      summary
+    };
+  }
+  /**
+   * Accessor for the Express router that exposes /health endpoints.
+   */
+  get router() {
+    return this._router;
+  }
+  /**
+   * Symbol-based disposer for use with `using`.
+   */
+  [Symbol.dispose]() {
+    this.dispose();
+  }
+  /**
+   * Dispose of the monitor:
+   * - marks as disposed
+   * - (future: could also stop all dependency monitors)
+   */
+  dispose() {
+    this.isDisposed = true;
+    for (const dependency of this.dependencies.values()) {
+      dependency.dispose();
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  HealthMonitor,
+  TimeoutError,
+  UnknownError
+});

package/dist/index.mjs

@@ -0,0 +1,328 @@
+// src/health-monitor.ts
+import { Router } from "express";
+
+// src/static-checks.ts
+import os from "os";
+var ping = () => ({ status: "ok" });
+var liveness = () => {
+  const cpus = os.cpus();
+  const total = os.totalmem();
+  const free = os.freemem();
+  return {
+    status: "ok",
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    system: {
+      hostname: os.hostname(),
+      platform: os.platform(),
+      release: os.release(),
+      arch: os.arch(),
+      uptime: os.uptime(),
+      loadavg: os.loadavg(),
+      totalmem: total,
+      freemem: free,
+      memUsedRatio: total > 0 ? (total - free) / total : 0,
+      cpus: {
+        count: cpus.length,
+        model: cpus[0]?.model,
+        speedMHz: cpus[0]?.speed
+      }
+    },
+    process: {
+      pid: process.pid,
+      node: process.versions.node,
+      uptime: process.uptime(),
+      memory: process.memoryUsage()
+      // rss, heapTotal, heapUsed, external, arrayBuffers
+    }
+  };
+};
+
+// src/types.ts
+var TimeoutError = class extends Error {
+  constructor() {
+    super("timeout");
+    this.name = "TimeoutError";
+  }
+};
+var UnknownError = class extends Error {
+  constructor() {
+    super("unknown");
+    this.name = "UnknownError";
+  }
+};
+
+// src/timing.ts
+var throttle = (fn, ms) => {
+  let current = null;
+  let clearHandle = null;
+  const wrapped = (...args) => {
+    if (!current) {
+      current = fn(...args);
+      if (clearHandle) {
+        clearTimeout(clearHandle);
+        clearHandle = null;
+      }
+      current.finally(() => {
+        if (ms > 0) {
+          clearHandle = setTimeout(() => {
+            current = null;
+            clearHandle = null;
+          }, ms);
+        } else {
+          current = null;
+        }
+      });
+    }
+    return current;
+  };
+  return wrapped;
+};
+
+// src/health-monitor.ts
+var HealthMonitor = class {
+  _router;
+  dependencies;
+  isDisposed = false;
+  /**
+   * Create a new HealthMonitor instance with its own router and dependency map.
+   */
+  constructor(config) {
+    this._router = this.createRouter();
+    this.dependencies = /* @__PURE__ */ new Map();
+    const thr = config ? config.throttle : 10;
+    if (thr > 0) {
+      this.ready = throttle(this.ready.bind(this), thr);
+    }
+  }
+  /**
+   * 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, dependency) {
+    this.dependencies.set(name, dependency);
+    return this;
+  }
+  /**
+   * Internal: create the Express router with /health routes.
+   */
+  createRouter() {
+    const router = Router();
+    router.get("/health", async (_req, res, next) => {
+      try {
+        const health = await this.health();
+        res.status(200).json(health);
+      } catch (err) {
+        next(err);
+      }
+    });
+    router.get("/health/ping", (_req, res, next) => {
+      try {
+        res.status(200).json(this.ping());
+      } catch (err) {
+        next(err);
+      }
+    });
+    router.get("/health/live", (_req, res, next) => {
+      try {
+        res.status(200).json(this.live());
+      } catch (err) {
+        next(err);
+      }
+    });
+    router.get("/health/ready", async (_req, res, next) => {
+      try {
+        const readiness = await this.ready();
+        res.status(200).json(readiness);
+      } catch (err) {
+        next(err);
+      }
+    });
+    const errorHandler = (err, _req, res, _next) => {
+      const message = err instanceof Error ? err.message : String(err);
+      res.status(500).json({
+        status: "error",
+        error: { message }
+      });
+    };
+    router.use(errorHandler);
+    return router;
+  }
+  /**
+   * Static ping check — always returns `{ status: "ok" }`.
+   */
+  ping() {
+    return ping();
+  }
+  /**
+   * Liveness probe: reports uptime and current timestamp.
+   */
+  live() {
+    return 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 }
+   *     }
+   *   }
+   * }
+   * ```
+   */
+  async ready() {
+    const entries = Array.from(this.dependencies.entries());
+    const settled = await Promise.allSettled(
+      entries.map(async ([name, monitor]) => {
+        const check = await monitor.check();
+        return [name, check];
+      })
+    );
+    const checks = {};
+    for (let i = 0; i < settled.length; i++) {
+      const s = settled[i];
+      const [name] = entries[i];
+      if (s.status === "fulfilled") {
+        const [, check] = s.value;
+        checks[name] = check;
+      } else {
+        checks[name] = {
+          status: "error",
+          impact: this.dependencies.get(name)?.impact,
+          mode: "polled",
+          freshness: {
+            lastChecked: (/* @__PURE__ */ new Date()).toISOString(),
+            lastSuccess: null
+          },
+          observed: void 0,
+          error: {
+            code: "CHECK_FAILED",
+            message: String(s.reason ?? "unknown error")
+          }
+        };
+      }
+    }
+    let criticalOk = 0;
+    let criticalFailing = 0;
+    let nonCritOk = 0;
+    let nonCritDegraded = 0;
+    let nonCritFailing = 0;
+    const degradedReasons = [];
+    for (const [name, c] of Object.entries(checks)) {
+      const isCritical = c.impact === "critical";
+      if (c.status === "ok") {
+        if (isCritical) criticalOk++;
+        else nonCritOk++;
+      } else if (c.status === "degraded") {
+        if (isCritical)
+          criticalFailing++;
+        else nonCritDegraded++;
+        degradedReasons.push(`${name}:degraded`);
+      } else {
+        if (isCritical) criticalFailing++;
+        else nonCritFailing++;
+        degradedReasons.push(`${name}:${c.error?.code ?? "error"}`);
+      }
+    }
+    const summary = {
+      critical: { ok: criticalOk, failing: criticalFailing },
+      nonCritical: {
+        ok: nonCritOk,
+        degraded: nonCritDegraded,
+        failing: nonCritFailing
+      },
+      degradedReasons
+    };
+    let status = "ok";
+    const values = Object.values(checks);
+    const anyCriticalError = values.some(
+      (c) => c.impact === "critical" && c.status === "error"
+    );
+    const anyDegradedOrError = values.some(
+      (c) => c.status === "degraded" || c.status === "error"
+    );
+    const anyCriticalDegraded = values.some(
+      (c) => c.impact === "critical" && c.status === "degraded"
+    );
+    if (anyCriticalError) status = "error";
+    else if (anyCriticalDegraded || anyDegradedOrError) status = "degraded";
+    const payload = {
+      status,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      // service: { name, version, instanceId } // (optional; if you add config later)
+      summary,
+      checks
+    };
+    return payload;
+  }
+  async health() {
+    const { status, checks, summary } = await this.ready();
+    const { timestamp, system, process: process2 } = this.live();
+    return {
+      status,
+      timestamp,
+      system,
+      process: process2,
+      checks,
+      summary
+    };
+  }
+  /**
+   * Accessor for the Express router that exposes /health endpoints.
+   */
+  get router() {
+    return this._router;
+  }
+  /**
+   * Symbol-based disposer for use with `using`.
+   */
+  [Symbol.dispose]() {
+    this.dispose();
+  }
+  /**
+   * Dispose of the monitor:
+   * - marks as disposed
+   * - (future: could also stop all dependency monitors)
+   */
+  dispose() {
+    this.isDisposed = true;
+    for (const dependency of this.dependencies.values()) {
+      dependency.dispose();
+    }
+  }
+};
+export {
+  HealthMonitor,
+  TimeoutError,
+  UnknownError
+};