Registry / http-networking / lil-http-terminator

lil-http-terminator

JSON →
library1.2.3jsnpmunverified

lil-http-terminator is a minimalistic, zero-dependency Node.js library designed for gracefully shutting down HTTP and HTTPS servers. Currently at stable version 1.2.3, it offers a consistent, promise-based API for managing server connections during shutdown. Its core differentiator lies in its low footprint (11 KB), absence of external dependencies, and a design that prioritizes robustness: it never throws exceptions during termination, instead resolving with a `{success, code, message, error}` object. Unlike some alternatives, it guarantees termination by timing out if connections linger, and it avoids monkey-patching Node.js core APIs. The library is actively maintained, with recent updates ensuring compatibility with newer Node.js features like `server.closeIdleConnections()`.

http-networkingdevops
npm install lil-http-terminator
github ↗package ↗
INSTALL
IMPORT
SIG · LIL-HTTP-TERMINATO
L
lil-http-terminator
http-networkingjavascriptv1.2.3
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
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
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

createHttpTerminator
✓ const createHttpTerminator = require('lil-http-terminator');
✗ import { createHttpTerminator } from 'lil-http-terminator';
The module exports a factory function directly, not a named export. This is the correct CommonJS pattern.
createHttpTerminator
✓ import createHttpTerminator from 'lil-http-terminator';
✗ const createHttpTerminator = require('lil-http-terminator').default;
For ESM projects, this default import syntax will generally work via Node.js's CJS-ESM interop. Avoid accessing `.default` explicitly for CommonJS modules in ESM.
terminator.terminate
✓ await terminator.terminate();
✗ terminator.terminate(); // Missing await
The `terminate()` method returns a Promise; ensure you await its resolution to handle the shutdown result properly and prevent unintended process exits.

This quickstart demonstrates how to set up a basic HTTP server and integrate `lil-http-terminator` for graceful shutdown upon receiving SIGTERM or SIGINT signals, logging the termination result.

const http = require('http'); const createHttpTerminator = require('lil-http-terminator'); const server = http.createServer((req, res) => { console.log(`Request received: ${req.method} ${req.url}`); setTimeout(() => { res.writeHead(200, { 'Content-Type': 'text/plain' }); res.end('Hello from lil-http-terminator!\n'); }, 500); }); const httpTerminator = createHttpTerminator({ server: server, gracefulTerminationTimeout: 1000, maxWaitTimeout: 5000, logger: console, }); server.listen(3000, () => { console.log('Server listening on http://localhost:3000'); console.log('Send SIGTERM or SIGINT to gracefully shut down.'); }); async function shutdown(signal) { console.log(`\nReceived ${signal}. Initiating graceful shutdown...`); const { success, code, message, error } = await httpTerminator.terminate(); if (success) { console.log(`HTTP server closure successful.`); } else { console.error(`HTTP server closure failed: ${code} - ${message}`, error || ''); } process.exit(success ? 0 : 1); } process.on('SIGTERM', shutdown); // Used by K8s, AWS ECS, etc. process.on('SIGINT', shutdown); // Atom, VSCode, WebStorm or Terminal Ctrl+C
Debug
Known issues
breakingStarting with version 1.2.3, `lil-http-terminator` requires Node.js version 12 or higher. Earlier Node.js versions are no longer supported due to the adoption of `server.closeIdleConnections()`.
fix
Upgrade your Node.js runtime to version 12 or newer. For projects requiring older Node.js versions, use `lil-http-terminator@1.2.2`.
affects: >=1.2.3
breakingVersion 1.1.0 changed the API for `terminate()` to never throw exceptions. Instead, it now returns a Promise that resolves to an object `{ success: Boolean, code: String, message: String, error?: Error }` indicating the termination result.
fix
Update your error handling logic. Instead of using `try/catch` blocks around `await terminator.terminate()`, inspect the `success` and `code` properties of the resolved object. Example: `const { success, code, message } = await terminator.terminate(); if (!success) console.error(message);`
affects: >=1.1.0
gotchaNode.js's native `server.close()` method only stops new connections but keeps existing 'keep-alive' connections open indefinitely, potentially hanging your process. `lil-http-terminator` addresses this by actively tracking and terminating all connections after a configurable timeout.
fix
Always use `await httpTerminator.terminate()` instead of `server.close()` when you need to shut down your server gracefully to ensure all connections are properly closed or destroyed.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: lil_http_terminator_1.default is not a function
Attempting to import a CommonJS module that exports a function directly using an incorrect ESM named import syntax.
fix
If using ESM, change `import { createHttpTerminator } from 'lil-http-terminator';` to `import createHttpTerminator from 'lil-http-terminator';`
TypeError: HttpTerminator is not a constructor
Trying to instantiate the factory function using the `new` keyword, which is not supported.
fix
Call the `createHttpTerminator` function directly without `new`: `const terminator = createHttpTerminator({ server });`
Error: Cannot find module 'lil-http-terminator'
The package is not installed or the import path is incorrect.
fix
Run `npm install lil-http-terminator` or `yarn add lil-http-terminator` to install the package. Verify the import statement is `require('lil-http-terminator')` or `import createHttpTerminator from 'lil-http-terminator'`.
Upgrade
Version history
1.2.3latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
2 hits · last 30 days
node
2
Resources
githubhttps://github.com/flash-oss/lil-http-terminator ↗
packagehttps://www.npmjs.com/package/lil-http-terminator ↗
lil-http-terminator — npm install lil-http-terminator · libregistry