request-scope-api 1.0.21 → 1.0.23

package/dist/types/index.d.ts

@@ -28,5 +28,23 @@ export default requestscopeMiddleware;
 export declare function dashboard(config?: DashboardConfig, adapter?: StorageAdapter): express.Router;
 export { setup };
 export { errorHandler };
+/**
+ * Gracefully shuts down all RequestScope resources.
+ *
+ * This should be called by the host application during shutdown (e.g., on SIGTERM/SIGINT).
+ * It will:
+ * - Stop the retention scheduler
+ * - Drain the queue with a timeout
+ * - Destroy the queue (clear timers)
+ * - Close all database connections
+ *
+ * @param options - Optional configuration for shutdown
+ * @param options.drainTimeoutMs - Timeout for queue drain in milliseconds (default: 5000)
+ * @param options.logHandles - Whether to log active handles after shutdown (default: false)
+ */
+export declare function shutdown(options?: {
+    drainTimeoutMs?: number;
+    logHandles?: boolean;
+}): Promise<void>;
 export type { RequestScopeConfig, StorageConfig, AuthConfig, RequestRecord, StorageAdapter, QueryFilters, DashboardConfig, };
 export { requestscope as requestscopeMiddleware } from './middleware.js';

package/dist/types/shutdown-manager.d.ts

@@ -0,0 +1,49 @@
+/**
+ * ShutdownManager — Manages graceful shutdown of all RequestScope resources.
+ *
+ * This centralizes shutdown logic to prevent multiple shutdown executions,
+ * add comprehensive logging, and expose a shutdown() method that the host
+ * application can call instead of relying on global signal handlers.
+ */
+interface ShutdownResources {
+    queue?: {
+        drain: (timeoutMs: number) => Promise<void>;
+        destroy: () => void;
+    };
+    retentionScheduler?: {
+        stop: () => void;
+    };
+}
+declare class ShutdownManager {
+    private isShuttingDown;
+    private resources;
+    /**
+     * Registers resources that need to be cleaned up during shutdown.
+     */
+    registerResources(resources: ShutdownResources): void;
+    /**
+     * Performs graceful shutdown of all registered resources.
+     *
+     * Steps:
+     * 1. Prevents multiple shutdown executions
+     * 2. Stops retention scheduler
+     * 3. Drains queue with timeout
+     * 4. Destroys queue
+     * 5. Closes all database connections
+     * 6. Logs remaining active handles for debugging
+     */
+    shutdown(options?: {
+        drainTimeoutMs?: number;
+        logHandles?: boolean;
+    }): Promise<void>;
+    /**
+     * Logs active handles to help identify what's preventing process exit.
+     */
+    private logActiveHandles;
+    /**
+     * Returns whether shutdown is currently in progress.
+     */
+    isShutdownInProgress(): boolean;
+}
+export declare const shutdownManager: ShutdownManager;
+export {};

package/dist/types/types.d.ts

@@ -98,4 +98,6 @@ export interface StorageAdapter {
      * Returns the number of deleted records.
      */
     deleteOlderThan(date: Date): Promise<number>;
+    /** Closes the database connection/pool. Called during application shutdown. */
+    close(): Promise<void>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "request-scope-api",
-  "version": "1.0.21",
+  "version": "1.0.23",
   "description": "Zero-friction API request observability for Express.js applications",
   "keywords": [
     "express",