@quanticjs/health 3.1.0

package/README.md

@@ -0,0 +1,389 @@
+# @quanticjs/health
+
+Health check module for QuanticJS applications. Provides liveness, readiness, and startup probes with auto-detection, caching, and multiple transports for both HTTP and non-HTTP apps.
+
+## Installation
+
+Already included in the `@quanticjs/quanticjs` umbrella. For standalone use:
+
+```bash
+npm install @quanticjs/health
+```
+
+## Quick Start
+
+### HTTP API (most common)
+
+```typescript
+import { Module } from '@nestjs/common';
+import { QuanticCoreModule } from '@quanticjs/core';
+import { QuanticHealthModule } from '@quanticjs/health';
+
+@Module({
+  imports: [
+    QuanticCoreModule.forRoot(),
+    QuanticHealthModule.forRoot({
+      transport: { type: 'controller' },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+This registers three endpoints on your existing NestJS server:
+
+| Endpoint | Probe | Purpose |
+|----------|-------|---------|
+| `GET /health/live` | Liveness | Is the process alive? Restart if not. |
+| `GET /health/ready` | Readiness | Can this instance serve traffic? Remove from LB if not. |
+| `GET /health/startup` | Startup | Has the app finished initializing? |
+
+All endpoints are public (no auth required) and return:
+
+```json
+{
+  "status": "ok",
+  "checks": {
+    "database": { "status": "ok", "latency_ms": 2 },
+    "redis": { "status": "ok", "latency_ms": 1 }
+  },
+  "timestamp": "2026-05-18T10:32:01.123Z"
+}
+```
+
+Status code is `200` when all checks pass, `503` when any check fails.
+
+## Auto-Detection
+
+When `autoDetect` is enabled (the default), the module scans the NestJS DI container on startup and registers checks automatically:
+
+| Dependency | Detection | Probe | Check |
+|------------|-----------|-------|-------|
+| TypeORM `DataSource` | `typeorm` installed + DataSource in DI | readiness | `SELECT 1` |
+| Redis (`REDIS_CLIENT`) | `QuanticRedisModule` imported | readiness | `redis.ping()` |
+| Event loop | Always | liveness | `setImmediate` responsiveness |
+
+No configuration needed for framework-managed dependencies. The module logs what it discovers:
+
+```
+[HealthRegistry] Auto-detected DataSource → database readiness check
+[HealthRegistry] Auto-detected Redis → redis readiness check
+[HealthRegistry] readiness: [database, redis]
+[HealthRegistry] liveness: [event_loop]
+```
+
+Disable with `autoDetect: false`.
+
+## Custom Checks
+
+Add product-specific checks for dependencies the framework doesn't know about.
+
+### Function checks
+
+```typescript
+QuanticHealthModule.forRoot({
+  transport: { type: 'controller' },
+  readiness: [
+    {
+      name: 'minio',
+      check: async () => {
+        const exists = await minioClient.bucketExists('my-bucket');
+        if (!exists) throw new Error('Bucket not found');
+      },
+      timeoutMs: 5000, // optional, default 3000
+    },
+  ],
+  startup: [
+    {
+      name: 'migrations',
+      check: async () => {
+        if (!migrationService.isComplete()) throw new Error('Migrations pending');
+      },
+    },
+  ],
+})
+```
+
+The check function should **resolve** when healthy and **throw** when unhealthy.
+
+### HTTP checks
+
+For external services, pass a `url` instead of a `check` function:
+
+```typescript
+QuanticHealthModule.forRoot({
+  transport: { type: 'controller' },
+  readiness: [
+    { name: 'ai-gateway', url: 'http://ai-gateway:3005/health' },
+    { name: 'kogito', url: 'http://kogito:8080/q/health/live', timeoutMs: 5000 },
+  ],
+})
+```
+
+HTTP checks expect a 2xx response. Any other status or network error marks the check as unhealthy.
+
+## Transports
+
+The transport determines **how** probes reach the app.
+
+### `controller` — HTTP API apps
+
+Mounts on the existing NestJS HTTP server. Endpoints: `/health/live`, `/health/ready`, `/health/startup`.
+
+```typescript
+QuanticHealthModule.forRoot({
+  transport: { type: 'controller' },
+})
+```
+
+### `standalone` — Workers, consumers, queue processors
+
+Spins up a minimal HTTP server on a **separate port**. No NestJS overhead — just raw `http.createServer`.
+
+```typescript
+QuanticHealthModule.forRoot({
+  transport: { type: 'standalone', port: 9091 },
+})
+```
+
+Endpoints: `/live`, `/ready`, `/startup` (no `/health` prefix since this is a dedicated health server).
+
+Use this for apps that have no HTTP server but still need K8s/Docker health probes.
+
+### `file` — Cron jobs, one-shot migration scripts
+
+Writes a JSON file when healthy, deletes it when unhealthy. Probes check file existence.
+
+```typescript
+QuanticHealthModule.forRoot({
+  transport: {
+    type: 'file',
+    path: '/tmp/.healthy',    // optional, default '/tmp/.healthy'
+    intervalMs: 10000,        // optional, default 10000
+  },
+})
+```
+
+Docker healthcheck: `test: ["CMD", "test", "-f", "/tmp/.healthy"]`
+
+### `none` — Programmatic only
+
+No endpoints, no files. Inject `HealthRegistry` directly for custom usage:
+
+```typescript
+@Injectable()
+export class MyService {
+  constructor(private readonly health: HealthRegistry) {}
+
+  async checkDeps() {
+    const report = await this.health.evaluate('readiness');
+    if (report.status === 'error') {
+      // handle unhealthy state
+    }
+  }
+}
+```
+
+## Result Caching
+
+By default, check results are cached for 5 seconds to avoid hammering dependencies on high-frequency probe intervals.
+
+```typescript
+QuanticHealthModule.forRoot({
+  transport: { type: 'controller' },
+  cacheTtlMs: 10000, // cache for 10s
+})
+```
+
+Set to `0` to disable caching (every probe hit runs all checks).
+
+## Shutdown Integration
+
+When the app receives SIGTERM, the module:
+
+1. Flips readiness to `503` immediately (before `GracefulShutdownService` runs)
+2. Waits `shutdownDelayMs` (default 5s) for the load balancer to observe the change
+3. Then `GracefulShutdownService` proceeds with its drain + cleanup
+
+```json
+{
+  "status": "error",
+  "reason": "shutting_down",
+  "checks": {},
+  "timestamp": "2026-05-18T10:35:00.000Z"
+}
+```
+
+This ensures no new traffic arrives while the app is draining in-flight work.
+
+```typescript
+QuanticHealthModule.forRoot({
+  transport: { type: 'controller' },
+  shutdownAware: true,      // default true
+  shutdownDelayMs: 5000,    // default 5000
+})
+```
+
+Disable with `shutdownAware: false` if you don't need this behavior.
+
+## Docker Compose
+
+```yaml
+backend:
+  healthcheck:
+    test: ["CMD", "wget", "-q", "--spider", "http://127.0.0.1:3000/health/ready"]
+    interval: 10s
+    timeout: 5s
+    retries: 3
+    start_period: 30s
+
+worker:
+  healthcheck:
+    test: ["CMD", "wget", "-q", "--spider", "http://127.0.0.1:9091/ready"]
+    interval: 10s
+    timeout: 5s
+    retries: 3
+    start_period: 15s
+
+migration-job:
+  healthcheck:
+    test: ["CMD", "test", "-f", "/tmp/.healthy"]
+    interval: 5s
+    retries: 3
+```
+
+## Kubernetes
+
+```yaml
+# HTTP API
+spec:
+  containers:
+    - name: backend
+      livenessProbe:
+        httpGet:
+          path: /health/live
+          port: 3000
+        periodSeconds: 10
+        failureThreshold: 3
+      readinessProbe:
+        httpGet:
+          path: /health/ready
+          port: 3000
+        periodSeconds: 10
+        failureThreshold: 3
+      startupProbe:
+        httpGet:
+          path: /health/startup
+          port: 3000
+        periodSeconds: 5
+        failureThreshold: 30
+
+---
+# Worker (standalone transport)
+spec:
+  containers:
+    - name: worker
+      livenessProbe:
+        httpGet:
+          path: /live
+          port: 9091
+      readinessProbe:
+        httpGet:
+          path: /ready
+          port: 9091
+```
+
+## Registering Checks Programmatically
+
+Inject `HealthRegistry` to register checks at runtime:
+
+```typescript
+@Injectable()
+export class KafkaConsumer implements OnModuleInit {
+  constructor(private readonly health: HealthRegistry) {}
+
+  onModuleInit() {
+    this.health.register('readiness', 'kafka', async () => {
+      if (!this.consumer.isConnected()) throw new Error('Kafka disconnected');
+    });
+  }
+}
+```
+
+## Full Options Reference
+
+```typescript
+interface HealthModuleOptions {
+  transport: HealthTransport;
+  autoDetect?: boolean;          // default: true
+  cacheTtlMs?: number;           // default: 5000
+  shutdownAware?: boolean;       // default: true
+  shutdownDelayMs?: number;      // default: 5000
+  readiness?: HealthCheckConfig[];
+  startup?: HealthCheckConfig[];
+  liveness?: HealthCheckConfig[];
+}
+
+// Custom function check
+interface CustomHealthCheck {
+  name: string;
+  check: () => Promise<void>;   // resolve = healthy, throw = unhealthy
+  timeoutMs?: number;            // default: 3000
+}
+
+// HTTP endpoint check
+interface HttpHealthCheck {
+  name: string;
+  url: string;
+  timeoutMs?: number;            // default: 3000
+}
+
+type HealthTransport =
+  | { type: 'controller' }
+  | { type: 'standalone'; port: number }
+  | { type: 'file'; path?: string; intervalMs?: number }
+  | { type: 'none' };
+```
+
+## Complete Example (AutoFlux-style)
+
+```typescript
+import { Module } from '@nestjs/common';
+import { QuanticCoreModule } from '@quanticjs/core';
+import { QuanticRedisModule } from '@quanticjs/redis';
+import { QuanticHealthModule } from '@quanticjs/health';
+
+@Module({
+  imports: [
+    QuanticCoreModule.forRoot(),
+    QuanticRedisModule.forRoot(),
+    // TypeOrmModule.forRoot({ ... }),
+
+    QuanticHealthModule.forRoot({
+      transport: { type: 'controller' },
+
+      // Auto-detects: database (TypeORM), redis, event_loop
+      // Add product-specific checks below:
+
+      readiness: [
+        { name: 'minio', check: async () => {
+          const exists = await minioClient.bucketExists('autoflux');
+          if (!exists) throw new Error('Bucket missing');
+        }},
+        { name: 'ai-gateway', url: 'http://ai-gateway:3005/health' },
+        { name: 'kogito', url: 'http://kogito:8080/q/health/live', timeoutMs: 5000 },
+      ],
+
+      startup: [
+        { name: 'templates-seeded', check: async () => {
+          if (!seederService.isComplete()) throw new Error('Seeding in progress');
+        }},
+      ],
+
+      cacheTtlMs: 5000,
+      shutdownDelayMs: 5000,
+    }),
+  ],
+})
+export class AppModule {}
+```

package/dist/FileHealthWriter.d.ts

@@ -0,0 +1,14 @@
+import { OnModuleInit, OnModuleDestroy } from '@nestjs/common';
+import { HealthRegistry } from './HealthRegistry';
+import { type HealthModuleOptions } from './interfaces';
+export declare class FileHealthWriter implements OnModuleInit, OnModuleDestroy {
+    private readonly registry;
+    private readonly options;
+    private readonly logger;
+    private timer?;
+    constructor(registry: HealthRegistry, options: HealthModuleOptions);
+    onModuleInit(): void;
+    onModuleDestroy(): void;
+    private write;
+    private getPath;
+}

package/dist/FileHealthWriter.js

@@ -0,0 +1,75 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+var FileHealthWriter_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileHealthWriter = void 0;
+const common_1 = require("@nestjs/common");
+const promises_1 = __importDefault(require("node:fs/promises"));
+const HealthRegistry_1 = require("./HealthRegistry");
+const interfaces_1 = require("./interfaces");
+const DEFAULT_PATH = '/tmp/.healthy';
+const DEFAULT_INTERVAL_MS = 10_000;
+let FileHealthWriter = FileHealthWriter_1 = class FileHealthWriter {
+    registry;
+    options;
+    logger = new common_1.Logger(FileHealthWriter_1.name);
+    timer;
+    constructor(registry, options) {
+        this.registry = registry;
+        this.options = options;
+    }
+    onModuleInit() {
+        if (this.options.transport.type !== 'file')
+            return;
+        const intervalMs = this.options.transport.intervalMs ?? DEFAULT_INTERVAL_MS;
+        this.timer = setInterval(() => this.write(), intervalMs);
+        this.write();
+    }
+    onModuleDestroy() {
+        if (this.timer)
+            clearInterval(this.timer);
+        const path = this.getPath();
+        promises_1.default.unlink(path).catch(() => { });
+    }
+    async write() {
+        const path = this.getPath();
+        try {
+            const report = await this.registry.evaluate('readiness');
+            if (report.status === 'ok') {
+                await promises_1.default.writeFile(path, JSON.stringify(report), 'utf-8');
+            }
+            else {
+                await promises_1.default.unlink(path).catch(() => { });
+            }
+        }
+        catch (err) {
+            this.logger.warn(`Failed to write health file: ${err.message}`);
+            await promises_1.default.unlink(path).catch(() => { });
+        }
+    }
+    getPath() {
+        return this.options.transport.type === 'file'
+            ? (this.options.transport.path ?? DEFAULT_PATH)
+            : DEFAULT_PATH;
+    }
+};
+exports.FileHealthWriter = FileHealthWriter;
+exports.FileHealthWriter = FileHealthWriter = FileHealthWriter_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(1, (0, common_1.Inject)(interfaces_1.HEALTH_OPTIONS)),
+    __metadata("design:paramtypes", [HealthRegistry_1.HealthRegistry, Object])
+], FileHealthWriter);

package/dist/HealthController.d.ts

@@ -0,0 +1,9 @@
+import { Response } from 'express';
+import { HealthRegistry } from './HealthRegistry';
+export declare class HealthController {
+    private readonly registry;
+    constructor(registry: HealthRegistry);
+    live(res: Response): Promise<void>;
+    ready(res: Response): Promise<void>;
+    startup(res: Response): Promise<void>;
+}

package/dist/HealthController.js

@@ -0,0 +1,63 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HealthController = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@quanticjs/core");
+const HealthRegistry_1 = require("./HealthRegistry");
+let HealthController = class HealthController {
+    registry;
+    constructor(registry) {
+        this.registry = registry;
+    }
+    async live(res) {
+        const report = await this.registry.evaluate('liveness');
+        res.status(report.status === 'ok' ? common_1.HttpStatus.OK : common_1.HttpStatus.SERVICE_UNAVAILABLE).json(report);
+    }
+    async ready(res) {
+        const report = await this.registry.evaluate('readiness');
+        res.status(report.status === 'ok' ? common_1.HttpStatus.OK : common_1.HttpStatus.SERVICE_UNAVAILABLE).json(report);
+    }
+    async startup(res) {
+        const report = await this.registry.evaluate('startup');
+        res.status(report.status === 'ok' ? common_1.HttpStatus.OK : common_1.HttpStatus.SERVICE_UNAVAILABLE).json(report);
+    }
+};
+exports.HealthController = HealthController;
+__decorate([
+    (0, common_1.Get)('live'),
+    __param(0, (0, common_1.Res)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], HealthController.prototype, "live", null);
+__decorate([
+    (0, common_1.Get)('ready'),
+    __param(0, (0, common_1.Res)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], HealthController.prototype, "ready", null);
+__decorate([
+    (0, common_1.Get)('startup'),
+    __param(0, (0, common_1.Res)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], HealthController.prototype, "startup", null);
+exports.HealthController = HealthController = __decorate([
+    (0, core_1.Public)(),
+    (0, common_1.Controller)('health'),
+    __metadata("design:paramtypes", [HealthRegistry_1.HealthRegistry])
+], HealthController);

package/dist/HealthRegistry.d.ts

@@ -0,0 +1,26 @@
+import { OnModuleInit } from '@nestjs/common';
+import { ModuleRef } from '@nestjs/core';
+import { type HealthModuleOptions, type HealthReport } from './interfaces';
+type ProbeType = 'liveness' | 'readiness' | 'startup';
+export declare class HealthRegistry implements OnModuleInit {
+    private readonly options;
+    private readonly moduleRef;
+    private readonly logger;
+    private shuttingDown;
+    private readonly checks;
+    private readonly cache;
+    constructor(options: HealthModuleOptions, moduleRef: ModuleRef);
+    onModuleInit(): void;
+    register(type: ProbeType, name: string, fn: () => Promise<void>, timeoutMs?: number): void;
+    setShuttingDown(): void;
+    isShuttingDown(): boolean;
+    evaluate(type: ProbeType): Promise<HealthReport>;
+    private runCheck;
+    private autoDetect;
+    private autoDetectDatabase;
+    private autoDetectRedis;
+    private registerConfigs;
+    private httpCheck;
+    private logRegistered;
+}
+export {};

package/dist/HealthRegistry.js

@@ -0,0 +1,200 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+var HealthRegistry_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HealthRegistry = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const core_2 = require("@quanticjs/core");
+const node_http_1 = __importDefault(require("node:http"));
+const interfaces_1 = require("./interfaces");
+const DEFAULT_TIMEOUT_MS = 3_000;
+const DEFAULT_CACHE_TTL_MS = 5_000;
+let HealthRegistry = HealthRegistry_1 = class HealthRegistry {
+    options;
+    moduleRef;
+    logger = new common_1.Logger(HealthRegistry_1.name);
+    shuttingDown = false;
+    checks = new Map([
+        ['liveness', new Map()],
+        ['readiness', new Map()],
+        ['startup', new Map()],
+    ]);
+    cache = new Map();
+    constructor(options, moduleRef) {
+        this.options = options;
+        this.moduleRef = moduleRef;
+    }
+    onModuleInit() {
+        if (this.options.autoDetect !== false) {
+            this.autoDetect();
+        }
+        this.registerConfigs('liveness', this.options.liveness);
+        this.registerConfigs('readiness', this.options.readiness);
+        this.registerConfigs('startup', this.options.startup);
+        this.logRegistered();
+    }
+    register(type, name, fn, timeoutMs = DEFAULT_TIMEOUT_MS) {
+        this.checks.get(type).set(name, { fn, timeoutMs });
+    }
+    setShuttingDown() {
+        this.shuttingDown = true;
+        this.cache.clear();
+    }
+    isShuttingDown() {
+        return this.shuttingDown;
+    }
+    async evaluate(type) {
+        if (type === 'readiness' && this.shuttingDown) {
+            return {
+                status: 'error',
+                reason: 'shutting_down',
+                checks: {},
+                timestamp: new Date().toISOString(),
+            };
+        }
+        const ttl = this.options.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
+        const cached = this.cache.get(type);
+        if (cached && Date.now() < cached.expiry) {
+            return cached.report;
+        }
+        const checkMap = this.checks.get(type);
+        const entries = [...checkMap.entries()];
+        if (entries.length === 0) {
+            const report = { status: 'ok', checks: {}, timestamp: new Date().toISOString() };
+            this.cache.set(type, { report, expiry: Date.now() + ttl });
+            return report;
+        }
+        const results = await Promise.allSettled(entries.map(([, { fn, timeoutMs }]) => this.runCheck(fn, timeoutMs)));
+        const checks = {};
+        let allOk = true;
+        for (let i = 0; i < entries.length; i++) {
+            const [name] = entries[i];
+            const result = results[i];
+            checks[name] = result.status === 'fulfilled'
+                ? result.value
+                : { status: 'error', latency_ms: 0, error: String(result.reason) };
+            if (checks[name].status === 'error')
+                allOk = false;
+        }
+        const report = {
+            status: allOk ? 'ok' : 'error',
+            checks,
+            timestamp: new Date().toISOString(),
+        };
+        this.cache.set(type, { report, expiry: Date.now() + ttl });
+        return report;
+    }
+    async runCheck(fn, timeoutMs) {
+        const start = performance.now();
+        try {
+            await Promise.race([
+                fn(),
+                new Promise((_, reject) => setTimeout(() => reject(new Error(`Timed out after ${timeoutMs}ms`)), timeoutMs)),
+            ]);
+            return { status: 'ok', latency_ms: Math.round(performance.now() - start) };
+        }
+        catch (err) {
+            return {
+                status: 'error',
+                latency_ms: Math.round(performance.now() - start),
+                error: err.message,
+            };
+        }
+    }
+    autoDetect() {
+        this.autoDetectDatabase();
+        this.autoDetectRedis();
+        this.register('liveness', 'event_loop', async () => {
+            await new Promise((resolve) => setImmediate(resolve));
+        });
+    }
+    autoDetectDatabase() {
+        try {
+            // Resolve DataSource without a compile-time dependency on typeorm
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const { DataSource } = require('typeorm');
+            const ds = this.moduleRef.get(DataSource, { strict: false });
+            if (ds?.isInitialized) {
+                this.register('readiness', 'database', async () => {
+                    await ds.query('SELECT 1');
+                });
+                this.logger.log('Auto-detected DataSource → database readiness check');
+            }
+        }
+        catch {
+            // typeorm not installed or DataSource not in DI container
+        }
+    }
+    autoDetectRedis() {
+        try {
+            const redis = this.moduleRef.get(core_2.REDIS_CLIENT, { strict: false });
+            if (redis?.ping) {
+                this.register('readiness', 'redis', async () => {
+                    const result = await redis.ping();
+                    if (result !== 'PONG')
+                        throw new Error(`Unexpected ping response: ${result}`);
+                });
+                this.logger.log('Auto-detected Redis → redis readiness check');
+            }
+        }
+        catch {
+            // Redis not in DI container
+        }
+    }
+    registerConfigs(type, configs) {
+        if (!configs)
+            return;
+        for (const config of configs) {
+            if ((0, interfaces_1.isHttpHealthCheck)(config)) {
+                const { name, url, timeoutMs = DEFAULT_TIMEOUT_MS } = config;
+                this.register(type, name, () => this.httpCheck(url, timeoutMs), timeoutMs);
+            }
+            else {
+                this.register(type, config.name, config.check, config.timeoutMs);
+            }
+        }
+    }
+    httpCheck(url, timeoutMs) {
+        return new Promise((resolve, reject) => {
+            const req = node_http_1.default.get(url, { timeout: timeoutMs }, (res) => {
+                res.resume();
+                if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {
+                    resolve();
+                }
+                else {
+                    reject(new Error(`HTTP ${res.statusCode}`));
+                }
+            });
+            req.on('error', (err) => reject(err));
+            req.on('timeout', () => { req.destroy(); reject(new Error('HTTP timeout')); });
+        });
+    }
+    logRegistered() {
+        for (const [type, checks] of this.checks) {
+            if (checks.size > 0) {
+                this.logger.log(`${type}: [${[...checks.keys()].join(', ')}]`);
+            }
+        }
+    }
+};
+exports.HealthRegistry = HealthRegistry;
+exports.HealthRegistry = HealthRegistry = HealthRegistry_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(interfaces_1.HEALTH_OPTIONS)),
+    __metadata("design:paramtypes", [Object, core_1.ModuleRef])
+], HealthRegistry);

package/dist/HealthShutdownHook.d.ts

@@ -0,0 +1,10 @@
+import { BeforeApplicationShutdown } from '@nestjs/common';
+import { HealthRegistry } from './HealthRegistry';
+import { type HealthModuleOptions } from './interfaces';
+export declare class HealthShutdownHook implements BeforeApplicationShutdown {
+    private readonly registry;
+    private readonly options;
+    private readonly logger;
+    constructor(registry: HealthRegistry, options: HealthModuleOptions);
+    beforeApplicationShutdown(): Promise<void>;
+}

package/dist/HealthShutdownHook.js

@@ -0,0 +1,46 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var HealthShutdownHook_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HealthShutdownHook = void 0;
+const common_1 = require("@nestjs/common");
+const HealthRegistry_1 = require("./HealthRegistry");
+const interfaces_1 = require("./interfaces");
+const DEFAULT_SHUTDOWN_DELAY_MS = 5_000;
+let HealthShutdownHook = HealthShutdownHook_1 = class HealthShutdownHook {
+    registry;
+    options;
+    logger = new common_1.Logger(HealthShutdownHook_1.name);
+    constructor(registry, options) {
+        this.registry = registry;
+        this.options = options;
+    }
+    async beforeApplicationShutdown() {
+        if (this.options.shutdownAware === false)
+            return;
+        this.registry.setShuttingDown();
+        this.logger.log('Readiness probe now returns 503');
+        const delay = this.options.shutdownDelayMs ?? DEFAULT_SHUTDOWN_DELAY_MS;
+        if (delay > 0) {
+            this.logger.log(`Waiting ${delay}ms for load balancer to observe readiness change...`);
+            await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+    }
+};
+exports.HealthShutdownHook = HealthShutdownHook;
+exports.HealthShutdownHook = HealthShutdownHook = HealthShutdownHook_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(1, (0, common_1.Inject)(interfaces_1.HEALTH_OPTIONS)),
+    __metadata("design:paramtypes", [HealthRegistry_1.HealthRegistry, Object])
+], HealthShutdownHook);

package/dist/QuanticHealthModule.d.ts

@@ -0,0 +1,5 @@
+import { DynamicModule } from '@nestjs/common';
+import { type HealthModuleOptions } from './interfaces';
+export declare class QuanticHealthModule {
+    static forRoot(options?: HealthModuleOptions): DynamicModule;
+}

package/dist/QuanticHealthModule.js

@@ -0,0 +1,49 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var QuanticHealthModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QuanticHealthModule = void 0;
+const common_1 = require("@nestjs/common");
+const HealthRegistry_1 = require("./HealthRegistry");
+const HealthController_1 = require("./HealthController");
+const StandaloneHealthServer_1 = require("./StandaloneHealthServer");
+const FileHealthWriter_1 = require("./FileHealthWriter");
+const HealthShutdownHook_1 = require("./HealthShutdownHook");
+const interfaces_1 = require("./interfaces");
+let QuanticHealthModule = QuanticHealthModule_1 = class QuanticHealthModule {
+    static forRoot(options = { transport: { type: 'controller' } }) {
+        const providers = [
+            { provide: interfaces_1.HEALTH_OPTIONS, useValue: options },
+            HealthRegistry_1.HealthRegistry,
+            HealthShutdownHook_1.HealthShutdownHook,
+        ];
+        const controllers = [];
+        switch (options.transport.type) {
+            case 'controller':
+                controllers.push(HealthController_1.HealthController);
+                break;
+            case 'standalone':
+                providers.push(StandaloneHealthServer_1.StandaloneHealthServer);
+                break;
+            case 'file':
+                providers.push(FileHealthWriter_1.FileHealthWriter);
+                break;
+        }
+        return {
+            module: QuanticHealthModule_1,
+            controllers,
+            providers,
+            exports: [HealthRegistry_1.HealthRegistry],
+        };
+    }
+};
+exports.QuanticHealthModule = QuanticHealthModule;
+exports.QuanticHealthModule = QuanticHealthModule = QuanticHealthModule_1 = __decorate([
+    (0, common_1.Global)(),
+    (0, common_1.Module)({})
+], QuanticHealthModule);

package/dist/StandaloneHealthServer.d.ts

@@ -0,0 +1,13 @@
+import { OnModuleInit, OnModuleDestroy } from '@nestjs/common';
+import { HealthRegistry } from './HealthRegistry';
+import { type HealthModuleOptions } from './interfaces';
+export declare class StandaloneHealthServer implements OnModuleInit, OnModuleDestroy {
+    private readonly registry;
+    private readonly options;
+    private readonly logger;
+    private server?;
+    constructor(registry: HealthRegistry, options: HealthModuleOptions);
+    onModuleInit(): Promise<void>;
+    onModuleDestroy(): Promise<void>;
+    private resolveProbe;
+}

package/dist/StandaloneHealthServer.js

@@ -0,0 +1,78 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+var StandaloneHealthServer_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StandaloneHealthServer = void 0;
+const common_1 = require("@nestjs/common");
+const node_http_1 = __importDefault(require("node:http"));
+const HealthRegistry_1 = require("./HealthRegistry");
+const interfaces_1 = require("./interfaces");
+let StandaloneHealthServer = StandaloneHealthServer_1 = class StandaloneHealthServer {
+    registry;
+    options;
+    logger = new common_1.Logger(StandaloneHealthServer_1.name);
+    server;
+    constructor(registry, options) {
+        this.registry = registry;
+        this.options = options;
+    }
+    async onModuleInit() {
+        if (this.options.transport.type !== 'standalone')
+            return;
+        const { port } = this.options.transport;
+        this.server = node_http_1.default.createServer(async (req, res) => {
+            const probe = this.resolveProbe(req.url);
+            if (!probe) {
+                res.writeHead(404).end();
+                return;
+            }
+            try {
+                const report = await this.registry.evaluate(probe);
+                const status = report.status === 'ok' ? 200 : 503;
+                res.writeHead(status, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify(report));
+            }
+            catch (err) {
+                res.writeHead(500).end(JSON.stringify({ status: 'error', error: String(err) }));
+            }
+        });
+        await new Promise((resolve) => this.server.listen(port, resolve));
+        this.logger.log(`Health probe server listening on port ${port}`);
+    }
+    async onModuleDestroy() {
+        if (!this.server)
+            return;
+        await new Promise((resolve, reject) => this.server.close((err) => (err ? reject(err) : resolve())));
+        this.logger.log('Health probe server closed');
+    }
+    resolveProbe(url) {
+        const path = url?.split('?')[0];
+        if (path === '/live')
+            return 'liveness';
+        if (path === '/ready')
+            return 'readiness';
+        if (path === '/startup')
+            return 'startup';
+        return null;
+    }
+};
+exports.StandaloneHealthServer = StandaloneHealthServer;
+exports.StandaloneHealthServer = StandaloneHealthServer = StandaloneHealthServer_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(1, (0, common_1.Inject)(interfaces_1.HEALTH_OPTIONS)),
+    __metadata("design:paramtypes", [HealthRegistry_1.HealthRegistry, Object])
+], StandaloneHealthServer);

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { QuanticHealthModule } from './QuanticHealthModule';
+export { HealthRegistry } from './HealthRegistry';
+export { HealthController } from './HealthController';
+export { StandaloneHealthServer } from './StandaloneHealthServer';
+export { FileHealthWriter } from './FileHealthWriter';
+export { HealthShutdownHook } from './HealthShutdownHook';
+export { HEALTH_OPTIONS, type HealthModuleOptions, type HealthTransport, type HealthCheckConfig, type CustomHealthCheck, type HttpHealthCheck, type HealthReport, type HealthCheckDetail, } from './interfaces';

package/dist/index.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HEALTH_OPTIONS = exports.HealthShutdownHook = exports.FileHealthWriter = exports.StandaloneHealthServer = exports.HealthController = exports.HealthRegistry = exports.QuanticHealthModule = void 0;
+var QuanticHealthModule_1 = require("./QuanticHealthModule");
+Object.defineProperty(exports, "QuanticHealthModule", { enumerable: true, get: function () { return QuanticHealthModule_1.QuanticHealthModule; } });
+var HealthRegistry_1 = require("./HealthRegistry");
+Object.defineProperty(exports, "HealthRegistry", { enumerable: true, get: function () { return HealthRegistry_1.HealthRegistry; } });
+var HealthController_1 = require("./HealthController");
+Object.defineProperty(exports, "HealthController", { enumerable: true, get: function () { return HealthController_1.HealthController; } });
+var StandaloneHealthServer_1 = require("./StandaloneHealthServer");
+Object.defineProperty(exports, "StandaloneHealthServer", { enumerable: true, get: function () { return StandaloneHealthServer_1.StandaloneHealthServer; } });
+var FileHealthWriter_1 = require("./FileHealthWriter");
+Object.defineProperty(exports, "FileHealthWriter", { enumerable: true, get: function () { return FileHealthWriter_1.FileHealthWriter; } });
+var HealthShutdownHook_1 = require("./HealthShutdownHook");
+Object.defineProperty(exports, "HealthShutdownHook", { enumerable: true, get: function () { return HealthShutdownHook_1.HealthShutdownHook; } });
+var interfaces_1 = require("./interfaces");
+Object.defineProperty(exports, "HEALTH_OPTIONS", { enumerable: true, get: function () { return interfaces_1.HEALTH_OPTIONS; } });

package/dist/interfaces.d.ts

@@ -0,0 +1,51 @@
+export declare const HEALTH_OPTIONS: unique symbol;
+export type HealthTransport = {
+    type: 'controller';
+} | {
+    type: 'standalone';
+    port: number;
+} | {
+    type: 'file';
+    path?: string;
+    intervalMs?: number;
+} | {
+    type: 'none';
+};
+export interface HealthModuleOptions {
+    transport: HealthTransport;
+    /** Scan DI container for DataSource/Redis and register checks automatically (default: true) */
+    autoDetect?: boolean;
+    /** Cache check results for this many ms (default: 5000) */
+    cacheTtlMs?: number;
+    /** Flip readiness to 503 on SIGTERM before draining (default: true) */
+    shutdownAware?: boolean;
+    /** Ms to wait after flipping readiness before shutdown proceeds (default: 5000) */
+    shutdownDelayMs?: number;
+    readiness?: HealthCheckConfig[];
+    startup?: HealthCheckConfig[];
+    liveness?: HealthCheckConfig[];
+}
+export type HealthCheckConfig = CustomHealthCheck | HttpHealthCheck;
+export interface CustomHealthCheck {
+    name: string;
+    /** Resolves = healthy, throws = unhealthy */
+    check: () => Promise<void>;
+    timeoutMs?: number;
+}
+export interface HttpHealthCheck {
+    name: string;
+    url: string;
+    timeoutMs?: number;
+}
+export interface HealthReport {
+    status: 'ok' | 'error';
+    reason?: string;
+    checks: Record<string, HealthCheckDetail>;
+    timestamp: string;
+}
+export interface HealthCheckDetail {
+    status: 'ok' | 'error';
+    latency_ms: number;
+    error?: string;
+}
+export declare function isHttpHealthCheck(check: HealthCheckConfig): check is HttpHealthCheck;

package/dist/interfaces.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HEALTH_OPTIONS = void 0;
+exports.isHttpHealthCheck = isHttpHealthCheck;
+exports.HEALTH_OPTIONS = Symbol('HEALTH_OPTIONS');
+function isHttpHealthCheck(check) {
+    return 'url' in check;
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@quanticjs/health",
+  "version": "3.1.0",
+  "description": "Health check module — liveness, readiness, startup probes with auto-detection, caching, and multiple transports",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "jest --passWithNoTests",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@quanticjs/core": "^3.1.0"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0"
+  }
+}