healthpoint - HTTP Server Health Check

1.0.0 · maintenance · verified Wed Apr 22

healthpoint is a lightweight Node.js utility designed to simplify the exposure of an HTTP server's health status. It provides a straightforward function that returns an HTTP request handler, allowing developers to easily integrate health check endpoints into their applications. The package, currently stable at version 1.0.0, operates on a `require`-based CommonJS module system, indicating a focus on compatibility with established Node.js environments. Its release cadence is likely slow or non-existent, given its simple, self-contained functionality. Key differentiators include its minimal API, ease of integration into existing `http` servers, and the ability to customize both the static properties exposed in the health check JSON and a dynamic asynchronous `check` function for custom health logic (e.g., database connectivity). Unlike more complex monitoring agents, healthpoint provides a focused, on-demand health status report directly from the application.

Common errors

```
TypeError: healthpoint is not a function
```
cause Attempting to `import healthpoint from 'healthpoint'` in an ESM module, or incorrect CommonJS `require` syntax.

fix Ensure you are using `const healthpoint = require('healthpoint');` in a CommonJS module context. If in an ESM project, consider using dynamic `import()` if your Node.js version supports it for CJS modules, or check if a transpiler is configured to handle CJS.
```
Health check endpoint hangs or always returns pending status.
```
cause The custom `check` function passed to `healthpoint` is not calling its `callback` argument, preventing the health check response from being sent.

fix Verify that your asynchronous `check` logic consistently calls `cb(null)` for success or `cb(new Error('reason'))` for failure. Every code path within your `check` function must eventually invoke the callback.

Warnings

gotcha The `healthpoint` package is exclusively CommonJS (`require`) and does not natively support ECMAScript Modules (`import`). Attempting to `import` it directly in a pure ESM environment will lead to errors.
Fix: Use `const healthpoint = require('healthpoint');` in CommonJS modules. For ESM projects, you might need to use a CommonJS wrapper, dynamic `import()` if Node.js version supports it, or a bundling tool that handles CommonJS modules.
gotcha The custom health check function provided to `healthpoint` expects a Node.js-style callback (`cb(err, result)`). Developers accustomed to Promises or `async/await` might incorrectly return a Promise or omit calling the callback, leading to unresponsive or incorrect health statuses.
Fix: Ensure your custom `check` function always invokes the provided `cb` callback. Call `cb(null)` for a healthy state and `cb(new Error('message'))` for an unhealthy state.

Install

npm install healthpoint npm
yarn add healthpoint yarn
pnpm add healthpoint pnpm

Imports

healthpoint
wrong:
```
import healthpoint from 'healthpoint'
```
correct:
```
const healthpoint = require('healthpoint')
```
This package is CommonJS-only (uses `require`). Direct `import` syntax will not work in pure ESM environments without a CommonJS wrapper or bundler.

Quickstart

Demonstrates how to set up an HTTP server, integrate `healthpoint` as a middleware for the `/health` endpoint, and implement a custom asynchronous health check function.

const http = require('http');
const healthpoint = require('healthpoint');

// Create a healthpoint handler
// It exposes 'version' and runs a custom check function
const hp = healthpoint({
  version: '1.0.0', // Replace with dynamic version from package.json
  serviceName: 'MyWebApp'
}, function (cb) {
  // In a real application, you would check database connections,
  // external APIs, or other critical services here.
  // For demonstration, we'll alternate between healthy and unhealthy every 5 seconds.
  const isOk = Math.round(Date.now() / 5000) % 2;
  if (isOk) {
    cb(null); // Healthy
  } else {
    cb(new Error('Database connection failed or external service unreachable.')); // Unhealthy
  }
});

// Create a simple HTTP server
const server = http.createServer(function (req, res) {
  if (req.url === '/health') {
    // Delegate health check requests to the healthpoint handler
    return hp(req, res);
  }
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('Visit /health for the health check endpoint');
});

server.listen(1337, () => {
  console.log('Server running at http://localhost:1337');
  console.log('Visit http://localhost:1337/health for the health check');
});

view raw JSON →