{"_id":"@dwtechs/healix-express","_rev":"5-aa28ea61f8bcd401dd6068fd7df2df36","name":"@dwtechs/healix-express","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@dwtechs/healix-express","version":"0.1.0","keywords":["Health","Health check"],"author":{"url":"http://www.lcluber.com","name":"Ludovic Cluber","email":"http://www.lcluber.com/contact"},"license":"MIT","_id":"@dwtechs/healix-express@0.1.0","maintainers":[{"name":"dwtechs","email":"ludoclub@hotmail.com"}],"contributors":[],"homepage":"https://github.com/DWTechs/Healix-express.js","bugs":{"url":"https://github.com/DWTechs/Healix-express.js/issues"},"dist":{"shasum":"ee61a847e6d1769525d0641a631d0ed21eb9414e","tarball":"https://registry.npmjs.org/@dwtechs/healix-express/-/healix-express-0.1.0.tgz","fileCount":5,"integrity":"sha512-8esjQvYv87WcfwLZT3+sfS8hoDdpue1KtUAOKqP0fsca+l4XtoFOuBWDVpibYpyux6GtBL2ZQ/IRK9ccK2wA5g==","signatures":[{"sig":"MEQCIFF6BdWv82XIf6w7iPrm+yAecZqoi5W4tO4Lh6QP69DsAiBTkY/F7S1xv1gZhxjX4X2ngPU5z58KRKGCcz/5fXpNpQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":10102},"main":"dist/healix-express","types":"dist/healix-express","gitHead":"7642883129c89f3fcc8ec3e02cf7de0a38482f1c","scripts":{"test":"jest --coverage","build":"node ./scripts/clear && tsc && npm run rollup && node ./scripts/copy && npm run test","start":"","rollup":"npm run rollup:mjs","prebuild":"npm install","rollup:cjs":"rollup --config rollup.config.cjs.mjs","rollup:mjs":"rollup --config rollup.config.mjs"},"_npmUser":{"name":"dwtechs","email":"ludoclub@hotmail.com"},"repository":{"url":"git+https://github.com/DWTechs/Healix-express.js.git","type":"git"},"_npmVersion":"10.2.4","description":"Open source health check route for Express.js services.","directories":{},"_nodeVersion":"20.11.0","dependencies":{"express":"5.1.0"},"_hasShrinkwrap":false,"devDependencies":{"jest":"29.7.0","rollup":"4.24.0","core-js":"3.38.1","babel-jest":"29.7.0","typescript":"5.9.2","@types/express":"5.0.3","@babel/preset-env":"7.26.0","@rollup/plugin-node-resolve":"15.3.0"},"_npmOperationalInternal":{"tmp":"tmp/healix-express_0.1.0_1763495622726_0.6106296950327565","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@dwtechs/healix-express","version":"0.1.1","keywords":["Health","Health check"],"author":{"url":"http://www.lcluber.com","name":"Ludovic Cluber","email":"http://www.lcluber.com/contact"},"license":"MIT","_id":"@dwtechs/healix-express@0.1.1","maintainers":[{"name":"dwtechs","email":"ludoclub@hotmail.com"}],"contributors":[],"homepage":"https://github.com/DWTechs/Healix-express.js","bugs":{"url":"https://github.com/DWTechs/Healix-express.js/issues"},"dist":{"shasum":"fc98e879f63a3893cf4da2b5e828096e5bec0132","tarball":"https://registry.npmjs.org/@dwtechs/healix-express/-/healix-express-0.1.1.tgz","fileCount":6,"integrity":"sha512-15E1Cg6GmGwc4PBaMcyMpFYa4ibIgbNHvU30nuYWTk3TiASNuXnQOz+ohfEMfsSXrOjVLecO4MRfr5FoJKk0eA==","signatures":[{"sig":"MEUCIQDAi8D5MxdFID5OXcZylF9/CH34/3zSPcVfDm/rYzOxIAIgSDd2X83ebkmNEh90fOFi0ts7StjNKKHq1txfH4sRN3w=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":11380},"main":"dist/healix-express.js","type":"module","types":"dist/healix-express.d.ts","gitHead":"40e910526800b3e29961d76ec77bb36ccb25a8d2","scripts":{"test":"jest --coverage","build":"node ./scripts/clear.cjs && tsc && npm run rollup && node ./scripts/copy.cjs && npm run test","start":"","rollup":"npm run rollup:mjs","prebuild":"npm install","rollup:cjs":"rollup --config rollup.config.cjs.mjs","rollup:mjs":"rollup --config rollup.config.mjs"},"_npmUser":{"name":"dwtechs","email":"ludoclub@hotmail.com"},"repository":{"url":"git+https://github.com/DWTechs/Healix-express.js.git","type":"git"},"_npmVersion":"10.9.8","description":"Open source health check route for Express.js services.","directories":{},"_nodeVersion":"22.22.3","dependencies":{"express":"5.1.0"},"_hasShrinkwrap":false,"devDependencies":{"jest":"29.7.0","rollup":"4.24.0","core-js":"3.38.1","supertest":"7.1.1","babel-jest":"29.7.0","typescript":"5.9.2","@types/express":"5.0.3","@babel/preset-env":"7.26.0","@rollup/plugin-node-resolve":"15.3.0"},"_npmOperationalInternal":{"tmp":"tmp/healix-express_0.1.1_1786048389843_0.798033063414564","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@dwtechs/healix-express","version":"0.2.0","keywords":["Health","Health check","Readiness","Liveness"],"author":{"name":"Ludovic Cluber"},"license":"MIT","_id":"@dwtechs/healix-express@0.2.0","maintainers":[{"name":"dwtechs","email":"ludoclub@hotmail.com"}],"contributors":[],"homepage":"https://github.com/DWTechs/Healix-express.js","bugs":{"url":"https://github.com/DWTechs/Healix-express.js/issues"},"dist":{"shasum":"5d30e3e859f2507e2201c0d34165054b11168e76","tarball":"https://registry.npmjs.org/@dwtechs/healix-express/-/healix-express-0.2.0.tgz","fileCount":6,"integrity":"sha512-UfwCHF911Jxz9x0Fxw32uZyoTnmWbEeNbQCcsu53Mj/yC9nq/6ZqKL1TwGxIX3tuNxA273aPGl2oKScoUWWe3w==","signatures":[{"sig":"MEQCIB+pq22MD33OG5QDZYxi9a6P1sD+adbjhwtXUyvPiCAuAiAJP1KI8uPQYjhISySIyya3aABGKMkQL1eVwpCI5Zqzbw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":16067},"main":"dist/healix-express.js","type":"module","types":"dist/healix-express.d.ts","gitHead":"1d0b54d497f33d9f908130bfc307f4598b09b10b","scripts":{"test":"jest --coverage","build":"node ./scripts/clear.cjs && tsc && npm run rollup && node ./scripts/copy.cjs && npm run test","start":"","rollup":"npm run rollup:mjs","prebuild":"npm install","rollup:cjs":"rollup --config rollup.config.cjs.mjs","rollup:mjs":"rollup --config rollup.config.mjs"},"_npmUser":{"name":"dwtechs","email":"ludoclub@hotmail.com"},"repository":{"url":"git+https://github.com/DWTechs/Healix-express.js.git","type":"git"},"_npmVersion":"10.9.8","description":"Open source health check and readiness routes for Express.js services.","directories":{},"_nodeVersion":"22.22.3","dependencies":{"express":"5.1.0"},"_hasShrinkwrap":false,"devDependencies":{"jest":"29.7.0","rollup":"4.24.0","core-js":"3.38.1","supertest":"7.1.1","babel-jest":"29.7.0","typescript":"5.9.2","@types/express":"5.0.3","@babel/preset-env":"7.26.0","@rollup/plugin-node-resolve":"15.3.0"},"_npmOperationalInternal":{"tmp":"tmp/healix-express_0.2.0_1786745917634_0.022161450120086412","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2025-11-18T19:53:42.665Z","modified":"2026-09-12T06:29:30.189Z","0.1.0":"2025-11-18T19:53:42.920Z","0.1.1":"2026-08-06T20:33:10.021Z","0.2.0":"2026-08-14T22:18:37.800Z"},"bugs":{"url":"https://github.com/DWTechs/Healix-express.js/issues"},"author":{"name":"Ludovic Cluber"},"license":"MIT","homepage":"https://github.com/DWTechs/Healix-express.js","keywords":["Health","Health check","Readiness","Liveness"],"repository":{"url":"git+https://github.com/DWTechs/Healix-express.js.git","type":"git"},"description":"Open source health check and readiness routes for Express.js services.","contributors":[],"maintainers":[{"email":"ludoclub@hotmail.com","name":"lcluber_alten"},{"email":"ludovic.cluber@gmail.com","name":"lcluber"}],"readme":"\n[![License: MIT](https://img.shields.io/npm/l/@dwtechs/healix-express.svg?color=brightgreen)](https://opensource.org/licenses/MIT)\n[![npm version](https://badge.fury.io/js/%40dwtechs%2Fhealix-express.svg)](https://www.npmjs.com/package/@dwtechs/healix-express)\n[![last version release date](https://img.shields.io/github/release-date/DWTechs/Healix-express.js)](https://www.npmjs.com/package/@dwtechs/healix-express)\n![Jest:coverage](https://img.shields.io/badge/Jest:coverage-100%25-brightgreen.svg)\n\n\n- [Synopsis](#synopsis)\n- [Support](#support)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Health Check Script](#health-check-script)\n- [Logs](#logs)\n- [Contributors](#contributors)\n- [Stack](#stack)\n\n\n## Synopsis\n\n**[Healix-express.js](https://github.com/DWTechs/Healix-express.js)** is an open source health check and readiness route for Express.js services.  \n\n- 🪶 Very lightweight\n- ⚡ High performance\n- 🔧 Easy to use\n- 🧪 Thoroughly tested\n- 🚚 Shipped as ECMAScript Express route\n- 📝 Written in TypeScript\n\n\n## Support\n\n- node: 22\n\nThis is the oldest targeted version.  \n\n\n## Installation\n\n```bash\n$ npm i @dwtechs/healix-express\n```\n\n\n## Usage\n\n```javascript\nimport express from \"express\";\nimport { healix } from \"@dwtechs/healix-express\";\nimport { errorHandler } from \"@dwtechs/errandler-express\";\n\nconst app = express();\napp.disable(\"x-powered-by\");\n\n// Mandatory health check endpoint\napp.use(\"/health\", healix({\n  checks: {\n    db: () => pool.query(\"SELECT 1\"),\n  },\n}));\n\n// Your application routes\napp.use(\"/api/users\", ...);\napp.use(\"/api/products\", ...);\n\n// Error handling (must be last)\nerrorHandler(app);\n\napp.listen(3000, () => {\n  console.log(\"Server running on port 3000\");\n  console.log(\"Liveness  available at http://localhost:3000/health\");\n  console.log(\"Readiness available at http://localhost:3000/health/ready\");\n});\n```\n\n### Liveness vs readiness\n\nTwo questions, two endpoints — conflating them is why a service with a dead\ndatabase keeps receiving traffic.\n\n| | Question | Runs your checks? | On failure |\n| :--- | :--- | :---: | :--- |\n| `GET /` | Is the process alive? | no | orchestrator restarts the container |\n| `GET /ready` | Can it serve traffic? | yes | instance is pulled from the load balancer |\n\nLiveness deliberately ignores dependencies. If a database outage failed the\nliveness probe, every instance would be killed and restarted in a loop while the\nreal problem sat elsewhere.\n\n\n### Options\n\n```typescript\nhealix({\n  checks?: Record<string, () => unknown | Promise<unknown>>; // default {}\n  timeoutMs?: number;  // per-check budget, default 2000\n  readyPath?: string;  // default \"/ready\"\n});\n```\n\nA check is healthy when it returns or resolves, and unhealthy when it throws or\nrejects. Its resolved value is ignored. Checks run in parallel, each under its\nown `timeoutMs`, so one hung dependency cannot hold the probe open.\n\n\n### Endpoint: GET /\n\nLiveness. Never touches a dependency.\n\n**Response (200 OK):**\n\n```typescript\n{\n  status: \"ok\";        // Always \"ok\"\n  uptime: number;      // Process uptime in seconds\n  timestamp: number;   // Current Unix timestamp in milliseconds\n}\n```\n\n\n### Endpoint: GET /ready\n\nReadiness. Runs every configured check and reports them by name.\n\n**Response (200 OK / 503 Service Unavailable):**\n\n```typescript\n{\n  status: \"ready\" | \"unavailable\";\n  timestamp: number;\n  checks: Record<string, {\n    status: \"ok\" | \"error\";\n    durationMs: number;\n    error?: string;    // present only when the check failed or timed out\n  }>;\n}\n```\n\n```json\n{\n  \"status\": \"unavailable\",\n  \"timestamp\": 1700000000000,\n  \"checks\": {\n    \"db\": { \"status\": \"error\", \"durationMs\": 2000, \"error\": \"timed out after 2000ms\" },\n    \"cache\": { \"status\": \"ok\", \"durationMs\": 0 }\n  }\n}\n```\n\n## Health Check Script\n\nThe package includes a standalone health check script (`test.js`) designed for container orchestrators like Docker Compose and Kubernetes.\n\n### Usage with Docker Compose\n\nPoint the container healthcheck at readiness: a container that is running but\ncannot reach its database should be reported unhealthy, not left in rotation.\n\n```yaml\nservices:\n  my-service:\n    image: my-app\n    environment:\n      - PORT=3000\n      - HOST=127.0.0.1\n      - HEALTH_PATH=/health/ready\n    healthcheck:\n      test: [\"CMD\", \"node\", \"/usr/src/app/node_modules/@dwtechs/healix-express.js/dist/test.js\"]\n      interval: 30s\n      timeout: 3s\n      retries: 3\n      start_period: 10s\n```\n\n### Usage with Kubernetes\n\nThe two probes must target different paths. Pointing `readinessProbe` at the\nliveness endpoint makes it pass whenever the process is up, which defeats it.\n\n```yaml\nlivenessProbe:\n  exec:\n    command: [\"node\", \"/usr/src/app/node_modules/@dwtechs/healix-express.js/dist/test.js\"]\n  initialDelaySeconds: 10\n  periodSeconds: 30\n  timeoutSeconds: 3\nreadinessProbe:\n  exec:\n    command: [\"sh\", \"-c\", \"HEALTH_PATH=/health/ready node /usr/src/app/node_modules/@dwtechs/healix-express.js/dist/test.js\"]\n  initialDelaySeconds: 5\n  periodSeconds: 10\n```\n\n### Environment Variables\n\n- `PORT`: The port your service listens on (default: `3000`)\n- `HOST`: The host to check (default: `127.0.0.1`)\n- `HEALTH_PATH`: The path to request (default: `/health`; use `/health/ready` for readiness)\n- `HEALTH_TIMEOUT`: Request timeout in milliseconds (default: `2000`)\n\nThe script makes an HTTP GET request to `http://${HOST}:${PORT}${HEALTH_PATH}` and exits with:\n- Exit code `0` if the check returns HTTP 200\n- Exit code `1` if the check fails or times out\n\n## Stack\n\n| Purpose         |                    Choice                    |                                                     Motivation |\n| :-------------- | :------------------------------------------: | -------------------------------------------------------------: |\n| repository      |        [Github](https://github.com/)         |     hosting for software development version control using Git |\n| package manager |     [npm](https://www.npmjs.com/get-npm)     |                                default node.js package manager |\n| language        | [TypeScript](https://www.typescriptlang.org) | static type checking along with the latest ECMAScript features |\n| module bundler  |      [Rollup](https://rollupjs.org)          |                        advanced module bundler for ES6 modules |\n| unit testing    |          [Jest](https://jestjs.io/)          |                  delightful testing with a focus on simplicity |\n","readmeFilename":"README.md"}