@sebspark/health-check 0.1.4 → 1.0.1

package/dist/index.d.mts

@@ -375,4 +375,4 @@ declare class HealthMonitor {
     dispose(): void;
 }
 
-export { type CheckError, type DependencyCheck, type DependencyStatusValue, type Freshness, HealthMonitor, type HealthMonitorConfig, type HealthSummary, type Impact, type Liveness, type Mode, type Observed, type Process, type ReadinessPayload, type ReadinessSummary, type Status, type StatusValue, type System, TimeoutError, UnknownError };
+export { type AsyncConfig, type CheckError, type DependencyCheck, DependencyMonitor, type DependencyMonitorConfig, type DependencyStatusValue, type Freshness, HealthMonitor, type HealthMonitorConfig, type HealthSummary, type Impact, type Liveness, type Mode, type Observed, type Process, type ReadinessPayload, type ReadinessSummary, type Status, type StatusValue, type SyncInlineConfig, type SyncPolledConfig, type System, TimeoutError, UnknownError };

package/dist/index.d.ts

@@ -375,4 +375,4 @@ declare class HealthMonitor {
     dispose(): void;
 }
 
-export { type CheckError, type DependencyCheck, type DependencyStatusValue, type Freshness, HealthMonitor, type HealthMonitorConfig, type HealthSummary, type Impact, type Liveness, type Mode, type Observed, type Process, type ReadinessPayload, type ReadinessSummary, type Status, type StatusValue, type System, TimeoutError, UnknownError };
+export { type AsyncConfig, type CheckError, type DependencyCheck, DependencyMonitor, type DependencyMonitorConfig, type DependencyStatusValue, type Freshness, HealthMonitor, type HealthMonitorConfig, type HealthSummary, type Impact, type Liveness, type Mode, type Observed, type Process, type ReadinessPayload, type ReadinessSummary, type Status, type StatusValue, type SyncInlineConfig, type SyncPolledConfig, type System, TimeoutError, UnknownError };

package/dist/index.js

@@ -30,50 +30,15 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  DependencyMonitor: () => DependencyMonitor,
   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/dependency-monitor.ts
+var import_node_perf_hooks = require("perf_hooks");
 
 // src/types.ts
 var TimeoutError = class extends Error {
@@ -90,6 +55,17 @@ var UnknownError = class extends Error {
 };
 
 // src/timing.ts
+var wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var runTimeoutTimer = async (ms) => {
+  await wait(ms);
+  throw new TimeoutError();
+};
+var runAgainstTimeout = (promise, ms) => {
+  if (ms > 0) {
+    return Promise.race([promise, runTimeoutTimer(ms)]);
+  }
+  return promise;
+};
 var throttle = (fn, ms) => {
   let current = null;
   let clearHandle = null;
@@ -115,6 +91,236 @@ var throttle = (fn, ms) => {
   };
   return wrapped;
 };
+var singleFlight = (fn) => throttle(fn, 0);
+
+// src/dependency-monitor.ts
+var DependencyMonitor = class {
+  /** Immutable configuration for this monitor. */
+  config;
+  /** Operational mode determined from the configuration. */
+  mode;
+  /** Last computed status (starts as `"unknown"` until first result). */
+  status;
+  /** Optional error details from the last failure. */
+  error;
+  /** Last observed metrics (e.g., latency). */
+  observed;
+  /** Freshness timestamps for last check/success. */
+  freshness;
+  /** Indicates whether this monitor has been disposed. */
+  isDisposed = false;
+  /** Internal timer handle for polling/retry. */
+  timeout;
+  /**
+   * Create a new {@link DependencyMonitor}.
+   * @param config Monitor configuration (inline, polled, or async).
+   */
+  constructor(config) {
+    this.config = config;
+    this.mode = config.asyncCall ? "async" : config.pollRate ? "polled" : "inline";
+    this.status = "unknown";
+    if (this.mode === "inline") {
+      this.check = singleFlight(this.check.bind(this));
+    }
+    if (this.mode !== "inline") {
+      this.doCheck();
+    }
+  }
+  /** Impact of this dependency (critical/non_critical). */
+  get impact() {
+    return this.config.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
+   */
+  async doCheck() {
+    if (this.timeout) {
+      clearTimeout(this.timeout);
+    }
+    if (this.isDisposed) {
+      return;
+    }
+    if (this.config.syncCall) {
+      await this.doSyncCheck();
+    } else {
+      this.doAsyncCheck();
+    }
+  }
+  /**
+   * 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
+   */
+  async doSyncCheck() {
+    const start = import_node_perf_hooks.performance.now();
+    const { syncCall, timeoutLimitMs } = this.config;
+    try {
+      const response = await runAgainstTimeout(syncCall(), timeoutLimitMs);
+      const duration = import_node_perf_hooks.performance.now() - start;
+      this.handleDependencyResponse(response, duration);
+    } catch (err) {
+      this.handleDependencyError(err);
+    }
+  }
+  /**
+   * 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.
+   */
+  async doAsyncCheck() {
+    const { asyncCall, healthyLimitMs, timeoutLimitMs } = this.config;
+    const start = import_node_perf_hooks.performance.now();
+    let callActive = true;
+    let healthTimeout;
+    let serviceTimeout;
+    asyncCall((response) => {
+      if (!callActive) return;
+      callActive = false;
+      clearTimeout(healthTimeout);
+      clearTimeout(serviceTimeout);
+      const duration = import_node_perf_hooks.performance.now() - start;
+      this.handleDependencyResponse(response, duration);
+    });
+    healthTimeout = setTimeout(() => {
+      if (callActive) this.status = "degraded";
+    }, healthyLimitMs);
+    serviceTimeout = setTimeout(() => {
+      if (!callActive) return;
+      callActive = false;
+      clearTimeout(healthTimeout);
+      this.handleDependencyError(new TimeoutError());
+    }, timeoutLimitMs);
+  }
+  /**
+   * Normalize a successful dependency response into status + metadata.
+   * @param response Returned status value or Error from the dependency
+   * @param duration Measured latency in milliseconds
+   */
+  handleDependencyResponse(response, duration) {
+    if (response instanceof Error) {
+      return this.handleDependencyError(response);
+    }
+    if (response === "error") {
+      return this.handleDependencyError(new UnknownError());
+    }
+    this.error = void 0;
+    this.status = response === "ok" && duration <= this.config.healthyLimitMs ? "ok" : "degraded";
+    const end = /* @__PURE__ */ new Date();
+    this.freshness = {
+      lastChecked: end.toISOString(),
+      lastSuccess: end.toISOString()
+    };
+    this.observed = { latencyMs: duration };
+    if (this.config.pollRate && !this.isDisposed) {
+      const delay = this.config.pollRate;
+      this.timeout = setTimeout(() => this.doCheck(), delay);
+    }
+  }
+  /**
+   * Normalize a failed dependency result into `"error"` and update metadata.
+   * @param error Error thrown/returned or synthesized (e.g., timeout)
+   */
+  handleDependencyError(error) {
+    this.status = "error";
+    this.observed = void 0;
+    this.error = {
+      code: error.code || "UNKNOWN",
+      message: error.message
+    };
+    const end = /* @__PURE__ */ new Date();
+    if (this.freshness) {
+      this.freshness.lastChecked = end.toISOString();
+    } else {
+      this.freshness = { lastChecked: end.toISOString(), lastSuccess: null };
+    }
+    if ((this.config.retryRate || this.config.pollRate) && !this.isDisposed) {
+      const delay = this.config.retryRate || this.config.pollRate;
+      this.timeout = setTimeout(() => this.doCheck(), delay);
+    }
+  }
+  /**
+   * 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
+   */
+  async check() {
+    if (this.isDisposed) {
+      throw new Error("DependencyMonitor has been disposed");
+    }
+    if (this.mode === "inline") {
+      await this.doCheck();
+    }
+    const result = {
+      status: this.status,
+      impact: this.config.impact,
+      mode: this.mode,
+      freshness: this.freshness,
+      observed: this.observed,
+      error: this.error
+    };
+    return result;
+  }
+  /** Symbol-based disposer for use with `using`. */
+  [Symbol.dispose]() {
+    this.dispose();
+  }
+  /**
+   * Dispose the monitor:
+   * - Clears any scheduled timers
+   * - Prevents further checks from running
+   */
+  dispose() {
+    this.isDisposed = true;
+    if (this.timeout) {
+      clearTimeout(this.timeout);
+    }
+  }
+};
+
+// 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/health-monitor.ts
 var HealthMonitor = class {
@@ -360,6 +566,7 @@ var HealthMonitor = class {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  DependencyMonitor,
   HealthMonitor,
   TimeoutError,
   UnknownError

package/dist/index.mjs

@@ -1,41 +1,5 @@
-// 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/dependency-monitor.ts
+import { performance } from "perf_hooks";
 
 // src/types.ts
 var TimeoutError = class extends Error {
@@ -52,6 +16,17 @@ var UnknownError = class extends Error {
 };
 
 // src/timing.ts
+var wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var runTimeoutTimer = async (ms) => {
+  await wait(ms);
+  throw new TimeoutError();
+};
+var runAgainstTimeout = (promise, ms) => {
+  if (ms > 0) {
+    return Promise.race([promise, runTimeoutTimer(ms)]);
+  }
+  return promise;
+};
 var throttle = (fn, ms) => {
   let current = null;
   let clearHandle = null;
@@ -77,6 +52,236 @@ var throttle = (fn, ms) => {
   };
   return wrapped;
 };
+var singleFlight = (fn) => throttle(fn, 0);
+
+// src/dependency-monitor.ts
+var DependencyMonitor = class {
+  /** Immutable configuration for this monitor. */
+  config;
+  /** Operational mode determined from the configuration. */
+  mode;
+  /** Last computed status (starts as `"unknown"` until first result). */
+  status;
+  /** Optional error details from the last failure. */
+  error;
+  /** Last observed metrics (e.g., latency). */
+  observed;
+  /** Freshness timestamps for last check/success. */
+  freshness;
+  /** Indicates whether this monitor has been disposed. */
+  isDisposed = false;
+  /** Internal timer handle for polling/retry. */
+  timeout;
+  /**
+   * Create a new {@link DependencyMonitor}.
+   * @param config Monitor configuration (inline, polled, or async).
+   */
+  constructor(config) {
+    this.config = config;
+    this.mode = config.asyncCall ? "async" : config.pollRate ? "polled" : "inline";
+    this.status = "unknown";
+    if (this.mode === "inline") {
+      this.check = singleFlight(this.check.bind(this));
+    }
+    if (this.mode !== "inline") {
+      this.doCheck();
+    }
+  }
+  /** Impact of this dependency (critical/non_critical). */
+  get impact() {
+    return this.config.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
+   */
+  async doCheck() {
+    if (this.timeout) {
+      clearTimeout(this.timeout);
+    }
+    if (this.isDisposed) {
+      return;
+    }
+    if (this.config.syncCall) {
+      await this.doSyncCheck();
+    } else {
+      this.doAsyncCheck();
+    }
+  }
+  /**
+   * 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
+   */
+  async doSyncCheck() {
+    const start = performance.now();
+    const { syncCall, timeoutLimitMs } = this.config;
+    try {
+      const response = await runAgainstTimeout(syncCall(), timeoutLimitMs);
+      const duration = performance.now() - start;
+      this.handleDependencyResponse(response, duration);
+    } catch (err) {
+      this.handleDependencyError(err);
+    }
+  }
+  /**
+   * 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.
+   */
+  async doAsyncCheck() {
+    const { asyncCall, healthyLimitMs, timeoutLimitMs } = this.config;
+    const start = performance.now();
+    let callActive = true;
+    let healthTimeout;
+    let serviceTimeout;
+    asyncCall((response) => {
+      if (!callActive) return;
+      callActive = false;
+      clearTimeout(healthTimeout);
+      clearTimeout(serviceTimeout);
+      const duration = performance.now() - start;
+      this.handleDependencyResponse(response, duration);
+    });
+    healthTimeout = setTimeout(() => {
+      if (callActive) this.status = "degraded";
+    }, healthyLimitMs);
+    serviceTimeout = setTimeout(() => {
+      if (!callActive) return;
+      callActive = false;
+      clearTimeout(healthTimeout);
+      this.handleDependencyError(new TimeoutError());
+    }, timeoutLimitMs);
+  }
+  /**
+   * Normalize a successful dependency response into status + metadata.
+   * @param response Returned status value or Error from the dependency
+   * @param duration Measured latency in milliseconds
+   */
+  handleDependencyResponse(response, duration) {
+    if (response instanceof Error) {
+      return this.handleDependencyError(response);
+    }
+    if (response === "error") {
+      return this.handleDependencyError(new UnknownError());
+    }
+    this.error = void 0;
+    this.status = response === "ok" && duration <= this.config.healthyLimitMs ? "ok" : "degraded";
+    const end = /* @__PURE__ */ new Date();
+    this.freshness = {
+      lastChecked: end.toISOString(),
+      lastSuccess: end.toISOString()
+    };
+    this.observed = { latencyMs: duration };
+    if (this.config.pollRate && !this.isDisposed) {
+      const delay = this.config.pollRate;
+      this.timeout = setTimeout(() => this.doCheck(), delay);
+    }
+  }
+  /**
+   * Normalize a failed dependency result into `"error"` and update metadata.
+   * @param error Error thrown/returned or synthesized (e.g., timeout)
+   */
+  handleDependencyError(error) {
+    this.status = "error";
+    this.observed = void 0;
+    this.error = {
+      code: error.code || "UNKNOWN",
+      message: error.message
+    };
+    const end = /* @__PURE__ */ new Date();
+    if (this.freshness) {
+      this.freshness.lastChecked = end.toISOString();
+    } else {
+      this.freshness = { lastChecked: end.toISOString(), lastSuccess: null };
+    }
+    if ((this.config.retryRate || this.config.pollRate) && !this.isDisposed) {
+      const delay = this.config.retryRate || this.config.pollRate;
+      this.timeout = setTimeout(() => this.doCheck(), delay);
+    }
+  }
+  /**
+   * 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
+   */
+  async check() {
+    if (this.isDisposed) {
+      throw new Error("DependencyMonitor has been disposed");
+    }
+    if (this.mode === "inline") {
+      await this.doCheck();
+    }
+    const result = {
+      status: this.status,
+      impact: this.config.impact,
+      mode: this.mode,
+      freshness: this.freshness,
+      observed: this.observed,
+      error: this.error
+    };
+    return result;
+  }
+  /** Symbol-based disposer for use with `using`. */
+  [Symbol.dispose]() {
+    this.dispose();
+  }
+  /**
+   * Dispose the monitor:
+   * - Clears any scheduled timers
+   * - Prevents further checks from running
+   */
+  dispose() {
+    this.isDisposed = true;
+    if (this.timeout) {
+      clearTimeout(this.timeout);
+    }
+  }
+};
+
+// 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/health-monitor.ts
 var HealthMonitor = class {
@@ -321,6 +526,7 @@ var HealthMonitor = class {
   }
 };
 export {
+  DependencyMonitor,
   HealthMonitor,
   TimeoutError,
   UnknownError

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sebspark/health-check",
-  "version": "0.1.4",
+  "version": "1.0.1",
   "license": "Apache-2.0",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -9,7 +9,7 @@
     "dist"
   ],
   "scripts": {
-    "build": "tsup-node src/index.ts --format esm,cjs --dts",
+    "build": "tsup-node src/index.ts --format esm,cjs --target node22 --dts",
     "dev": "tsc --watch --noEmit",
     "lint": "biome check .",
     "test": "vitest run --passWithNoTests --coverage",