NestJS Terminus

@nestjs/terminus is the official NestJS integration for building /health endpoints, providing a HealthCheckService plus a library of ready-made health indicators for databases (TypeORM, Mongoose, Sequelize, Prisma, MikroORM), disk and memory usage, HTTP dependencies (via Axios), and microservice transports (gRPC, and others reachable through Nest’s microservice client). It only requires the driver dependency for the checks you actually use, throwing a clear error if a required peer dependency is missing.

Health checks are composed declaratively: a @HealthCheck() decorated controller method calls HealthCheckService.check([...indicators]) with an array of indicator functions, and Terminus aggregates their results into a standard health-check response shape consumable by orchestrators like Kubernetes liveness/readiness probes or uptime monitors.

What You Get

• HealthCheckService and @HealthCheck() decorator for aggregating multiple indicator results into one endpoint response
• Database health indicators for TypeORM, Mongoose, Sequelize, Prisma, and MikroORM connections
• Disk-usage and memory (heap/RSS) health indicators with configurable thresholds
• HTTP health indicator built on Axios for checking reachability of external dependencies
• Microservice health indicators (gRPC and other Nest microservice transports)
• A graceful-shutdown-timeout utility for coordinating health status during application shutdown

Common Use Cases

• Exposing a /health endpoint for Kubernetes liveness and readiness probes
• Aggregating database, disk, and memory checks into a single health-check response for uptime monitoring tools
• Verifying downstream HTTP or microservice dependencies are reachable before reporting an application as healthy
• Coordinating graceful shutdown so load balancers stop routing traffic before in-flight requests are dropped

Under The Hood

Architecture — The library is centered on lib/terminus.module.ts registering providers, with the actual work split between lib/health-check/health-check-executor.service.ts (runs the array of indicator functions passed to @HealthCheck() and aggregates pass/fail results) and lib/health-indicator/ (one subdirectory per dependency type: database/, disk/, memory/, http/, microservice/, each exporting an indicator class with a .pingCheck()-style method). lib/errors/ defines typed error classes per failure mode (connection not found, storage exceeded, timeout, unhealthy response code) so failures are distinguishable programmatically, not just by message string.

Tech Stack — Peer-dependency driven: Terminus itself has a small core dependency footprint and dynamically requires the ORM/HTTP client package matching whichever indicator you use (e.g. only needs typeorm installed if you use TypeOrmHealthIndicator), checked via lib/utils/checkPackage.util.ts which throws a descriptive error if the peer dependency is missing. Built with pnpm workspaces and tested against a docker-compose.yml stack of real database services for integration coverage.

Code Quality — Indicator services and the check-executor carry .spec.ts unit tests (health-check.service.spec.ts, health-check-executor.service.spec.ts, http.health.spec.ts, grpc.health.spec.ts, graceful-shutdown-timeout.service.spec.ts), and the repo has a separate e2e/ directory exercising indicators against real services via the docker-compose stack rather than mocks alone — a meaningfully more rigorous test posture than typical for a peer-dependency-heavy integration package.

API Design — The @HealthCheck() + HealthCheckService.check([...]) pattern keeps a health endpoint to a few lines: pass an array of indicator function calls (() => this.db.pingCheck('database')) and Terminus handles aggregation, timeout, and response shaping. Each indicator follows the same .pingCheck(key, options) shape regardless of underlying dependency type, so adding a new check type to an existing endpoint requires no new mental model — a deliberate consistency choice across an otherwise heterogeneous set of integrations.