catornot

A delightful health monitoring middleware for Express that rewards you with a cat image when all your endpoints are healthy. Because monitoring should be fun!

Features

• Simple Configuration: Configure endpoints to monitor via JSON or JS files
• Express Integration: Drop-in middleware for Express applications
• Periodic Monitoring: Automatically checks endpoint health at configurable intervals
• Visual Feedback: Returns a cat image when all endpoints are healthy, error response when not
• Flexible: Support for custom headers, timeouts, and check intervals

Installation

npm install catornot

Quick Start

1. Create a configuration file catOrNot.config.json:

{
  "endpoints": [
    {
      "url": "http://localhost:3000/api/status",
      "method": "GET"
    },
    {
      "url": "http://localhost:3000/api/database",
      "method": "GET"
    }
  ],
  "checkInterval": 30000,
  "timeout": 5000,
  "healthPath": "/health"
}

2. Add to your Express application:

const express = require('express');
const catOrNot = require('catornot');

const app = express();

// Add the catornot health check
app.use(catOrNot('./catOrNot.config.json'));

app.listen(3000, () => {
  console.log('Server running on port 3000');
  console.log('Health check available at http://localhost:3000/health');
});

3. Visit http://localhost:3000/health:
   • If all endpoints are healthy: You get a cat image!
   • If any endpoint is unhealthy: You get a 503 error with details

Configuration Options

Config File Format

Option	Type	Default	Description
endpoints	Array	Required	List of endpoints to monitor
checkInterval	Number	30000	Interval between health checks (ms)
timeout	Number	5000	Request timeout for each endpoint (ms)
healthPath	String	"/health"	Path where health check endpoint is exposed
enableMonitoring	Boolean	true	Enable periodic background monitoring
catImagePath	String	"./cat.jpeg"	Path to custom cat image

Endpoint Configuration

Each endpoint in the endpoints array can have:

{
  "url": "http://example.com/health",
  "method": "GET",
  "headers": {
    "Authorization": "Bearer token"
  }
}

Usage Examples

Basic Usage with Config File

const express = require('express');
const catOrNot = require('catornot');

const app = express();
app.use(catOrNot('./catOrNot.config.json'));

Inline Configuration

const express = require('express');
const catOrNot = require('catornot');

const app = express();

app.use(catOrNot({
  endpoints: [
    { url: 'http://localhost:3001/status', method: 'GET' },
    { url: 'http://localhost:3002/health', method: 'GET' }
  ],
  checkInterval: 60000,
  timeout: 3000,
  healthPath: '/status'
}));

Manual Health Checking

const catOrNot = require('catornot');

const healthRouter = catOrNot('./catOrNot.config.json');

// Access the health checker
const checker = healthRouter.healthChecker;

// Perform manual check
async function checkHealth() {
  const isHealthy = await checker.checkAll();
  const status = checker.getStatus();
  console.log('All healthy:', isHealthy);
  console.log('Status:', status);
}

// Stop automatic monitoring
healthRouter.healthChecker.stopMonitoring();

// Start automatic monitoring
healthRouter.healthChecker.startMonitoring();

Standalone Health Checker (without Express)

const { createHealthChecker } = require('catornot');

const checker = createHealthChecker({
  endpoints: [
    { url: 'http://localhost:3000/api', method: 'GET' }
  ],
  timeout: 5000
});

// Manual check
checker.checkAll().then(healthy => {
  console.log('Healthy:', healthy);
  console.log('Status:', checker.getStatus());
});

Response Format

Healthy Response (200)

When all endpoints are healthy, you receive the cat image:

• Status Code: 200
• Content-Type: image/jpeg
• Headers:
  • X-Health-Status: healthy
  • X-Endpoints-Status: JSON with endpoint details
• Body: Cat image (JPEG)

Unhealthy Response (503)

When any endpoint is unhealthy:

{
  "message": "Service unhealthy - no cat today",
  "allHealthy": false,
  "endpoints": {
    "http://localhost:3000/api/status": {
      "healthy": false,
      "lastCheck": "2025-10-11T12:00:00.000Z",
      "error": "Request timeout",
      "statusCode": null
    },
    "http://localhost:3000/api/database": {
      "healthy": true,
      "lastCheck": "2025-10-11T12:00:00.000Z",
      "error": null,
      "statusCode": 200
    }
  }
}

Custom Cat Image

Want to use your own cat image? Specify the path in the config:

{
  "catImagePath": "./my-custom-cat.jpeg",
  "endpoints": [...]
}

API Reference

catOrNot(configPathOrObject)

Main function to create health monitoring router.

• Parameters:
  • configPathOrObject: String path to config file or configuration object
• Returns: Express Router with health endpoint

createHealthChecker(configPathOrObject)

Create standalone health checker without Express router.

• Parameters:
  • configPathOrObject: String path to config file or configuration object
• Returns: HealthChecker instance

HealthChecker Methods

• checkAll(): Check all endpoints, returns Promise
• areAllHealthy(): Returns boolean indicating if all endpoints are healthy
• getStatus(): Returns detailed status object
• startMonitoring(): Start periodic health checks
• stopMonitoring(): Stop periodic health checks

License

MIT

Contributing

Issues and pull requests welcome! Let's make health monitoring more fun together.