@firebreak/vitals 1.0.2 → 1.1.1

package/README.md

@@ -1,11 +1,11 @@
 # Vitals (Node.js)
 
-Structured deep healthcheck endpoints for Node.js services. Register health checks, run them concurrently with timeouts, and expose them via Express.
+Structured deep healthcheck endpoints for Node.js services. Register health checks, run them concurrently with timeouts, and expose them via Express or Next.js.
 
 ## Install
 
 ```bash
-npm install vitals
+npm install @firebreak/vitals
 ```
 
 Peer dependencies are optional — install only what you need:
@@ -16,40 +16,51 @@ npm install ioredis   # for Redis checks
 npm install express   # for Express integration
 ```
 
-## Quick Start
+## Quick Start (Express)
 
 ```typescript
-import { HealthcheckRegistry, Status } from 'vitals';
-import { createHealthcheckMiddleware } from 'vitals/express';
-import { pgPoolCheck } from 'vitals/checks/postgres';
-import { ioredisClientCheck } from 'vitals/checks/redis';
+import { HealthcheckRegistry } from '@firebreak/vitals';
+import { createHealthcheckMiddleware } from '@firebreak/vitals/express';
+import { pgPoolCheck } from '@firebreak/vitals/checks/postgres';
+import { ioredisClientCheck } from '@firebreak/vitals/checks/redis';
+import { httpCheck } from '@firebreak/vitals/checks/http';
 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));
+registry.add('api', httpCheck('https://api.example.com/health'));
 
-// 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({
+app.get('/vitals', createHealthcheckMiddleware({
   registry,
-  token: process.env.HEALTHCHECK_TOKEN,
+  token: process.env.VITALS_TOKEN,
 }));
 ```
 
+## Quick Start (Next.js)
+
+```typescript
+// app/vitals/route.ts
+import { HealthcheckRegistry } from '@firebreak/vitals';
+import { createNextHandler } from '@firebreak/vitals/next';
+import { pgClientCheck } from '@firebreak/vitals/checks/postgres';
+import { httpCheck } from '@firebreak/vitals/checks/http';
+
+const registry = new HealthcheckRegistry({ defaultTimeout: 5000 });
+
+if (process.env.DATABASE_URL) {
+  registry.add('postgres', pgClientCheck(process.env.DATABASE_URL));
+}
+registry.add('api', httpCheck(`${process.env.API_BASE_URL}/health`));
+
+export const GET = createNextHandler({
+  registry,
+  token: process.env.VITALS_TOKEN,
+});
+```
+
 ## API
 
 ### `HealthcheckRegistry`
@@ -65,18 +76,19 @@ Register a named async check function. Options: `{ timeout?: number }`.
 ```typescript
 registry.add('service', async () => ({
   status: Status.HEALTHY,
-  latencyMs: 0,
   message: '',
 }), { timeout: 3000 });
 ```
 
+Check functions return a `CheckInput` with `status` and `message`. The `latencyMs` field is optional — the registry measures wall-clock latency automatically using `performance.now()`.
+
 **`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.
+Execute all registered checks concurrently. Returns a `HealthcheckResponse` with the worst overall status and registry-measured latency for each check.
 
 ```typescript
 const response = await registry.run();
@@ -89,7 +101,7 @@ const json = toJson(response);
 ### Status
 
 ```typescript
-import { Status, statusToLabel, statusFromString, httpStatusCode } from 'vitals';
+import { Status, statusToLabel, statusFromString, httpStatusCode } from '@firebreak/vitals';
 
 Status.HEALTHY  // 2
 Status.DEGRADED // 1
@@ -103,10 +115,26 @@ httpStatusCode(Status.OUTAGE)  // 503
 
 ### Built-in Checks
 
+#### HTTP
+
+```typescript
+import { httpCheck } from '@firebreak/vitals/checks/http';
+
+// Basic URL check — returns HEALTHY if response is 2xx
+registry.add('api', httpCheck('https://api.example.com/health'));
+
+// With options
+registry.add('api', httpCheck('https://api.example.com/health', {
+  method: 'HEAD',
+  headers: { 'X-Api-Key': 'secret' },
+  timeout: 3000, // default: 5000ms
+}));
+```
+
 #### PostgreSQL
 
 ```typescript
-import { pgClientCheck, pgPoolCheck } from 'vitals/checks/postgres';
+import { pgClientCheck, pgPoolCheck } from '@firebreak/vitals/checks/postgres';
 
 // Fresh connection each time (good for validating connectivity)
 registry.add('pg', pgClientCheck('postgresql://localhost:5432/mydb'));
@@ -118,7 +146,7 @@ registry.add('pg', pgPoolCheck(pool));
 #### Redis
 
 ```typescript
-import { ioredisCheck, ioredisClientCheck } from 'vitals/checks/redis';
+import { ioredisCheck, ioredisClientCheck } from '@firebreak/vitals/checks/redis';
 
 // Fresh connection each time
 registry.add('redis', ioredisCheck('redis://localhost:6379'));
@@ -127,48 +155,89 @@ registry.add('redis', ioredisCheck('redis://localhost:6379'));
 registry.add('redis', ioredisClientCheck(client));
 ```
 
+### Custom Checks
+
+Check functions only need to return `status` and `message`. The registry measures latency automatically:
+
+```typescript
+registry.add('databricks', async () => {
+  try {
+    await databricksService.query('SELECT 1');
+    return { status: Status.HEALTHY, message: '' };
+  } catch (error) {
+    return { status: Status.OUTAGE, message: error.message };
+  }
+});
+```
+
 ### 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`,
-  };
-}));
+import { syncCheck, Status } from '@firebreak/vitals';
+
+registry.add('disk', syncCheck(() => ({
+  status: checkDiskSpace('/') > 1_000_000_000 ? Status.HEALTHY : Status.DEGRADED,
+  message: '',
+})));
 ```
 
-### Express Integration
+### Framework Integrations
+
+#### Express
 
 ```typescript
-import { createHealthcheckMiddleware } from 'vitals/express';
+import { createHealthcheckMiddleware } from '@firebreak/vitals/express';
 
-app.get('/healthcheck/deep', createHealthcheckMiddleware({
+app.get('/vitals', createHealthcheckMiddleware({
   registry,
   token: 'my-secret-token',   // optional — omit to disable auth
   queryParamName: 'token',     // default: 'token'
 }));
 ```
 
+#### Next.js (App Router)
+
+```typescript
+import { createNextHandler } from '@firebreak/vitals/next';
+
+export const GET = createNextHandler({
+  registry,
+  token: process.env.VITALS_TOKEN,
+});
+```
+
+#### Framework-Agnostic Handler
+
+For other frameworks, use the generic handler directly:
+
+```typescript
+import { createHealthcheckHandler } from '@firebreak/vitals';
+
+const handle = createHealthcheckHandler({ registry, token: process.env.VITALS_TOKEN });
+
+// In any framework:
+const result = await handle({
+  queryParams: { token: 'abc' },
+  authorizationHeader: 'Bearer abc',
+});
+// result = { status: 200, body: { status: 'healthy', ... } }
+```
+
+### Authentication
+
 When a token is configured, requests must provide it via:
 - Query parameter: `?token=my-secret-token`
 - Bearer header: `Authorization: Bearer my-secret-token`
 
-### Authentication
+Tokens are compared using timing-safe SHA-256 comparison.
 
 ```typescript
-import { verifyToken, extractToken } from 'vitals';
+import { verifyToken, extractToken } from '@firebreak/vitals';
 
-// Timing-safe token comparison
 verifyToken('provided-token', 'expected-token'); // boolean
 
-// Extract token from request
 const token = extractToken({
   queryParams: { token: 'abc' },
   authorizationHeader: 'Bearer abc',
@@ -185,12 +254,12 @@ const token = extractToken({
   "checks": {
     "postgres": {
       "status": "healthy",
-      "latencyMs": 4.2,
+      "latencyMs": 4,
       "message": ""
     },
     "redis": {
       "status": "healthy",
-      "latencyMs": 1.1,
+      "latencyMs": 1,
       "message": ""
     }
   }

package/dist/checks/databricks.cjs

@@ -0,0 +1,57 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/checks/databricks.ts
+var databricks_exports = {};
+__export(databricks_exports, {
+  databricksCheck: () => databricksCheck
+});
+module.exports = __toCommonJS(databricks_exports);
+
+// src/types.ts
+var Status = {
+  HEALTHY: 2,
+  DEGRADED: 1,
+  OUTAGE: 0
+};
+
+// src/checks/databricks.ts
+function databricksCheck(client) {
+  return async () => {
+    let session;
+    let op;
+    try {
+      session = await client.openSession();
+      op = await session.executeStatement("SELECT 1");
+      return { status: Status.HEALTHY, message: "" };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return { status: Status.OUTAGE, message };
+    } finally {
+      op?.close().catch(() => {
+      });
+      session?.close().catch(() => {
+      });
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  databricksCheck
+});

package/dist/checks/databricks.d.cts

@@ -0,0 +1,23 @@
+import { A as AsyncCheckFn } from '../core-BJ2Z0rRi.cjs';
+
+/**
+ * Minimal interface for a connected Databricks SQL client.
+ * Avoids a hard dependency on `@databricks/sql`.
+ */
+interface DatabricksClient {
+    openSession(): Promise<DatabricksSession>;
+}
+interface DatabricksSession {
+    executeStatement(statement: string, options?: Record<string, unknown>): Promise<DatabricksOperation>;
+    close(): Promise<void>;
+}
+interface DatabricksOperation {
+    close(): Promise<void>;
+}
+/**
+ * Creates a healthcheck function that opens a session on an existing
+ * Databricks SQL client, runs `SELECT 1`, and closes the session.
+ */
+declare function databricksCheck(client: DatabricksClient): AsyncCheckFn;
+
+export { AsyncCheckFn, type DatabricksClient, type DatabricksOperation, type DatabricksSession, databricksCheck };

package/dist/checks/databricks.d.ts

@@ -0,0 +1,23 @@
+import { A as AsyncCheckFn } from '../core-BJ2Z0rRi.js';
+
+/**
+ * Minimal interface for a connected Databricks SQL client.
+ * Avoids a hard dependency on `@databricks/sql`.
+ */
+interface DatabricksClient {
+    openSession(): Promise<DatabricksSession>;
+}
+interface DatabricksSession {
+    executeStatement(statement: string, options?: Record<string, unknown>): Promise<DatabricksOperation>;
+    close(): Promise<void>;
+}
+interface DatabricksOperation {
+    close(): Promise<void>;
+}
+/**
+ * Creates a healthcheck function that opens a session on an existing
+ * Databricks SQL client, runs `SELECT 1`, and closes the session.
+ */
+declare function databricksCheck(client: DatabricksClient): AsyncCheckFn;
+
+export { AsyncCheckFn, type DatabricksClient, type DatabricksOperation, type DatabricksSession, databricksCheck };

package/dist/checks/databricks.mjs

@@ -0,0 +1,30 @@
+// src/types.ts
+var Status = {
+  HEALTHY: 2,
+  DEGRADED: 1,
+  OUTAGE: 0
+};
+
+// src/checks/databricks.ts
+function databricksCheck(client) {
+  return async () => {
+    let session;
+    let op;
+    try {
+      session = await client.openSession();
+      op = await session.executeStatement("SELECT 1");
+      return { status: Status.HEALTHY, message: "" };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return { status: Status.OUTAGE, message };
+    } finally {
+      op?.close().catch(() => {
+      });
+      session?.close().catch(() => {
+      });
+    }
+  };
+}
+export {
+  databricksCheck
+};

package/dist/checks/http.cjs

@@ -0,0 +1,63 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/checks/http.ts
+var http_exports = {};
+__export(http_exports, {
+  httpCheck: () => httpCheck
+});
+module.exports = __toCommonJS(http_exports);
+
+// src/types.ts
+var Status = {
+  HEALTHY: 2,
+  DEGRADED: 1,
+  OUTAGE: 0
+};
+
+// src/checks/http.ts
+function httpCheck(url, options) {
+  const { method = "GET", headers, timeout = 5e3 } = options ?? {};
+  return async () => {
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), timeout);
+      try {
+        const res = await fetch(url, {
+          method,
+          headers,
+          signal: controller.signal
+        });
+        return {
+          status: res.ok ? Status.HEALTHY : Status.OUTAGE,
+          message: res.ok ? "" : `HTTP ${res.status}`
+        };
+      } finally {
+        clearTimeout(timeoutId);
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.name === "AbortError" ? `Request to ${url} timed out after ${timeout}ms` : error.message : String(error);
+      return { status: Status.OUTAGE, message };
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  httpCheck
+});

package/dist/checks/http.d.cts

@@ -0,0 +1,17 @@
+import { A as AsyncCheckFn } from '../core-BJ2Z0rRi.cjs';
+
+interface HttpCheckOptions {
+    /** HTTP method to use. Defaults to 'GET'. */
+    method?: string;
+    /** Request headers to include. */
+    headers?: Record<string, string>;
+    /** Timeout in milliseconds for the fetch call. Defaults to 5000. */
+    timeout?: number;
+}
+/**
+ * Creates a healthcheck function that fetches a URL and checks for an ok response.
+ * Returns HEALTHY if the response status is 2xx, OUTAGE otherwise.
+ */
+declare function httpCheck(url: string, options?: HttpCheckOptions): AsyncCheckFn;
+
+export { AsyncCheckFn, type HttpCheckOptions, httpCheck };

package/dist/checks/http.d.ts

@@ -0,0 +1,17 @@
+import { A as AsyncCheckFn } from '../core-BJ2Z0rRi.js';
+
+interface HttpCheckOptions {
+    /** HTTP method to use. Defaults to 'GET'. */
+    method?: string;
+    /** Request headers to include. */
+    headers?: Record<string, string>;
+    /** Timeout in milliseconds for the fetch call. Defaults to 5000. */
+    timeout?: number;
+}
+/**
+ * Creates a healthcheck function that fetches a URL and checks for an ok response.
+ * Returns HEALTHY if the response status is 2xx, OUTAGE otherwise.
+ */
+declare function httpCheck(url: string, options?: HttpCheckOptions): AsyncCheckFn;
+
+export { AsyncCheckFn, type HttpCheckOptions, httpCheck };

package/dist/checks/http.mjs

@@ -0,0 +1,36 @@
+// src/types.ts
+var Status = {
+  HEALTHY: 2,
+  DEGRADED: 1,
+  OUTAGE: 0
+};
+
+// src/checks/http.ts
+function httpCheck(url, options) {
+  const { method = "GET", headers, timeout = 5e3 } = options ?? {};
+  return async () => {
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), timeout);
+      try {
+        const res = await fetch(url, {
+          method,
+          headers,
+          signal: controller.signal
+        });
+        return {
+          status: res.ok ? Status.HEALTHY : Status.OUTAGE,
+          message: res.ok ? "" : `HTTP ${res.status}`
+        };
+      } finally {
+        clearTimeout(timeoutId);
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.name === "AbortError" ? `Request to ${url} timed out after ${timeout}ms` : error.message : String(error);
+      return { status: Status.OUTAGE, message };
+    }
+  };
+}
+export {
+  httpCheck
+};

package/dist/checks/postgres.cjs

@@ -34,7 +34,6 @@ __export(postgres_exports, {
   pgPoolCheck: () => pgPoolCheck
 });
 module.exports = __toCommonJS(postgres_exports);
-var import_node_perf_hooks = require("perf_hooks");
 
 // src/types.ts
 var Status = {
@@ -46,18 +45,15 @@ var Status = {
 // src/checks/postgres.ts
 function pgClientCheck(connectionString, options) {
   return async () => {
-    const start = import_node_perf_hooks.performance.now();
     const { Client } = await import("pg");
     const client = new Client({ connectionString, ...options });
     try {
       await client.connect();
       await client.query("SELECT 1");
-      const latencyMs = Math.round(import_node_perf_hooks.performance.now() - start);
-      return { status: Status.HEALTHY, latencyMs, message: "" };
+      return { status: Status.HEALTHY, message: "" };
     } catch (error) {
-      const latencyMs = Math.round(import_node_perf_hooks.performance.now() - start);
       const message = error instanceof Error ? error.message : String(error);
-      return { status: Status.OUTAGE, latencyMs, message };
+      return { status: Status.OUTAGE, message };
     } finally {
       client.end().catch(() => {
       });
@@ -66,17 +62,14 @@ function pgClientCheck(connectionString, options) {
 }
 function pgPoolCheck(pool) {
   return async () => {
-    const start = import_node_perf_hooks.performance.now();
     let client;
     try {
       client = await pool.connect();
       await client.query("SELECT 1");
-      const latencyMs = Math.round(import_node_perf_hooks.performance.now() - start);
-      return { status: Status.HEALTHY, latencyMs, message: "" };
+      return { status: Status.HEALTHY, message: "" };
     } catch (error) {
-      const latencyMs = Math.round(import_node_perf_hooks.performance.now() - start);
       const message = error instanceof Error ? error.message : String(error);
-      return { status: Status.OUTAGE, latencyMs, message };
+      return { status: Status.OUTAGE, message };
     } finally {
       client?.release();
     }

package/dist/checks/postgres.d.cts

@@ -1,4 +1,4 @@
-import { A as AsyncCheckFn } from '../core-9-MXAO0I.cjs';
+import { A as AsyncCheckFn } from '../core-BJ2Z0rRi.cjs';
 import { Pool } from 'pg';
 
 /**

package/dist/checks/postgres.d.ts

@@ -1,4 +1,4 @@
-import { A as AsyncCheckFn } from '../core-9-MXAO0I.js';
+import { A as AsyncCheckFn } from '../core-BJ2Z0rRi.js';
 import { Pool } from 'pg';
 
 /**

package/dist/checks/postgres.mjs

@@ -1,6 +1,3 @@
-// src/checks/postgres.ts
-import { performance } from "perf_hooks";
-
 // src/types.ts
 var Status = {
   HEALTHY: 2,
@@ -11,18 +8,15 @@ var Status = {
 // src/checks/postgres.ts
 function pgClientCheck(connectionString, options) {
   return async () => {
-    const start = performance.now();
     const { Client } = await import("pg");
     const client = new Client({ connectionString, ...options });
     try {
       await client.connect();
       await client.query("SELECT 1");
-      const latencyMs = Math.round(performance.now() - start);
-      return { status: Status.HEALTHY, latencyMs, message: "" };
+      return { status: Status.HEALTHY, message: "" };
     } catch (error) {
-      const latencyMs = Math.round(performance.now() - start);
       const message = error instanceof Error ? error.message : String(error);
-      return { status: Status.OUTAGE, latencyMs, message };
+      return { status: Status.OUTAGE, message };
     } finally {
       client.end().catch(() => {
       });
@@ -31,17 +25,14 @@ function pgClientCheck(connectionString, options) {
 }
 function pgPoolCheck(pool) {
   return async () => {
-    const start = performance.now();
     let client;
     try {
       client = await pool.connect();
       await client.query("SELECT 1");
-      const latencyMs = Math.round(performance.now() - start);
-      return { status: Status.HEALTHY, latencyMs, message: "" };
+      return { status: Status.HEALTHY, message: "" };
     } catch (error) {
-      const latencyMs = Math.round(performance.now() - start);
       const message = error instanceof Error ? error.message : String(error);
-      return { status: Status.OUTAGE, latencyMs, message };
+      return { status: Status.OUTAGE, message };
     } finally {
       client?.release();
     }