lastcall

Graceful process lifecycle management for Node.js and Bun.

Published on npm as lastcall. Source repository: sakurablush/lastcall. Documentation: sakurablush.github.io/lastcall.

lastcall is a zero-dependency, TypeScript-first library for managing graceful shutdown in production applications. It handles SIGTERM/SIGINT from Docker, Kubernetes, and PM2 — with priorities, dependencies, phases, and HTTP server draining built in.

~22 KB ESM bundle · zero production dependencies · 100% line coverage · integration tests via child processes

npm install lastcall

Try it locally (clone, install, run tests):

git clone https://github.com/sakurablush/lastcall.git && cd lastcall && npm ci && npm test

Documentation

Browse online: sakurablush.github.io/lastcall

📖 VitePress docs cover getting started, API reference, guides (Kubernetes, Docker, Bun), and examples.

Automation: CI and automation · Security: SECURITY.md · See Contributing.

Cursor users: project Agent Skills in .cursor/skills/ guide the AI through development, testing, and docs.

Community

| Document | Purpose | | ---------------------------------------- | ---------------------------------- | | CONTRIBUTING.md | Development setup and PR checklist | | CODE_OF_CONDUCT.md | Community standards | | CONTRIBUTORS.md | How contributors are recognized | | CHANGELOG.md | Release history | | SECURITY.md | Vulnerability reporting |

Why lastcall?

| Problem | lastcall solution | | ------------------------------------- | ------------------------------------- | | In-flight requests dropped on SIGTERM | withHttpServer() drains connections | | Cleanup runs in wrong order | Priorities + dependency graph | | Custom signal handlers are buggy | Test-covered, idempotent shutdown | | Hard to test shutdown | simulateSignal(), autoExit: false | | No observability | Metrics hooks + lifecycle events |

Quick start

import { createServer } from 'node:http';
import { createLastcall } from 'lastcall';

const server = createServer((req, res) => {
  res.end('ok');
});

const lastcall = createLastcall();

lastcall.withHttpServer(server); // before listen()

lastcall.register(
  'database',
  async () => {
    await db.disconnect();
  },
  { critical: true },
);

server.listen(3000);
// SIGTERM / SIGINT trigger graceful shutdown automatically.

API

createLastcall(options?)

| Option | Default | Description | | --------------------------- | ---------------------------------------- | ------------------------------------ | | signals | ['SIGTERM', 'SIGINT', 'SIGHUP'] | Signals to listen for | | shutdownTimeoutMs | 30000 | Global shutdown timeout (> 0) | | phases | ['pre', 'drain', 'cleanup', 'post'] | Shutdown phases (no duplicates) | | onHandlerStart | — | Metrics hook when handler starts | | onHandlerEnd | — | Metrics hook when handler ends | | captureUncaughtException | false | Shutdown on uncaught exceptions | | captureUnhandledRejection | false | Shutdown on unhandled rejections | | autoExit | true | Call process.exit() after shutdown | | logger | console.error with [lastcall] prefix | Custom logger |

lastcall.register(name, fn, options?)

| Option | Default | Description | | ----------- | ----------- | --------------------------------------------- | | priority | 100 | Lower runs earlier (within same phase) | | timeoutMs | — | Per-handler timeout | | critical | false | Failure affects exit code | | deps | [] | Names that must finish first (same phase) | | phase | 'cleanup' | Shutdown phase |

Shutdown phases

1. pre — Mark unhealthy, stop accepting new work
2. drain — Wait for in-flight requests/jobs
3. cleanup — Close DB, Redis, queues, files
4. post — Final logs, metrics flush

getDefaultLastcall(options?)

Returns a process-wide singleton. Options apply only on the first call.

Other methods

await lastcall.shutdown('reason', 'SIGTERM'); // Manual trigger (optional signal)
lastcall.isShuttingDown(); // True once shutdown starts (stays true after completion)
lastcall.isShutdownComplete(); // True after shutdown finishes
lastcall.getState(); // 'idle' | 'shutting_down' | 'done' | 'force_exit'
lastcall.simulateSignal('SIGTERM'); // Testing
lastcall.withHttpServer(server); // HTTP drain
lastcall.unregister('name'); // Remove handler (blocked if others depend on it)
lastcall.hasHandler('name'); // Check if a handler is registered
lastcall.listHandlers(); // Snapshot for logging / health dashboards
lastcall.on('beforeShutdown', fn); // Events

Events

• beforeShutdown — { reason, signal? }
• afterShutdown — { exitCode }
• handlerError — { name, phase, durationMs, error }
• handlerCompleted — { name, phase, durationMs, error? }

HTTP server integration

import http from 'node:http';
import { createLastcall } from 'lastcall';

const server = http.createServer(handler);
const lastcall = createLastcall();

lastcall.withHttpServer(server, {
  drainTimeoutMs: 10_000,
  priority: 10,
  phase: 'drain',
});

server.listen(3000);

Works with Node.js http/https/http2 servers. Framework examples: Express, Fastify, Hono.

Dependencies between handlers

lastcall.register(
  'database',
  async () => {
    /* ... */
  },
  { phase: 'cleanup' },
);
lastcall.register(
  'cache',
  async () => {
    /* ... */
  },
  {
    phase: 'cleanup',
    deps: ['database'],
  },
);

Handlers with deps wait for their dependencies to complete within the same phase. Circular dependencies throw at shutdown time. Cross-phase dependencies are rejected at registration time.

Examples

| Example | Description | | ------------------------------------------------ | ---------------------- | | standalone-worker | Worker without HTTP | | express | Express + health check | | fastify | Fastify server | | hono | Hono server | | node-http | Raw Node.js http | | docker-k8s | K8s/Docker guide | | nextjs-standalone | Next.js custom server | | pm2-cluster | PM2 cluster mode |

See examples/README.md for how to run them.

Testing

npm test                  # silent
npm run test:log          # verbose proof logging (LASTCALL_TEST_LOG=1)
npm run test:coverage     # 100% line coverage (98% branch threshold)

import { createLastcall } from 'lastcall';

const lastcall = createLastcall({
  autoExit: false,
  signals: [],
});

lastcall.register('cleanup', vi.fn());
await lastcall.shutdown('test');

See docs/testing/running-tests.md for the full guide.

Kubernetes / Docker

See examples/docker-k8s/ for deployment best practices.

Key settings:

• Set terminationGracePeriodSeconds > shutdownTimeoutMs
• Use preStop hook for load balancer drain
• Register health check as unhealthy in pre phase

// Readiness probe — fail fast once shutdown starts
app.get('/health', (_req, res) => {
  if (lastcall.isShuttingDown()) {
    res.status(503).send('shutting down');
    return;
  }
  res.status(200).send('ok');
});

Bun compatibility

lastcall works with Bun. Signal handling may differ on Windows — SIGHUP is not available on all platforms and is safely skipped.

Troubleshooting

Handler hangs forever

Set timeoutMs on the handler. lastcall will log a clear timeout message and continue shutdown.

Multiple SIGTERM signals

Shutdown is idempotent — subsequent signals are ignored while shutting down.

Exit code is 1

A handler marked critical: true failed or timed out. Check logs for Handler "name" failed.

Tests call process.exit

Use autoExit: false in test configuration. Use resetDefaultLastcall() when testing code that calls getDefaultLastcall().

Sustain development (optional)

lastcall is MIT-licensed and free on npm — no paywall, no paid tier, no feature lock.

Keeping it current still has a real cost: cross-platform signal testing, integration suites via child processes, docs, CI, and compatibility with Node.js and Bun releases. That work runs on a self-funded stack.

Contribute in code if that fits you: Issues or a pull request per CONTRIBUTING.md.

Financial support is optional — only if lastcall saved you time or you want to help cover the next development cycle. No tiers, no perks, no obligation:

| Coin | Address | | -------- | --------------------------------------------- | | Bitcoin | bc1qcrj9wreunffxm75fcz0a2gjkw87jshcwvmxv68 | | Ethereum | 0xB85Bf389E5fC5E12636FB6F17b68Df7fC990a3dA | | Litecoin | ltc1q0nsarncmnz8vk34dav7l0vgu9m5k48drr8z6js | | Dogecoin | D6YGoYWpFZxW8JXvEfT5iB9uNXcs8AeY7L |

License

MIT