@zola_do/health

NestJS readiness/liveness helpers built on @nestjs/terminus, aligned with @zola_do env conventions (TypeORM, RabbitMQ audit, MinIO, Seaweed/S3).

Install

pnpm add @zola_do/health @nestjs/terminus

Optional peers (enable related checks only when installed and configured):

• @nestjs/typeorm, typeorm — database ping
• @nestjs/microservices, amqplib — RabbitMQ ping when RMQ_URL is set

Usage

import { ZolaHealthModule } from '@zola_do/health';

@Module({
  imports: [
    TypeOrmModule.forRoot(/* ... */),
    ZolaHealthModule.forRoot({
      path: 'health',
      typeorm: true,
      rabbitmq: true,
      minio: true,
      seaweed: true,
      http: [{ name: 'docs', url: 'https://example.com/status' }],
    }),
  ],
})
export class AppModule {}

• path: controller route (default health → GET /health).
• typeorm: true (key database), a custom string key, or false to skip.
• rabbitmq: uses RMQ_URL and Terminus microservice ping (requires optional peers above).
• minio: GET http(s)://MINIO_ENDPOINT:MINIO_PORT/minio/health/live from MINIO_* env vars.
• seaweed: GET AWS_ENDPOINT (prefixes https:// if missing); treats HTTP ≥ 500 as down.
• http: extra { name, url } GET checks via fetch.

If @nestjs/terminus is not installed, the module registers a minimal GET /health JSON body (mode: 'minimal') so imports stay safe.

Split liveness and readiness (Kubernetes)

ZolaHealthModule.forRoot({
  splitLivenessReadiness: true,
  livenessPath: 'live',   // default
  readinessPath: 'ready', // default
  typeorm: true,
  rabbitmq: true,
})

| Probe | Path (default) | Checks | | ----- | -------------- | ------ | | Liveness | GET /live | Process up (heap memory) | | Readiness | GET /ready | Full dependency indicators (typeorm, rabbitmq, etc.) |

# kubernetes deployment excerpt
livenessProbe:
  httpGet:
    path: /live
    port: 3000
readinessProbe:
  httpGet:
    path: /ready
    port: 3000

When splitLivenessReadiness is false (default), a single GET /health runs all configured checks.

Global JWT guard

Use @ZolaHealthPublic() on custom health routes, or rely on the built-in controller: it sets the same allowAnonymous metadata key as @AllowAnonymous() from @zola_do/authorization.

Environment variables

| Check | Variables | | -------- | ---------------------------------------------------- | | TypeORM | Same as your app / @zola_do/typeorm (DATABASE_*) | | RabbitMQ | RMQ_URL | | MinIO | MINIO_ENDPOINT, MINIO_PORT, MINIO_USESSL | | Seaweed | AWS_ENDPOINT |

Optional OpenTelemetry trace IDs

import { getActiveTraceIds } from '@zola_do/health/optional/otel';

Requires optional peer @opentelemetry/api. Returns active traceId / spanId when an OTel SDK is installed in the app. See docs/OBSERVABILITY.md.

License

ISC

Diagnostics Roadmap

Diagnostics will be added inside this existing package rather than as a separate package. The target is an opt-in endpoint that reports package versions, optional peer availability, and redacted config status for support/debugging.

Enable it with:

ZolaHealthModule.forRoot({
  path: 'health',
  diagnostics: true,
});

This registers GET /health/diagnostics and returns redacted status only: enabled checks, optional peer availability, package versions when discoverable, and config presence status. It never returns secret values.

See docs/DIAGNOSTICS.md for the response shape and safety rules.