@plokkke/nest-health-registry

A powerful and flexible health check registry module for NestJS applications, built on top of @nestjs/terminus. This module provides a centralized way to manage and monitor the health of your application's dependencies and services.

Features

• 🔄 Dynamic health check registration
• 🏥 Separate liveness and readiness checks
• 🚀 Easy integration with NestJS applications
• 📊 Built-in health check endpoints
• 🔍 TypeScript support
• 🧪 Comprehensive test coverage
• 🧬 100% mutation testing coverage

Installation

npm install @plokkke/nest-health-registry

Quick Start

1. Import the HealthRegistryModule in your app module:

import { Module } from '@nestjs/common';
import { HealthRegistryModule } from '@plokkke/nest-health-registry';

@Module({
  imports: [HealthRegistryModule],
})
export class AppModule {}

2. Inject the HealthRegistryService where you need to add health checks:

import { Injectable } from '@nestjs/common';
import { HealthRegistryService } from '@plokkke/nest-health-registry';

@Injectable()
export class DatabaseService {
  constructor(private readonly healthRegistry: HealthRegistryService) {
    this.healthRegistry.addLivenessCheck('database', async () => {
      // Your database health check logic here
      return true;
    });

    this.healthRegistry.addReadinessCheck('cache', async () => {
      // Your cache health check logic here
      return true;
    });
  }
}

API Reference

HealthRegistryService

Methods

• addLivenessCheck(key: string, check: HealthCheck): void

  • Adds a new liveness check
  • Throws an error if the check key already exists

• addReadinessCheck(key: string, check: HealthCheck): void

  • Adds a new readiness check
  • Throws an error if the check key already exists

• removeLivenessCheck(key: string): void

  • Removes a liveness check
  • Throws an error if the check doesn't exist

• removeReadinessCheck(key: string): void

  • Removes a readiness check
  • Throws an error if the check doesn't exist

• checkLiveness(): Promise<HealthCheckResult>

  • Runs all registered liveness checks
  • Returns the combined health check result

• checkReadiness(): Promise<HealthCheckResult>

  • Runs all registered readiness checks
  • Returns the combined health check result

HealthController

The module provides a controller with the following endpoints:

• GET /health/startup

  • Startup health check endpoint
  • Returns 204 No Content
  • Useful for initial application health verification

• GET /health/liveness

  • Liveness health check endpoint
  • Returns the status of all registered liveness checks
  • Used by container orchestrators to determine if the application is running

• GET /health/readiness

  • Readiness health check endpoint
  • Returns the status of all registered readiness checks
  • Used to determine if the application is ready to receive traffic

Example Response

{
  "status": "ok",
  "info": {
    "database": {
      "status": "up"
    },
    "cache": {
      "status": "up"
    }
  },
  "error": {},
  "details": {
    "database": {
      "status": "up"
    },
    "cache": {
      "status": "up"
    }
  }
}

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.