hibernot

Hibernot

Hibernot is a lightweight TypeScript/JavaScript utility for keeping your Node.js services "warm" by automatically running a keep-alive function after a period of inactivity. It's especially useful for serverless or containerized environments where you want to avoid cold starts or resource hibernation due to inactivity.

Why Hibernot?

Many cloud providers or hosting platforms will scale down, hibernate, or cold-start your service if it hasn't received traffic for a while. Hibernot helps you prevent this by running a custom keep-alive function (like a ping or a warm-up task) after a configurable period of inactivity.

Installation

npm install hibernot

Usage

1. Import and Configure

import { Hibernot } from 'hibernot';

const hibernot = new Hibernot({
  inactivityLimit: 60000, // 1 minute in milliseconds
  keepAliveFn: async () => {
    // Your keep-alive logic here (e.g., ping a health endpoint, warm up cache, etc.)
    console.log('Keep-alive triggered!');
  },
  instanceName: 'MyService', // Optional, for logging
  maxRetryAttempts: 5        // Optional, default is 3
});

2. Integrate with Express (or any middleware-based framework)

If you're using Express, you can use the built-in middleware to automatically register activity on every request:

import express from 'express';

const app = express();

app.use(hibernot.middleware());

// ... your routes here

app.listen(3000);

3. Manual Activity Registration

If you want to manually signal activity (for example, from a non-HTTP event), just call:

hibernot.registerActivity();

4. Monitoring and Control

• Get stats:
  Retrieve current stats for monitoring or debugging:

  console.log(hibernot.getStats());
  

• Reset activity count:
  Useful for tests or monitoring resets:

  hibernot.resetActivityCount();
  

• Stop the timer:
  If you want to disable inactivity detection (e.g., during shutdown):

  hibernot.stop();
  

Configuration Options

Option	Type	Required	Description
inactivityLimit	number	Yes	Time in ms to wait before triggering keepAliveFn after inactivity.
keepAliveFn	() => Promise	Yes	Async function to call when inactivity limit is reached.
instanceName	string	No	Optional name for logging/debugging.
maxRetryAttempts	number	No	How many times to retry keepAliveFn on failure (default: 3).

How It Works

• Every time activity is registered (via HTTP request or manually), Hibernot resets its inactivity timer.
• If no activity occurs for inactivityLimit ms, Hibernot calls your keepAliveFn.
• If keepAliveFn fails, it will retry up to maxRetryAttempts times (with a 1-second delay between attempts).
• After a successful keep-alive, Hibernot registers a new activity, so the cycle continues.

Example: Full Setup

import { Hibernot } from 'hibernot';
import express from 'express';

const hibernot = new Hibernot({
  inactivityLimit: 120000, // 2 minutes
  keepAliveFn: async () => {
    // Example: ping your own health endpoint
    await fetch('https://your-service/health');
  },
  instanceName: 'API',
  maxRetryAttempts: 2
});

const app = express();
app.use(hibernot.middleware());

app.get('/', (req, res) => res.send('Hello World!'));

app.listen(3000, () => console.log('Server running on port 3000'));

FAQ

Q: Can I use this outside of Express?
A: Yes! Just call registerActivity() whenever you want to signal activity.

Q: What happens if my keepAliveFn keeps failing?
A: Hibernot will retry up to maxRetryAttempts times, then log an error and continue monitoring.

Q: Is this safe for production?
A: Yes, but make sure your keepAliveFn is idempotent and doesn't cause side effects if called repeatedly.

License

MIT

Contributing

Feel free to open issues or PRs! If you want to tweak the inactivity logic or retry strategy, check the comments in the source code—everything is documented for easy modification.