healthzkit 0.0.4 → 0.1.0

package/README.md

@@ -1,53 +1,132 @@
 # 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.
+Framework-agnostic **liveness** and **readiness** probes for Node.js. 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
+Docs: [healthzkit.dev](https://healthzkit.dev)
 
 ```bash
-npm install healthzkit
+npm install healthzkit hono @healthzkit/postgres pg
 ```
 
-The package is ESM-only (`"type": "module"`). The published entry is `./dist/index.mjs` (see `package.json` `exports`).
+The package is ESM-only. Runtime: Node.js 22.12+ (CI). Other runtimes with `fetch` / `Response` work for the Fetch helper.
 
-## Quick start
+## Quick start (Hono)
 
 ```ts
-import { createHealthKit } from "healthzkit";
+import { Hono } from "hono";
+import { createHealthKit, toFetchResponse } from "healthzkit";
+import { pgAdapter } from "@healthzkit/postgres/pg";
 
 const kit = createHealthKit({
   checks: [
+    {
+      name: "process",
+      type: ["liveness"],
+      adapter: { check: async () => ({ status: "ok" }) },
+    },
     {
       name: "db",
       type: ["readiness"],
-      adapter: {
-        check: async () => {
-          // ping your database, etc.
-          return { status: "ok" };
-        },
-      },
+      adapter: pgAdapter({ connectionString: process.env.DATABASE_URL! }),
+      schedule: { intervalMs: 30_000 },
     },
+  ],
+});
+
+kit.start();
+
+const app = new Hono();
+app.get("/healthz/live", async () => toFetchResponse(await kit.handleLiveness()));
+app.get("/healthz/ready", async () => toFetchResponse(await kit.handleReadiness()));
+
+export default app;
+```
+
+Point Kubernetes (or any orchestrator) at `GET /healthz/live` and `GET /healthz/ready`. A failed readiness check returns **503** by default so the instance is taken out of rotation.
+
+## Fetch, Next.js, Bun, Workers
+
+`createFetchHandler` mounts the default routes on any Fetch-API server:
+
+```ts
+import { createFetchHandler, createHealthKit } from "healthzkit";
+
+const kit = createHealthKit({
+  checks: [
+    { name: "process", type: ["liveness"], adapter: { check: async () => ({ status: "ok" }) } },
+  ],
+});
+
+const handler = createFetchHandler(kit);
+
+Deno.serve(handler); // also: Bun.serve({ fetch: handler })
+```
+
+GET and HEAD are served on the live/ready routes; other methods on those routes return **405** with `Allow: GET, HEAD`. Unknown paths return **404**.
+
+```ts
+// app/healthz/live/route.ts  (Next.js App Router)
+import { createHealthKit, toFetchResponse } from "healthzkit";
+
+const kit = createHealthKit({
+  checks: [
     {
       name: "process",
-      type: ["liveness"],
+      type: ["liveness", "readiness"],
       adapter: { check: async () => ({ status: "ok" }) },
     },
   ],
 });
 
-// Wire into your HTTP server: path + method from the incoming request
+export const dynamic = "force-dynamic";
+export const GET = async () => toFetchResponse(await kit.handleLiveness());
+export const HEAD = async () => toFetchResponse(await kit.handleLiveness(), "HEAD");
+```
+
+## Express
+
+```ts
+import express from "express";
+import { createHealthKit } from "healthzkit";
+
+const kit = createHealthKit({
+  checks: [
+    {
+      name: "process",
+      type: ["liveness", "readiness"],
+      adapter: { check: async () => ({ status: "ok" }) },
+    },
+  ],
+});
+
+const app = express();
+app.get("/healthz/live", async (_req, res) => {
+  const out = await kit.handleLiveness();
+  res.status(out.status).set(out.headers).send(out.body);
+});
+app.get("/healthz/ready", async (_req, res) => {
+  const out = await kit.handleReadiness();
+  res.status(out.status).set(out.headers).send(out.body);
+});
+```
+
+More frameworks: [healthzkit.dev/guide/frameworks](https://healthzkit.dev/guide/frameworks).
+
+## `handleRequest`
+
+If you already have a router, pass the incoming path:
+
+```ts
 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.
+`handleRequest` returns `null` when the path is not a probe route, so you can try it first and fall through.
 
 ## Routes and `basePath`
 
-By default, **healthzkit** expects:
-
 | Path               | Behavior                                        |
 | ------------------ | ----------------------------------------------- |
 | `{basePath}/live`  | Runs checks whose `type` includes `"liveness"`  |
@@ -55,8 +134,6 @@ By default, **healthzkit** expects:
 
 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`:
@@ -77,9 +154,11 @@ Each check is a `CheckConfig`:
 
 Thrown errors from `adapter.check()` are treated as **`fail`** with the error message captured when `exposeError` is true.
 
+Official adapters (Postgres, Redis, Kafka, S3, Prisma, Drizzle, and more) live in [`@healthzkit/*` packages](https://healthzkit.dev).
+
 ## Scheduling
 
-For expensive checks (database, external APIs), you can run them on a timer and serve probes from cache:
+For expensive checks (database, external APIs), run them on a timer and serve probes from cache:
 
 ```ts
 const kit = createHealthKit({
@@ -144,6 +223,8 @@ Exported from `healthzkit`:
 
 - `createHealthKit(config)` → `HealthKit`
 - `HealthKit`: `start()`, `stop()`, `handleRequest(req)`, `handleLiveness()`, `handleReadiness()`
+- `toFetchResponse(res, method?)` → Fetch `Response` (`HEAD` omits the body)
+- `createFetchHandler(kit)` → `(request: Request) => Promise<Response>`
 
 **Types**
 

package/dist/index.d.mts

@@ -92,10 +92,16 @@ declare class HealthKit {
   stop(): void;
   handleLiveness(): Promise<AgnosticResponse>;
   handleReadiness(): Promise<AgnosticResponse>;
+  /** True for `{basePath}/live` and `{basePath}/ready`. Does not run checks. */
+  matchHealthPath(path: string): boolean;
   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 };
+//#region src/http.d.ts
+declare function toFetchResponse(res: AgnosticResponse, method?: string): Response;
+declare function createFetchHandler(kit: HealthKit): (request: Request) => Promise<Response>;
+//#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, createFetchHandler, createHealthKit, toFetchResponse };

package/dist/index.mjs

@@ -1,2 +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{config;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};
+`)}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})}}};const l=`/healthz`;var u=class{config;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`)}matchHealthPath(e){let t=this.config.basePath??l;return e===`${t}/live`||e===`${t}/ready`}async handleRequest(e){let t=this.config.basePath??l,{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 d(e){return new u(e)}function f(e,t=`GET`){let n=t.toUpperCase()===`HEAD`?null:e.body;return new Response(n,{status:e.status,headers:e.headers})}const p={allow:`GET, HEAD`};function m(e){return async t=>{let n=t.method.toUpperCase(),r=new URL(t.url).pathname;if(n!==`GET`&&n!==`HEAD`)return e.matchHealthPath(r)?new Response(null,{status:405,headers:p}):new Response(null,{status:404});let i=await e.handleRequest({path:r,method:n});return i?f(i,n):new Response(null,{status:404})}}export{u as HealthKit,m as createFetchHandler,d as createHealthKit,f as toFetchResponse};

package/package.json

@@ -1,7 +1,30 @@
 {
   "name": "healthzkit",
-  "version": "0.0.4",
+  "version": "0.1.0",
+  "description": "Framework-agnostic Kubernetes liveness and readiness probes for Node.js. Parallel checks, status rollup, HTTP mapping, and optional background scheduling.",
+  "keywords": [
+    "express",
+    "health-check",
+    "healthcheck",
+    "healthz",
+    "healthzkit",
+    "hono",
+    "kubernetes",
+    "liveness",
+    "nextjs",
+    "nodejs",
+    "probe",
+    "readiness"
+  ],
+  "homepage": "https://healthzkit.dev",
+  "bugs": {
+    "url": "https://github.com/alasti-company/healthzkit.dev/issues"
+  },
   "license": "MIT",
+  "author": {
+    "name": "Alasti Company",
+    "url": "https://healthzkit.dev"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/alasti-company/healthzkit.dev",
@@ -26,6 +49,9 @@
     "typescript": "^5",
     "vite-plus": "0.3.0"
   },
+  "engines": {
+    "node": ">=22.12.0"
+  },
   "scripts": {
     "build": "vp pack",
     "dev": "vp pack --watch",