request-drain 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pascal Pfeifer <pascal@pfeifer.zone>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+# request-drain
+
+> Gracefully drain HTTP requests before shutting down a Node.js service.
+
+[![npm version](https://img.shields.io/npm/v/request-drain.svg)](https://www.npmjs.com/package/request-drain)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)
+[![codecov](https://codecov.io/gh/pfeiferio/request-drain/branch/main/graph/badge.svg)](https://codecov.io/gh/pfeiferio/request-drain)
+
+`request-drain` tracks active HTTP requests and allows services to wait until all requests are finished before shutting down.
+
+It is designed for graceful deployments where a process should stop accepting new requests, finish ongoing ones, and then exit cleanly.
+
+---
+
+## What problem does this solve?
+
+When deploying a new version of a service, existing HTTP requests should be allowed to finish before the process exits.
+`request-drain` tracks active requests and allows services to wait until they are completed.
+
+---
+
+## Features
+
+* ✅ Graceful request draining for Node.js services
+* ✅ Works with Express, Fastify, Koa or any Node.js HTTP framework
+* ✅ No runtime dependencies
+* ✅ Multiple middleware layers can track the same request safely
+* ✅ Predictable shutdown behavior with optional timeout
+
+---
+
+## Installation
+
+```bash
+npm install request-drain
+```
+
+---
+
+## Usage
+
+The recommended pattern is to encapsulate shutdown behavior inside each middleware. The middleware registers itself with the `ShutdownRegistry`, tracks incoming requests, and decides how long to wait for them to finish.
+
+The request object must be a Node.js `IncomingMessage`. This is compatible with Express, Fastify, Koa and native HTTP servers.
+
+```ts
+import {ShutdownRegistry} from "request-drain"
+
+const registry = new ShutdownRegistry()
+
+const createMiddleware = (registry: ShutdownRegistry) => {
+  const handle = registry.register()
+
+  handle.onAbort(async () => {
+    await handle.waitUntilIdle(5_000)
+  })
+
+  return (req, res, next) => {
+    if (handle.isShutdown) {
+      res.status(503).end("Server shutting down")
+      return
+    }
+
+    /**
+     * Registers the request with the handle.
+     * The request is automatically released when it closes.
+     */
+    handle.request(req)
+    next()
+  }
+}
+
+app.use(createMiddleware(registry))
+
+const onShutdown = async () => {
+  await registry.shutdown()
+  process.exit(0)
+}
+
+process.on("SIGTERM", onShutdown)
+process.on("SIGINT", onShutdown)
+```
+
+In this example the middleware:
+
+* tracks incoming requests
+* stops accepting new requests during shutdown
+* waits up to 5 seconds for active requests to finish
+
+`registry.shutdown()` calls `onAbort` on all registered handles and waits for them to complete.
+
+---
+
+## Multiple Middlewares
+
+Each middleware registers its own handle. The registry ensures that a request passing through multiple middlewares is tracked independently per handle without double-counting within a handle.
+
+```ts
+const registry = new ShutdownRegistry()
+
+app.use(createMiddleware(registry))
+app.use(createSessionMiddleware(registry))
+
+const onShutdown = async () => {
+  await registry.shutdown()
+  process.exit(0)
+}
+
+process.on("SIGTERM", onShutdown)
+process.on("SIGINT", onShutdown)
+```
+
+---
+
+## Optional: Global Shutdown Timeout
+
+`request-drain` does not enforce a global shutdown timeout. Each middleware decides how long it waits via `waitUntilIdle()`.
+
+If you want to enforce a maximum shutdown time for the entire process, add a safety timeout in your signal handler:
+
+```ts
+import {setTimeout as sleep} from "node:timers/promises"
+
+const onShutdown = async () => {
+  await Promise.race([
+    registry.shutdown(),
+    sleep(30_000)
+  ])
+
+  process.exit(0)
+}
+
+process.on("SIGTERM", onShutdown)
+process.on("SIGINT", onShutdown)
+```
+
+This ensures the process exits even if a component fails to shut down in time.
+
+---
+
+## Design Goals
+
+* Minimal API surface
+* Predictable shutdown behavior
+* No framework coupling
+* No global state
+* No runtime dependencies
+
+---
+
+## License
+
+MIT

package/dist/RequestTracker.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Tracks active request identifiers and emits an `idle` event
+ * when all tracked requests have been released.
+ *
+ * Used internally by {@link ShutdownHandle} to determine when
+ * all requests associated with a handle have completed.
+ */
+export declare class RequestTracker {
+    #private;
+    /**
+     * Registers a callback that is executed once the tracker becomes idle.
+     *
+     * The callback fires when the last tracked request is released.
+     */
+    onIdle(onIdle: () => void): this;
+    /**
+     * Removes a previously registered idle listener.
+     */
+    offIdle(handle: () => void): this;
+    /**
+     * Releases a previously tracked request identifier.
+     *
+     * If this call removes the last active request, the tracker
+     * emits an `idle` event.
+     */
+    release(id: symbol): this;
+    /**
+     * Marks a request identifier as active.
+     */
+    track(id: symbol): this;
+    /**
+     * Indicates whether no requests are currently tracked.
+     */
+    get isEmpty(): boolean;
+}
+//# sourceMappingURL=RequestTracker.d.ts.map

package/dist/RequestTracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RequestTracker.d.ts","sourceRoot":"","sources":["../src/RequestTracker.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,qBAAa,cAAc;;IAKzB;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,IAAI;IAKzB;;OAEG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,IAAI;IAK1B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAUzB;;OAEG;IACH,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAKvB;;OAEG;IACH,IAAI,OAAO,YAEV;CACF"}

package/dist/RequestTracker.js

@@ -0,0 +1,57 @@
+import EventEmitter from "node:events";
+/**
+ * Tracks active request identifiers and emits an `idle` event
+ * when all tracked requests have been released.
+ *
+ * Used internally by {@link ShutdownHandle} to determine when
+ * all requests associated with a handle have completed.
+ */
+export class RequestTracker {
+    #store = new Set();
+    #event = new EventEmitter();
+    /**
+     * Registers a callback that is executed once the tracker becomes idle.
+     *
+     * The callback fires when the last tracked request is released.
+     */
+    onIdle(onIdle) {
+        this.#event.once('idle', onIdle);
+        return this;
+    }
+    /**
+     * Removes a previously registered idle listener.
+     */
+    offIdle(handle) {
+        this.#event.removeListener('idle', handle);
+        return this;
+    }
+    /**
+     * Releases a previously tracked request identifier.
+     *
+     * If this call removes the last active request, the tracker
+     * emits an `idle` event.
+     */
+    release(id) {
+        if (!this.#store.has(id))
+            return this;
+        this.#store.delete(id);
+        if (this.isEmpty) {
+            this.#event.emit('idle');
+        }
+        return this;
+    }
+    /**
+     * Marks a request identifier as active.
+     */
+    track(id) {
+        this.#store.add(id);
+        return this;
+    }
+    /**
+     * Indicates whether no requests are currently tracked.
+     */
+    get isEmpty() {
+        return this.#store.size === 0;
+    }
+}
+//# sourceMappingURL=RequestTracker.js.map

package/dist/RequestTracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RequestTracker.js","sourceRoot":"","sources":["../src/RequestTracker.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,aAAa,CAAC;AAEvC;;;;;;GAMG;AACH,MAAM,OAAO,cAAc;IAEhB,MAAM,GAAgB,IAAI,GAAG,EAAE,CAAA;IAC/B,MAAM,GAAG,IAAI,YAAY,EAAE,CAAA;IAEpC;;;;OAIG;IACH,MAAM,CAAC,MAAkB;QACvB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAChC,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;OAEG;IACH,OAAO,CAAC,MAAkB;QACxB,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAC1C,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;;;OAKG;IACH,OAAO,CAAC,EAAU;QAChB,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;YAAE,OAAO,IAAI,CAAA;QACrC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;QACtB,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAC1B,CAAC;QAED,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,EAAU;QACd,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;QACnB,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;OAEG;IACH,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,CAAA;IAC/B,CAAC;CACF"}

package/dist/ShutdownHandle.d.ts

@@ -0,0 +1,48 @@
+import type { OnAbortFn, RequestConfigs } from "./types.js";
+import type { RequestTracker } from "./RequestTracker.js";
+import type { IncomingMessage } from "node:http";
+export declare const SHUTDOWN_KEY: unique symbol;
+/**
+ * Represents a middleware-scoped shutdown controller.
+ *
+ * A handle tracks requests passing through a middleware and
+ * allows the middleware to participate in a coordinated shutdown.
+ *
+ * Each middleware typically registers its own handle via
+ * {@link ShutdownRegistry.register}.
+ */
+export declare class ShutdownHandle {
+    #private;
+    constructor(requestTracker: RequestTracker, requestConfigs: RequestConfigs, onRequestOpen: (id: symbol) => void, onRequestClose: (id: symbol) => void);
+    /**
+     * Returns true if no requests are currently tracked by this handle.
+     */
+    get isIdle(): boolean;
+    /**
+     * Waits until all tracked requests have completed or the timeout expires.
+     *
+     * @param ttl Maximum time to wait in milliseconds.
+     */
+    waitUntilIdle(ttl: number): Promise<void>;
+    /**
+     * Indicates whether the shutdown process has started.
+     *
+     * Middlewares can use this flag to reject new requests.
+     */
+    get isShutdown(): boolean;
+    [SHUTDOWN_KEY](): Promise<void>;
+    /**
+     * Registers a function that will be executed when shutdown begins.
+     *
+     * Typically used to wait for active requests to finish or to
+     * release external resources.
+     */
+    onAbort(fn: OnAbortFn): void;
+    /**
+     * Registers a request with this handle.
+     *
+     * The request is automatically released when its `close` event fires.
+     */
+    request(req: IncomingMessage): void;
+}
+//# sourceMappingURL=ShutdownHandle.d.ts.map

package/dist/ShutdownHandle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShutdownHandle.d.ts","sourceRoot":"","sources":["../src/ShutdownHandle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,SAAS,EAAE,cAAc,EAAC,MAAM,YAAY,CAAC;AAC1D,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,qBAAqB,CAAC;AAExD,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,WAAW,CAAC;AAE/C,eAAO,MAAM,YAAY,eAAqB,CAAA;AAE9C;;;;;;;;GAQG;AACH,qBAAa,cAAc;;gBAUvB,cAAc,EAAE,cAAc,EAC9B,cAAc,EAAE,cAAc,EAC9B,aAAa,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,EACnC,cAAc,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI;IAQtC;;OAEG;IACH,IAAI,MAAM,YAET;IAED;;;;OAIG;IACG,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoB/C;;;;OAIG;IACH,IAAI,UAAU,YAEb;IAEK,CAAC,YAAY,CAAC;IAOpB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,EAAE,SAAS;IAIrB;;;;OAIG;IACH,OAAO,CAAC,GAAG,EAAE,eAAe;CAY7B"}

package/dist/ShutdownHandle.js

@@ -0,0 +1,92 @@
+import { createRequestConfig } from "./utils.js";
+export const SHUTDOWN_KEY = Symbol('shutdown');
+/**
+ * Represents a middleware-scoped shutdown controller.
+ *
+ * A handle tracks requests passing through a middleware and
+ * allows the middleware to participate in a coordinated shutdown.
+ *
+ * Each middleware typically registers its own handle via
+ * {@link ShutdownRegistry.register}.
+ */
+export class ShutdownHandle {
+    #abortFns = [];
+    #requestConfigs;
+    #onRequestClose;
+    #onRequestOpen;
+    #requestTracker;
+    #shutdown = false;
+    constructor(requestTracker, requestConfigs, onRequestOpen, onRequestClose) {
+        this.#requestConfigs = requestConfigs;
+        this.#requestTracker = requestTracker;
+        this.#onRequestClose = onRequestClose;
+        this.#onRequestOpen = onRequestOpen;
+    }
+    /**
+     * Returns true if no requests are currently tracked by this handle.
+     */
+    get isIdle() {
+        return this.#requestTracker.isEmpty;
+    }
+    /**
+     * Waits until all tracked requests have completed or the timeout expires.
+     *
+     * @param ttl Maximum time to wait in milliseconds.
+     */
+    async waitUntilIdle(ttl) {
+        return new Promise((resolve) => {
+            if (this.isIdle) {
+                return resolve();
+            }
+            const onIdle = () => {
+                clearTimeout(timeout);
+                resolve();
+            };
+            const timeout = setTimeout(() => {
+                resolve();
+                this.#requestTracker.offIdle(onIdle);
+            }, ttl).unref();
+            this.#requestTracker.onIdle(onIdle);
+        });
+    }
+    /**
+     * Indicates whether the shutdown process has started.
+     *
+     * Middlewares can use this flag to reject new requests.
+     */
+    get isShutdown() {
+        return this.#shutdown;
+    }
+    async [SHUTDOWN_KEY]() {
+        this.#shutdown = true;
+        for (const fn of this.#abortFns) {
+            await fn();
+        }
+    }
+    /**
+     * Registers a function that will be executed when shutdown begins.
+     *
+     * Typically used to wait for active requests to finish or to
+     * release external resources.
+     */
+    onAbort(fn) {
+        this.#abortFns.push(fn);
+    }
+    /**
+     * Registers a request with this handle.
+     *
+     * The request is automatically released when its `close` event fires.
+     */
+    request(req) {
+        const requestConfig = this.#requestConfigs.get(req) ?? createRequestConfig();
+        const id = requestConfig.id;
+        this.#requestTracker.track(id);
+        this.#onRequestOpen(id);
+        if (requestConfig.isNew) {
+            this.#requestConfigs.set(req, requestConfig);
+            requestConfig.isNew = false;
+            req.on('close', () => this.#onRequestClose(id));
+        }
+    }
+}
+//# sourceMappingURL=ShutdownHandle.js.map

package/dist/ShutdownHandle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShutdownHandle.js","sourceRoot":"","sources":["../src/ShutdownHandle.ts"],"names":[],"mappings":"AAEA,OAAO,EAAC,mBAAmB,EAAC,MAAM,YAAY,CAAC;AAG/C,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC,UAAU,CAAC,CAAA;AAE9C;;;;;;;;GAQG;AACH,MAAM,OAAO,cAAc;IAEhB,SAAS,GAAgB,EAAE,CAAA;IAC3B,eAAe,CAAgB;IAC/B,eAAe,CAAsB;IACrC,cAAc,CAAsB;IACpC,eAAe,CAAgB;IACxC,SAAS,GAAY,KAAK,CAAA;IAE1B,YACE,cAA8B,EAC9B,cAA8B,EAC9B,aAAmC,EACnC,cAAoC;QAEpC,IAAI,CAAC,eAAe,GAAG,cAAc,CAAA;QACrC,IAAI,CAAC,eAAe,GAAG,cAAc,CAAA;QACrC,IAAI,CAAC,eAAe,GAAG,cAAc,CAAA;QACrC,IAAI,CAAC,cAAc,GAAG,aAAa,CAAA;IACrC,CAAC;IAED;;OAEG;IACH,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,eAAe,CAAC,OAAO,CAAA;IACrC,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,aAAa,CAAC,GAAW;QAC7B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;YAC7B,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;gBAChB,OAAO,OAAO,EAAE,CAAA;YAClB,CAAC;YAED,MAAM,MAAM,GAAG,GAAG,EAAE;gBAClB,YAAY,CAAC,OAAO,CAAC,CAAA;gBACrB,OAAO,EAAE,CAAA;YACX,CAAC,CAAA;YAED,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE;gBAC9B,OAAO,EAAE,CAAA;gBACT,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;YACtC,CAAC,EAAE,GAAG,CAAC,CAAC,KAAK,EAAE,CAAA;YAEf,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QACrC,CAAC,CAAC,CAAA;IACJ,CAAC;IAED;;;;OAIG;IACH,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,SAAS,CAAA;IACvB,CAAC;IAED,KAAK,CAAC,CAAC,YAAY,CAAC;QAClB,IAAI,CAAC,SAAS,GAAG,IAAI,CAAA;QACrB,KAAK,MAAM,EAAE,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YAChC,MAAM,EAAE,EAAE,CAAA;QACZ,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,OAAO,CAAC,EAAa;QACnB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IACzB,CAAC;IAED;;;;OAIG;IACH,OAAO,CAAC,GAAoB;QAC1B,MAAM,aAAa,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,mBAAmB,EAAE,CAAA;QAC5E,MAAM,EAAE,GAAG,aAAa,CAAC,EAAE,CAAA;QAC3B,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;QAC9B,IAAI,CAAC,cAAc,CAAC,EAAE,CAAC,CAAA;QAEvB,IAAI,aAAa,CAAC,KAAK,EAAE,CAAC;YACxB,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,GAAG,EAAE,aAAa,CAAC,CAAA;YAC5C,aAAa,CAAC,KAAK,GAAG,KAAK,CAAA;YAC3B,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,eAAe,CAAC,EAAE,CAAC,CAAC,CAAA;QACjD,CAAC;IACH,CAAC;CACF"}

package/dist/ShutdownRegistry.d.ts

@@ -0,0 +1,26 @@
+import { ShutdownHandle } from "./ShutdownHandle.js";
+/**
+ * Coordinates shutdown across multiple middleware handles.
+ *
+ * The registry ensures that requests passing through multiple
+ * middlewares are tracked correctly and released across all
+ * associated trackers when the request closes.
+ */
+export declare class ShutdownRegistry {
+    #private;
+    /**
+     * Initiates shutdown by invoking all registered abort handlers.
+     *
+     * Each handle receives the shutdown signal and executes its
+     * registered `onAbort` callbacks.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Registers a new shutdown handle.
+     *
+     * Each middleware should create its own handle to track
+     * requests and define shutdown behavior.
+     */
+    register(): ShutdownHandle;
+}
+//# sourceMappingURL=ShutdownRegistry.d.ts.map

package/dist/ShutdownRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShutdownRegistry.d.ts","sourceRoot":"","sources":["../src/ShutdownRegistry.ts"],"names":[],"mappings":"AACA,OAAO,EAAe,cAAc,EAAC,MAAM,qBAAqB,CAAC;AAGjE;;;;;;GAMG;AACH,qBAAa,gBAAgB;;IAQ3B;;;;;OAKG;IACG,QAAQ;IAQd;;;;;OAKG;IACH,QAAQ,IAAI,cAAc;CAyB3B"}

package/dist/ShutdownRegistry.js

@@ -0,0 +1,54 @@
+import { SHUTDOWN_KEY, ShutdownHandle } from "./ShutdownHandle.js";
+import { RequestTracker } from "./RequestTracker.js";
+/**
+ * Coordinates shutdown across multiple middleware handles.
+ *
+ * The registry ensures that requests passing through multiple
+ * middlewares are tracked correctly and released across all
+ * associated trackers when the request closes.
+ */
+export class ShutdownRegistry {
+    #requestConfigs = new WeakMap();
+    #handles = [];
+    #idRequestTrackerMap = new Map();
+    /**
+     * Initiates shutdown by invoking all registered abort handlers.
+     *
+     * Each handle receives the shutdown signal and executes its
+     * registered `onAbort` callbacks.
+     */
+    async shutdown() {
+        const promises = [];
+        for (const handle of this.#handles) {
+            promises.push(handle[SHUTDOWN_KEY]());
+        }
+        await Promise.allSettled(promises);
+    }
+    /**
+     * Registers a new shutdown handle.
+     *
+     * Each middleware should create its own handle to track
+     * requests and define shutdown behavior.
+     */
+    register() {
+        const requestTracker = new RequestTracker();
+        const handle = new ShutdownHandle(requestTracker, this.#requestConfigs, (id) => {
+            const set = this.#idRequestTrackerMap.get(id);
+            if (set) {
+                set.add(requestTracker);
+            }
+            else {
+                this.#idRequestTrackerMap.set(id, new Set([requestTracker]));
+            }
+        }, (id) => {
+            const trackers = this.#idRequestTrackerMap.get(id);
+            if (!trackers)
+                return;
+            trackers.forEach(requestTracker => requestTracker.release(id));
+            this.#idRequestTrackerMap.delete(id);
+        });
+        this.#handles.push(handle);
+        return handle;
+    }
+}
+//# sourceMappingURL=ShutdownRegistry.js.map

package/dist/ShutdownRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShutdownRegistry.js","sourceRoot":"","sources":["../src/ShutdownRegistry.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,YAAY,EAAE,cAAc,EAAC,MAAM,qBAAqB,CAAC;AACjE,OAAO,EAAC,cAAc,EAAC,MAAM,qBAAqB,CAAC;AAEnD;;;;;;GAMG;AACH,MAAM,OAAO,gBAAgB;IAE3B,eAAe,GAAmB,IAAI,OAAO,EAAE,CAAA;IAE/C,QAAQ,GAAqB,EAAE,CAAA;IAE/B,oBAAoB,GAAqC,IAAI,GAAG,EAAE,CAAA;IAElE;;;;;OAKG;IACH,KAAK,CAAC,QAAQ;QACZ,MAAM,QAAQ,GAAG,EAAE,CAAA;QACnB,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,CAAC,CAAA;QACvC,CAAC;QACD,MAAM,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAA;IACpC,CAAC;IAED;;;;;OAKG;IACH,QAAQ;QACN,MAAM,cAAc,GAAG,IAAI,cAAc,EAAE,CAAA;QAE3C,MAAM,MAAM,GAAG,IAAI,cAAc,CAC/B,cAAc,EACd,IAAI,CAAC,eAAe,EACpB,CAAC,EAAE,EAAE,EAAE;YACL,MAAM,GAAG,GAAG,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;YAC7C,IAAI,GAAG,EAAE,CAAC;gBACR,GAAG,CAAC,GAAG,CAAC,cAAc,CAAC,CAAA;YACzB,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,GAAG,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,CAAA;YAC9D,CAAC;QACH,CAAC,EACD,CAAC,EAAE,EAAE,EAAE;YACL,MAAM,QAAQ,GAAG,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;YAClD,IAAI,CAAC,QAAQ;gBAAE,OAAM;YACrB,QAAQ,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,CAAC,cAAc,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAA;YAC9D,IAAI,CAAC,oBAAoB,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;QACtC,CAAC,CACF,CAAA;QAED,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAC1B,OAAO,MAAM,CAAA;IACf,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export type { OnAbortFn } from "./types.js";
+export { ShutdownRegistry } from "./ShutdownRegistry.js";
+export type { ShutdownHandle } from "./ShutdownHandle.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAC,SAAS,EAAC,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAC,gBAAgB,EAAC,MAAM,uBAAuB,CAAC;AACvD,YAAY,EAAC,cAAc,EAAC,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { ShutdownRegistry } from "./ShutdownRegistry.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,gBAAgB,EAAC,MAAM,uBAAuB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,12 @@
+import type { IncomingMessage } from "node:http";
+export type RequestConfigs = WeakMap<IncomingMessage, RequestConfig>;
+export type RequestConfig = {
+    isNew: boolean;
+    id: symbol;
+};
+/**
+ * Function executed when shutdown begins.
+ * May perform asynchronous cleanup.
+ */
+export type OnAbortFn = () => void | Promise<void>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,WAAW,CAAC;AAE/C,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,eAAe,EAAE,aAAa,CAAC,CAAA;AAEpE,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,OAAO,CAAA;IACd,EAAE,EAAE,MAAM,CAAA;CACX,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/utils.d.ts

@@ -0,0 +1,7 @@
+import type { RequestConfig } from "./types.js";
+/**
+ * Creates a new request configuration used to track a request
+ * across multiple middleware handles.
+ */
+export declare const createRequestConfig: () => RequestConfig;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,YAAY,CAAC;AAE9C;;;GAGG;AACH,eAAO,MAAM,mBAAmB,QAAO,aAKtC,CAAA"}

package/dist/utils.js

@@ -0,0 +1,11 @@
+/**
+ * Creates a new request configuration used to track a request
+ * across multiple middleware handles.
+ */
+export const createRequestConfig = () => {
+    return {
+        isNew: true,
+        id: Symbol()
+    };
+};
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAkB,EAAE;IACrD,OAAO;QACL,KAAK,EAAE,IAAI;QACX,EAAE,EAAE,MAAM,EAAE;KACb,CAAA;AACH,CAAC,CAAA"}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "request-drain",
+  "version": "1.0.0",
+  "description": "Gracefully drain HTTP requests before shutting down a Node.js service.",
+  "license": "MIT",
+  "author": "Pascal Pfeifer <pascal@pfeifer.zone>",
+  "sideEffects": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "graceful-shutdown",
+    "request-drain",
+    "http",
+    "middleware",
+    "nodejs",
+    "express",
+    "fastify",
+    "koa"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pfeiferio/request-drain.git"
+  },
+  "bugs": {
+    "url": "https://github.com/pfeiferio/request-drain/issues"
+  },
+  "homepage": "https://github.com/pfeiferio/request-drain#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepublishOnly": "npm test",
+    "build": "npm run clean && tsc",
+    "clean": "rm -rf dist",
+    "test": "npm run build && node --test",
+    "test:coverage": "npm run build && node --test --experimental-test-coverage --test-coverage-exclude='test/**'",
+    "test:coverage:c8": "npm run build && npx c8 node --test",
+    "test:coverage:lcov": "npm run build && npx c8 --src src node --enable-source-maps --test"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.9",
+    "typescript": "^5.9.3"
+  }
+}