healthzkit 0.0.1

package/README.md

@@ -0,0 +1,166 @@
+# healthzkit
+
+Framework-agnostic **liveness** and **readiness** probes for Node.js (and similar runtimes). You define checks as small adapters; **healthzkit** runs them in parallel, rolls up overall status, maps that to HTTP status and a JSON or plain-text body, and optionally **schedules** checks in the background so probes can read cached results instead of hitting dependencies on every request.
+
+## Install
+
+```bash
+npm install healthzkit
+```
+
+The package is ESM-only (`"type": "module"`). The published entry is `./dist/index.mjs` (see `package.json` `exports`).
+
+## Quick start
+
+```ts
+import { createHealthKit } from "healthzkit";
+
+const kit = createHealthKit({
+  checks: [
+    {
+      name: "db",
+      type: ["readiness"],
+      adapter: {
+        check: async () => {
+          // ping your database, etc.
+          return { status: "ok" };
+        },
+      },
+    },
+    {
+      name: "process",
+      type: ["liveness"],
+      adapter: { check: async () => ({ status: "ok" }) },
+    },
+  ],
+});
+
+// Wire into your HTTP server: path + method from the incoming request
+const res = await kit.handleRequest({ path: "/healthz/ready", method: "GET" });
+if (res) {
+  // res.status, res.headers, res.body
+}
+```
+
+Call `kit.handleLiveness()` or `kit.handleReadiness()` directly if you already route those endpoints yourself.
+
+## Routes and `basePath`
+
+By default, **healthzkit** expects:
+
+| Path               | Behavior                                        |
+| ------------------ | ----------------------------------------------- |
+| `{basePath}/live`  | Runs checks whose `type` includes `"liveness"`  |
+| `{basePath}/ready` | Runs checks whose `type` includes `"readiness"` |
+
+Default `basePath` is `/healthz`. Override with `basePath` in config (e.g. `/api/health` → `/api/health/live`).
+
+`handleRequest(req)` returns `null` if `req.path` does not match either route, so you can try it first and fall through to your app.
+
+## Checks and adapters
+
+Each check is a `CheckConfig`:
+
+- **`name`** — Key in the response `checks` object.
+- **`type`** — One or both of `"liveness"` and `"readiness"`. Only checks that include the probe type run for that probe. If none match, the response is still **200** with an empty `checks` object.
+- **`adapter`** — Must implement `HealthAdapter`: `check(): Promise<AdapterResult>`.
+- **`timeout`** — Per-check timeout in ms. Default is **5000**, unless overridden by `defaults.timeout`.
+- **`schedule`** — Optional `{ intervalMs }`. When `kit.start()` has been called, the adapter runs on that interval and results are **cached** (see [Scheduling](#scheduling)).
+- **`onFail`** — Optional `httpStatus`, `treatAs` (e.g. map `"fail"` to `"degraded"` for rollup and body while adjusting HTTP status rules).
+- **`onDegraded`** — Optional on `CheckConfig` in the type definition only; degraded HTTP status is set via **`defaults.onDegraded`** (see [HTTP status](#http-status)).
+
+`AdapterResult`:
+
+- **`status`**: `"ok" | "degraded" | "fail"`.
+- **`error`**: Optional `Error` or string (included in the serialized check unless `output.exposeError` is `false`).
+- **`metadata`**: Optional object merged into the check result.
+
+Thrown errors from `adapter.check()` are treated as **`fail`** with the error message captured when `exposeError` is true.
+
+## Scheduling
+
+For expensive checks (database, external APIs), you can run them on a timer and serve probes from cache:
+
+```ts
+const kit = createHealthKit({
+  checks: [
+    {
+      name: "db",
+      type: ["readiness"],
+      adapter: { check: async () => ({ status: "ok" }) },
+      schedule: { intervalMs: 30_000 },
+    },
+  ],
+});
+
+kit.start(); // starts background intervals for checks that define schedule
+// ... on shutdown:
+kit.stop();
+```
+
+- **`start()`** is idempotent (second call is a no-op).
+- **`stop()`** clears intervals and the cache.
+- When a cached result is used, that check’s **`latency`** is **0** and **`cachedAt`** is an ISO timestamp on the check result.
+
+Scheduled runs use **`adapter.check()`** directly (no per-request timeout wrapper in the scheduler). Timeouts still apply when there is **no** cache entry and the probe executes the check on demand.
+
+Timers use `unref` when available so they do not keep the process alive by themselves.
+
+## Rollup status
+
+Overall `HealthResponse.status` is computed from all check results for that probe:
+
+1. Any **`fail`** → **`fail`** (unless remapped by `onFail.treatAs` on that check).
+2. Else any **`degraded`** → **`degraded`**.
+3. Else **`ok`**.
+
+Override with `rollup.computeStatus(results)` for custom rules.
+
+## HTTP status
+
+Response **`status`** (HTTP code) is derived from the rolled-up health status and your config:
+
+- Any check with **`status === "fail"`** and **`onFail.httpStatus`** set → that value is returned (first matching check in config order wins among failed checks with a custom status).
+- Else if rollup is **`fail`**: `defaults.onFail.httpStatus` or **503**.
+- Else if rollup is **`degraded`**: `defaults.onDegraded.httpStatus` or **200**.
+- Else **200**.
+
+Note: `onFail.treatAs` changes the **check** status used for rollup and JSON/text body; combine with `onFail.httpStatus` / defaults if you need a specific HTTP code.
+
+## Output
+
+`output` on the root config:
+
+- **`format`**: `"json"` (default) or `"text"`.
+  - JSON: `Content-Type: application/json`, body is `JSON.stringify` of `HealthResponse`.
+  - Text: `Content-Type: text/plain`, human-readable lines (`status:`, then each check with latency and optional error).
+- **`exposeError`**: Default **true**. If **false**, the `error` field is omitted from each check in the payload.
+
+## Types (public API)
+
+Exported from `healthzkit`:
+
+**Runtime**
+
+- `createHealthKit(config)` → `HealthKit`
+- `HealthKit`: `start()`, `stop()`, `handleRequest(req)`, `handleLiveness()`, `handleReadiness()`
+
+**Types**
+
+- `HealthkitConfig`, `CheckConfig`, `HealthAdapter`, `AdapterResult`, `CheckResult`, `HealthResponse`
+- `CheckStatus`, `CheckType`, `RollupConfig`, `OutputConfig`, `DefaultsConfig`
+- `AgnosticRequest`, `AgnosticResponse`
+
+`AgnosticResponse` is `{ status: number; headers: Record<string, string>; body: string }` so you can map it to Express, Fastify, `fetch` `Response`, etc.
+
+## Development (this repo)
+
+From the package directory:
+
+```bash
+vp install
+vp test
+vp pack
+```
+
+See the repo root `AGENTS.md` for Vite+ / `vp` conventions.

package/dist/index.d.mts

@@ -0,0 +1,101 @@
+//#region src/types.d.ts
+type CheckStatus = "ok" | "degraded" | "fail";
+type CheckType = "liveness" | "readiness";
+type OutputFormat = "json" | "text";
+interface AdapterResult {
+  status: CheckStatus;
+  error?: Error | string;
+  metadata?: Record<string, unknown>;
+}
+interface HealthAdapter {
+  check(): Promise<AdapterResult>;
+}
+interface CheckConfig {
+  name: string;
+  type: CheckType[];
+  adapter: HealthAdapter;
+  timeout?: number;
+  schedule?: {
+    intervalMs: number;
+  };
+  onFail?: {
+    httpStatus?: number;
+    treatAs?: CheckStatus;
+  };
+  onDegraded?: {
+    httpStatus?: number;
+  };
+}
+interface CheckResult {
+  status: CheckStatus;
+  latency: number;
+  error?: string;
+  metadata?: Record<string, unknown>;
+  cachedAt?: string;
+}
+interface HealthResponse {
+  status: CheckStatus;
+  timestamp: string;
+  checks: Record<string, CheckResult>;
+}
+interface RollupConfig {
+  /**
+   * Custom function to determine top-level status from all check results.
+   * Defaults to:
+   * * any fail -> fail
+   * * any degraded -> degraded
+   * * else ok
+   */
+  computeStatus?: (results: Record<string, CheckResult>) => CheckStatus;
+}
+interface OutputConfig {
+  format?: OutputFormat;
+  /**
+   * Expose error messages in the response.
+   * Default: true
+   */
+  exposeError?: boolean;
+}
+interface DefaultsConfig {
+  onFail?: {
+    httpStatus?: number;
+  };
+  onDegraded?: {
+    httpStatus?: number;
+  };
+  timeout?: number;
+}
+interface HealthkitConfig {
+  checks: CheckConfig[];
+  basePath?: string;
+  rollup?: RollupConfig;
+  output?: OutputConfig;
+  defaults?: DefaultsConfig;
+}
+interface AgnosticRequest {
+  path: string;
+  method?: string;
+}
+interface AgnosticResponse {
+  status: number;
+  headers: Record<string, string>;
+  body: string;
+}
+//#endregion
+//#region src/healthkit.d.ts
+declare class HealthKit {
+  private config;
+  private scheduler;
+  private started;
+  constructor(config: HealthkitConfig);
+  start(): void;
+  stop(): void;
+  handleLiveness(): Promise<AgnosticResponse>;
+  handleReadiness(): Promise<AgnosticResponse>;
+  handleRequest(req: AgnosticRequest): Promise<AgnosticResponse | null>;
+  private runForType;
+  private resolveHttpStatus;
+}
+declare function createHealthKit(config: HealthkitConfig): HealthKit;
+//#endregion
+export { type AdapterResult, type AgnosticRequest, type AgnosticResponse, type CheckConfig, type CheckResult, type CheckStatus, type CheckType, type DefaultsConfig, type HealthAdapter, HealthKit, type HealthResponse, type HealthkitConfig, type OutputConfig, type RollupConfig, createHealthKit };

package/dist/index.mjs

@@ -0,0 +1,2 @@
+function e(e){return JSON.stringify(e)}function t(e){let t=[`status: ${e.status}`];for(let[n,r]of Object.entries(e.checks)){let e=`${n}: ${r.status} (${r.latency}ms)`;r.error&&(e+=` - ${r.error}`),t.push(e)}return t.join(`
+`)}function n(n,r=`json`){switch(r){case`text`:return{body:t(n),contentType:`text/plain`};default:return{body:e(n),contentType:`application/json`}}}const r=e=>{let t=Object.values(e).map(e=>e.status);return t.includes(`fail`)?`fail`:t.includes(`degraded`)?`degraded`:`ok`};function i(e,t){return(t?.computeStatus??r)(e)}async function a(e,t,n){let r,i=new Promise((e,i)=>{r=setTimeout(()=>i(Error(`Check "${n}" timed out after ${t}ms`)),t)});try{return await Promise.race([e,i])}finally{clearTimeout(r)}}async function o(e,t){let n=Date.now();try{return{result:await a(e.adapter.check(),t,e.name),latency:Date.now()-n}}catch(e){return{result:{status:`fail`,error:e instanceof Error?e:Error(String(e))},latency:Date.now()-n}}}async function s(e,t,n=5e3,r=!0){let i=await Promise.all(e.map(async e=>{let i=e.timeout??n,a=t.getCache(e.name),s,c,l;a?(s=a.result,c=0,l=a.cachedAt.toISOString()):{result:s,latency:c}=await o(e,i);let u=s.status===`fail`&&e.onFail?.treatAs?e.onFail.treatAs:s.status,d=s.error instanceof Error?s.error.message:s.error,f={status:u,latency:c,...s.metadata&&{metadata:s.metadata},...l&&{cachedAt:l},...r&&d&&{error:d}};return[e.name,f]}));return Object.fromEntries(i)}var c=class{timers=new Map;cache=new Map;start(e){for(let t of e){if(!t.schedule||this.timers.has(t.name))continue;this.runAndCache(t);let e=setInterval(()=>this.runAndCache(t),t.schedule.intervalMs);e.unref&&e.unref(),this.timers.set(t.name,e)}}stop(){for(let e of this.timers.values())clearInterval(e);this.timers.clear(),this.cache.clear()}getCache(e){return this.cache.get(e)}async runAndCache(e){try{let t=await e.adapter.check();this.cache.set(e.name,{result:t,cachedAt:new Date})}catch(t){this.cache.set(e.name,{result:{status:`fail`,error:t instanceof Error?t:Error(String(t))},cachedAt:new Date})}}},l=class{scheduler;started=!1;constructor(e){this.config=e,this.scheduler=new c}start(){this.started||=(this.scheduler.start(this.config.checks),!0)}stop(){this.scheduler.stop(),this.started=!1}async handleLiveness(){return this.runForType(`liveness`)}async handleReadiness(){return this.runForType(`readiness`)}async handleRequest(e){let t=this.config.basePath??`/healthz`,{path:n}=e;return n===`${t}/live`?this.handleLiveness():n===`${t}/ready`?this.handleReadiness():null}async runForType(e){let t=this.config.checks.filter(t=>t.type.includes(e)),{output:r,defaults:a,rollup:o}=this.config,c=r?.exposeError??!0,l=a?.timeout,u=await s(t,this.scheduler,l,c),d=i(u,o),{body:f,contentType:p}=n({status:d,timestamp:new Date().toISOString(),checks:u},r?.format);return{status:this.resolveHttpStatus(d,t,u),headers:{"Content-Type":p},body:f}}resolveHttpStatus(e,t,n){let{defaults:r}=this.config;for(let e of t)if(n[e.name]?.status===`fail`&&e.onFail?.httpStatus!==void 0)return e.onFail.httpStatus;return e===`fail`?r?.onFail?.httpStatus??503:e===`degraded`?r?.onDegraded?.httpStatus??200:200}};function u(e){return new l(e)}export{l as HealthKit,u as createHealthKit};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "healthzkit",
+  "version": "0.0.1",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "@typescript/native-preview": "7.0.0-dev.20260328.1",
+    "bumpp": "^11.0.1",
+    "tsdown": "^0.21.10",
+    "typescript": "^6.0.2",
+    "vite-plus": "^0.1.14"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check"
+  }
+}