@suaveplan/health-check - Server-tier standardised /health, /ready, /live endpoints with dependency checks — HealthChecker/ResponseBuilder/HttpCheck/TcpCheck with injectable Clock+TimersLike+LoggerLike+fetch, HEALTH_CHECK_CODES error registry, and OTel self-telemetry.

Server-tier health-check core for /health, /ready, /live endpoints with dependency checks (HTTP, TCP, custom), aggregated status, caching, and typed lifecycle events.

Documentation tree

error-codes — error-codes provides the canonical error namespace for @suaveplan/health-check. Every public failure path — invalid…
- error-codes — error-codes provides the canonical error namespace for @suaveplan/health-check. Every public failure path — invalid…
health-checker — HealthChecker is the orchestration core of @suaveplan/health-check. It owns a registry of dependency checks, runs t…
- health-checker.helpers — health-checker.helpers carries the pure helpers that back the HealthChecker class: the Zod schemas that validate co…
- health-checker — HealthChecker is the orchestration core of @suaveplan/health-check. It owns a registry of dependency checks, runs t…
http-check — createHttpCheck returns a CheckFn that probes an HTTP endpoint and reports healthy when the response status appea…
- http-check — createHttpCheck returns a CheckFn that probes an HTTP endpoint and reports healthy when the response status appea…
response-builder — ResponseBuilder adapts a HealthChecker into HTTP-shaped responses suitable for direct return from a Hono / Express…
- response-builder — ResponseBuilder adapts a HealthChecker into HTTP-shaped responses suitable for direct return from a Hono / Express…
tcp-check — createTcpCheck returns a CheckFn that opens a TCP socket against a host:port pair and resolves to healthy once…
- tcp-check — createTcpCheck returns a CheckFn that opens a TCP socket against a host:port pair and resolves to healthy once…
telemetry — telemetry registers the OpenTelemetry meter that the health-check package emits to on every public call. The instrume…
- telemetry — telemetry registers the OpenTelemetry meter that the health-check package emits to on every public call. The instrume…

Modules

health-checker/ — HealthChecker: registry, runner, aggregator, EventBus.
http-check/ — createHttpCheck: fetch-based probe with injectable fetchImpl.
tcp-check/ — createTcpCheck: socket probe with injectable TcpConnectFn.
response-builder/ — ResponseBuilder: maps statuses to HTTP codes.
error-codes/ — HEALTH_CHECK_CODES + HealthCheckError.
telemetry/ — OTel meter (counter + histogram).

Install

bun add @suaveplan/health-check

Usage

import {
    HealthChecker,
    ResponseBuilder,
    createHttpCheck,
    createTcpCheck,
} from "@suaveplan/health-check";

const checker = new HealthChecker({ name: "api", version: "1.0.0" });
checker.addCheck({
    name: "upstream",
    check: createHttpCheck({ url: "https://up.example.com/health" }),
});
checker.addCheck({
    name: "postgres",
    check: createTcpCheck({ host: "db.internal", port: 5432 }),
});

const builder = new ResponseBuilder(checker);
const { statusCode, body } = await builder.health();

License

MIT