Registry /
http-networking / express-service-readiness-middleware
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
createReadinessMiddleware
✓ import { createReadinessMiddleware } from 'express-service-readiness-middleware';
✗ const { createReadinessMiddleware } = require('express-service-readiness-middleware');
ESM import is recommended for modern Node.js and TypeScript projects. While `require()` works for CommonJS, it's considered 'wrong' in ESM-first environments.
checkDependenciesHealth
✓ import { checkDependenciesHealth } from 'express-service-readiness-middleware';
✗ const { checkDependenciesHealth } = require('express-service-readiness-middleware');
Used for on-demand health checks of all configured dependencies. Returns a Promise.
criticalDependenciesReady
✓ import { criticalDependenciesReady } from 'express-service-readiness-middleware';
✗ const { criticalDependenciesReady } = require('express-service-readiness-middleware');
Provides a simple boolean check for whether all critical dependencies have achieved readiness.
setLogger
✓ import { setLogger } from 'express-service-readiness-middleware';
✗ const { setLogger } = require('express-service-readiness-middleware');
Essential for enabling internal logging, as no logger is set by default. The provided logger object must have a `log` function.
Demonstrates setting up an Express application with readiness middleware. It includes critical and non-critical dependencies, whitelisted paths, and endpoints for both liveness and readiness, highlighting the middleware's gating behavior during startup.
import express from 'express';
import { createReadinessMiddleware, setLogger, checkDependenciesHealth } from 'express-service-readiness-middleware';
const app = express();
const PORT = process.env.PORT || 3000;
// Set a logger for internal messages (optional, but recommended)
setLogger(console);
// Simulate a critical database dependency
let isDatabaseReady = false;
setTimeout(() => {
console.log('Database became ready after 5 seconds.');
isDatabaseReady = true;
}, 5000);
// Simulate a non-critical cache dependency that might fail initially
let isCacheHealthy = true;
const toggleCacheHealth = () => {
isCacheHealthy = !isCacheHealthy;
console.log(`Cache is now ${isCacheHealthy ? 'healthy' : 'unhealthy'}.`);
};
setInterval(toggleCacheHealth, 15000);
const dependencies = [
{
name: 'database',
critical: true,
isReady: () => Promise.resolve(isDatabaseReady),
isHealthy: () => Promise.resolve(isDatabaseReady) // For liveness, same as readiness here
},
{
name: 'cache',
critical: false,
isReady: () => Promise.resolve(true), // Cache doesn't block readiness
isHealthy: () => Promise.resolve(isCacheHealthy) // Its health can fluctuate
}
];
// Register the readiness middleware before other routes
// Requests to non-whitelisted paths will get 502 until 'database' is ready.
app.use(createReadinessMiddleware(dependencies, {
whitelistedPaths: ['/liveness', '/ready']
}));
// Liveness endpoint (always accessible)
app.get('/liveness', (req, res) => {
res.status(200).send('Service is live');
});
// Readiness endpoint (checks current readiness status dynamically)
app.get('/ready', async (req, res) => {
const health = await checkDependenciesHealth(dependencies);
if (health.allCriticalDependenciesHealthy) {
res.status(200).json({ status: 'ready', details: health });
} else {
res.status(503).json({ status: 'not ready', details: health });
}
});
// Application routes (will be gated by readiness middleware)
app.get('/', (req, res) => {
res.send('Hello from the ready service!');
});
// Start the server
app.listen(PORT, () => {
console.log(`Server listening on port ${PORT}`);
console.log('Try accessing / and /liveness immediately, then / after 5 seconds.');
});
Errors
Common errors & fixes
TypeError: (0 , express_service_readiness_middleware_1.createReadinessMiddleware) is not a function
This error typically occurs when attempting to `require()` an ESM-first package in a CommonJS context, or using incorrect import syntax for named exports. While the package ships types, the example in the README uses CommonJS `require()` which might conflict with an ESM-configured project (e.g., `"type": "module"` in `package.json`).
fixIf your project is configured for ESM, use `import { createReadinessMiddleware } from 'express-service-readiness-middleware';`. If strictly using CommonJS and facing this issue, ensure your `tsconfig.json` (if applicable) and build setup correctly target CommonJS modules, or explicitly set `"type": "commonjs"` in your `package.json`. TypeError: dependency.isReady is not a function
A dependency object provided to `createReadinessMiddleware` or `checkDependenciesHealth` is missing the `isReady` property, or its value is not a function that returns a Promise.
fixEnsure all objects in the `dependencies` array have an `isReady` property set to an asynchronous function that returns a `Promise<boolean>`, e.g., `isReady: () => Promise.resolve(true)`.
Service is not becoming ready (502 errors persist)
The critical dependencies' `isReady` functions are consistently returning `false` or taking longer than `maximumWaitTimeForServiceReadinessInMilliseconds` to resolve to `true`, preventing the service from transitioning to a 'ready' state.
fixInspect the `isReady` implementations for your critical dependencies. Check external services, database connections, or other resources. Consider temporarily increasing `maximumWaitTimeForServiceReadinessInMilliseconds` in the middleware configuration for debugging, and ensure your `setLogger` is configured to view readiness logs.
Audit
Dependencies
No dependency data recorded yet.