@firebreak/vitals 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,209 @@
+# Vitals (Node.js)
+
+Structured deep healthcheck endpoints for Node.js services. Register health checks, run them concurrently with timeouts, and expose them via Express.
+
+## Install
+
+```bash
+npm install vitals
+```
+
+Peer dependencies are optional — install only what you need:
+
+```bash
+npm install pg        # for PostgreSQL checks
+npm install ioredis   # for Redis checks
+npm install express   # for Express integration
+```
+
+## Quick Start
+
+```typescript
+import { HealthcheckRegistry, Status } from 'vitals';
+import { createHealthcheckMiddleware } from 'vitals/express';
+import { pgPoolCheck } from 'vitals/checks/postgres';
+import { ioredisClientCheck } from 'vitals/checks/redis';
+import express from 'express';
+
+const registry = new HealthcheckRegistry({ defaultTimeout: 5000 });
+
+// Add checks using an existing connection pool / client
+registry.add('postgres', pgPoolCheck(pool));
+registry.add('redis', ioredisClientCheck(redisClient));
+
+// Or add a custom check
+registry.add('api', async () => {
+  const start = Date.now();
+  const res = await fetch('https://api.example.com/ping');
+  return {
+    status: res.ok ? Status.HEALTHY : Status.OUTAGE,
+    latencyMs: Date.now() - start,
+    message: res.ok ? '' : `HTTP ${res.status}`,
+  };
+});
+
+// Mount as Express middleware
+const app = express();
+app.get('/healthcheck/deep', createHealthcheckMiddleware({
+  registry,
+  token: process.env.HEALTHCHECK_TOKEN,
+}));
+```
+
+## API
+
+### `HealthcheckRegistry`
+
+```typescript
+const registry = new HealthcheckRegistry({ defaultTimeout: 5000 });
+```
+
+**`registry.add(name, checkFn, options?)`**
+
+Register a named async check function. Options: `{ timeout?: number }`.
+
+```typescript
+registry.add('service', async () => ({
+  status: Status.HEALTHY,
+  latencyMs: 0,
+  message: '',
+}), { timeout: 3000 });
+```
+
+**`registry.check(name, checkFn?, options?)`**
+
+Decorator-style registration. Can be used as a method decorator or called directly.
+
+**`registry.run()`**
+
+Execute all registered checks concurrently. Returns a `HealthcheckResponse` with the worst overall status.
+
+```typescript
+const response = await registry.run();
+// { status: 2, timestamp: '...', checks: { service: { status: 2, latencyMs: 12, message: '' } } }
+
+const json = toJson(response);
+// { status: 'healthy', timestamp: '...', checks: { ... } }
+```
+
+### Status
+
+```typescript
+import { Status, statusToLabel, statusFromString, httpStatusCode } from 'vitals';
+
+Status.HEALTHY  // 2
+Status.DEGRADED // 1
+Status.OUTAGE   // 0
+
+statusToLabel(Status.HEALTHY) // 'healthy'
+statusFromString('degraded')  // Status.DEGRADED
+httpStatusCode(Status.HEALTHY) // 200
+httpStatusCode(Status.OUTAGE)  // 503
+```
+
+### Built-in Checks
+
+#### PostgreSQL
+
+```typescript
+import { pgClientCheck, pgPoolCheck } from 'vitals/checks/postgres';
+
+// Fresh connection each time (good for validating connectivity)
+registry.add('pg', pgClientCheck('postgresql://localhost:5432/mydb'));
+
+// Existing pg.Pool (good for production — reuses connections)
+registry.add('pg', pgPoolCheck(pool));
+```
+
+#### Redis
+
+```typescript
+import { ioredisCheck, ioredisClientCheck } from 'vitals/checks/redis';
+
+// Fresh connection each time
+registry.add('redis', ioredisCheck('redis://localhost:6379'));
+
+// Existing ioredis client
+registry.add('redis', ioredisClientCheck(client));
+```
+
+### Sync Checks
+
+Wrap synchronous functions to use as health checks:
+
+```typescript
+import { syncCheck, Status } from 'vitals';
+
+registry.add('disk', syncCheck(() => {
+  const free = checkDiskSpace('/');
+  return {
+    status: free > 1_000_000_000 ? Status.HEALTHY : Status.DEGRADED,
+    latencyMs: 0,
+    message: `${free} bytes free`,
+  };
+}));
+```
+
+### Express Integration
+
+```typescript
+import { createHealthcheckMiddleware } from 'vitals/express';
+
+app.get('/healthcheck/deep', createHealthcheckMiddleware({
+  registry,
+  token: 'my-secret-token',   // optional — omit to disable auth
+  queryParamName: 'token',     // default: 'token'
+}));
+```
+
+When a token is configured, requests must provide it via:
+- Query parameter: `?token=my-secret-token`
+- Bearer header: `Authorization: Bearer my-secret-token`
+
+### Authentication
+
+```typescript
+import { verifyToken, extractToken } from 'vitals';
+
+// Timing-safe token comparison
+verifyToken('provided-token', 'expected-token'); // boolean
+
+// Extract token from request
+const token = extractToken({
+  queryParams: { token: 'abc' },
+  authorizationHeader: 'Bearer abc',
+  queryParamName: 'token',
+});
+```
+
+## Response Format
+
+```json
+{
+  "status": "healthy",
+  "timestamp": "2025-02-26T12:00:00.000Z",
+  "checks": {
+    "postgres": {
+      "status": "healthy",
+      "latencyMs": 4.2,
+      "message": ""
+    },
+    "redis": {
+      "status": "healthy",
+      "latencyMs": 1.1,
+      "message": ""
+    }
+  }
+}
+```
+
+| Overall Status | HTTP Code |
+|---------------|-----------|
+| `healthy` | `200` |
+| `degraded` | `503` |
+| `outage` | `503` |
+| Auth failure | `403` |
+
+## Requirements
+
+- Node.js >= 20.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firebreak/vitals",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Deep healthcheck endpoints following the HEALTHCHECK_SPEC format",
   "type": "module",
   "exports": {