@bun-and-butter/shutdown

A small helper for graceful shutdown in Bun applications.

@bun-and-butter/shutdown gives you one shared shutdown manager for the process. It lets you register ordered shutdown handlers, parallel cleanup handlers, coordinate cancellation through an AbortSignal, and trigger a graceful application exit from one central place.

This is useful when your application needs to:

• stop accepting new work
• cancel long-running background tasks
• close servers, queues, or workers in a predictable order
• flush logs, metrics, or telemetry before the process exits
• enforce a maximum shutdown timeout

Example

import { setTimeout as sleep } from "node:timers/promises";
import { shutdown } from "@bun-and-butter/shutdown";

shutdown.timeoutInSec = 5;

shutdown.registerShutdownHandler(async () => {
	console.log("closing HTTP server");
	await sleep(300);
});

shutdown.registerShutdownHandler(async () => {
	console.log("stopping background jobs");
	await sleep(200);
});

shutdown.registerCleanupHandler(async () => {
	console.log("flushing metrics");
	await sleep(100);
});

const runWorker = async (signal: AbortSignal) => {
	while (!signal.aborted) {
		await sleep(250);
	}
};

void runWorker(shutdown.signal);

shutdown.exit(0);

Why Use It

In many applications, shutdown logic starts out scattered across signal handlers, server files, worker loops, and logging code. That works for a while, but it tends to become inconsistent once multiple resources need to shut down in a specific order.

This package keeps that flow explicit:

• one shared shutdown manager for the process
• shutdown handlers run in series in registration order
• cleanup handlers run afterwards in parallel
• long-running tasks can observe shutdown.signal
• graceful shutdown can be triggered from OS signals or application code

Core API

The package exposes one shared instance:

• shutdown The default process-wide shutdown manager.

And one main method for initiating shutdown:

• shutdown.exit(code?) Starts graceful shutdown and exits the process afterwards.

The shared instance also exposes:

• shutdown.signal An AbortSignal that is aborted once shutdown begins.
• shutdown.timeoutInSec The maximum number of seconds to wait for handlers.
• shutdown.logger Optional logger used for shutdown-related messages.
• shutdown.logExit Controls whether exits without an OS signal emit a debug log.

Handler Model

There are two handler types:

• registerShutdownHandler(fn) Use this for critical steps that must run in order, such as closing an HTTP server before draining workers.
• registerCleanupHandler(fn) Use this for less critical tasks that can run concurrently, such as flushing metrics or logs.

Both handler types receive:

• the exit code
• the OS signal, if shutdown was triggered by a signal

Logging

By default, the shared instance uses the built-in ConsoleLogger.

You can replace it with your own logger:

shutdown.logger = {
	debug(message, meta) {
		console.debug("[app:debug]", message, meta);
	},
	info(message, meta) {
		console.info("[app:info]", message, meta);
	},
	error(message, meta) {
		console.error("[app:error]", message, meta);
	},
};

You can also disable logging entirely:

shutdown.logger = undefined;

Or disable only the debug log for normal exits without a signal:

shutdown.logExit = false;

Examples

The repository currently includes one main example:

• examples/demo.ts Shows the shared shutdown manager, custom logging, shutdown.signal, shutdown handlers, cleanup handlers, and manual shutdown.exit(0).

Recommended Pattern

For most applications:

1. configure shutdown once during startup
2. pass shutdown.signal into long-running tasks
3. register critical teardown steps as shutdown handlers
4. register non-critical flushing work as cleanup handlers
5. call shutdown.exit(code) instead of scattering exit logic across the codebase