Skip to content
Nexload SDK

Overview & Quick Start

Service Health Orchestration

@nexload-sdk/healthcheck

v4.1.0 Stable Released

Runtime-neutral health orchestration and monitoring report foundation for production services.

Node.jsBunedge-safe core
View on npm Browse source

@nexload-sdk/healthcheck provides a runtime-neutral health orchestration engine for modern backend services. It manages checks, collectors, timeouts, cancellation, and status aggregation, returning a deterministic HealthReport.

10-Second Code Snippet

Section titled “10-Second Code Snippet”
import { createHealthManager, memoryCheck, shutdownCheck } from "@nexload-sdk/healthcheck";


export const health = createHealthManager({
  service: { name: "api-service", version: "1.0.0" },
  checks: [shutdownCheck(), memoryCheck()],
});


// Run readiness probe for Kubernetes / Dokploy / Docker
const report = await health.run("readiness");
console.log(report.status); // "ok" | "degraded" | "unhealthy"

What You Get

Section titled “What You Get”
  • Multi-Scope Orchestration: Native support for liveness, readiness, startup, and protected diagnostics scopes.
  • Checks vs. Collectors:
    • Check: Can impact aggregate service status (e.g. database connectivity, Redis ping, shutdown signals).
    • Collector: Observational only; captures telemetry and measurements (e.g. CPU load, memory RSS) without triggering container restarts.
  • Resilient Execution: Enforces per-check timeouts, retry policies, and graceful degradation.
  • Sensitive Data Redaction: Automatic masking of database credentials, authorization tokens, and private hostnames in error outputs.
  • Runtime Neutrality: Pure TypeScript core with zero Node-only assumptions; runs seamlessly on Node.js, Bun, and edge runtimes.

Installation & Requirements

Section titled “Installation & Requirements”
Terminal window
pnpm add @nexload-sdk/healthcheck

With alternative package managers:

Terminal window
# npm
npm install @nexload-sdk/healthcheck


# bun
bun add @nexload-sdk/healthcheck

Requires Node >=20.9.0 or Bun >=1.0.0. The package is ESM-only and side-effect free.

Core Concepts: The Four Scopes

Section titled “Core Concepts: The Four Scopes”
ScopeProbe QuestionFailure ConsequenceRecommended Checks
livenessIs the process deadlocked or stuck in an unrecoverable state?Container / process restartMemory leak thresholds, shutdown signal, event loop freeze. Never downstream databases!
readinessCan this replica accept incoming client traffic?Temporarily removed from load balancer poolDatabase availability, Redis connection, cache warm status.
startupHas slow initialization or schema migration finished?Delays liveness evaluation during bootDatabase migrations, asset pre-compilation.
diagnosticsWhat is the detailed operational health state?Protected behind auth tokenDetailed memory breakdown, active connections, queue depth.

Quick Start: Creating a Production Manager

Section titled “Quick Start: Creating a Production Manager”
import {
  createHealthManager,
  memoryCheck,
  runtimeInfoCheck,
  shutdownCheck,
} from "@nexload-sdk/healthcheck";


export const health = createHealthManager({
  service: {
    name: "user-service",
    version: process.env.APP_VERSION ?? "1.0.0",
  },
  checks: [
    shutdownCheck(),
    runtimeInfoCheck(),
    memoryCheck({
      heapUsedPercent: 90, // Degraded above 90%
    }),
  ],
});


// Execute readiness probe
const report = await health.run("readiness");
if (report.status === "unhealthy") {
  process.exitCode = 1;
}

Next Steps

Section titled “Next Steps”