request-scope-api 1.0.22 → 1.0.24

package/README.md

@@ -21,6 +21,7 @@ import { setup } from 'request-scope-api';
 const app = express();
 
 setup(app, {
+  mode: 'development', // or 'production' to disable tracking
   storage: {
     type: 'mongodb',
     uri: 'mongodb://localhost:27017/myapp'
@@ -39,6 +40,7 @@ import { setup } from 'request-scope-api';
 const app = express();
 
 setup(app, {
+  mode: 'development', // or 'production' to disable tracking
   storage: {
     type: 'mysql',
     host: 'localhost',
@@ -64,6 +66,7 @@ import { setup } from 'request-scope-api';
 const app = express();
 
 setup(app, {
+  mode: 'development', // or 'production' to disable tracking
   storage: {
     type: 'postgresql',
     host: 'localhost',
@@ -88,6 +91,40 @@ app.listen(3000);
 - **Performance Metrics**: Records response time and body sizes
 - **Dashboard UI**: Web interface for browsing and filtering requests
 - **Basic Auth**: Optional authentication for dashboard access
+- **Production Mode**: Completely disables tracking in production for security and performance
+
+## Mode Configuration
+
+The package supports two modes: `development` and `production`.
+
+### Development Mode (Default)
+- Enables all request tracking, logging, and data collection
+- Runs retention scheduler and background processing
+- Dashboard is accessible
+- Ideal for local development and testing
+
+### Production Mode
+- Completely disables request tracking and data collection
+- No database connections are established
+- No background services or retention jobs run
+- Dashboard is disabled
+- Acts as a no-op middleware for security and performance
+
+```javascript
+// Development mode (default)
+setup(app, {
+  mode: 'development',
+  storage: { /* ... */ }
+});
+
+// Production mode - tracking disabled
+setup(app, {
+  mode: 'production',
+  storage: { /* ... */ }
+});
+```
+
+**Note:** In production mode, the package does not establish any database connections and has zero performance impact on your application.
 
 ## Sensitive Field Masking
 

package/dist/cjs/config.js

@@ -44,6 +44,9 @@ const DEFAULT_SENSITIVE_FIELDS = [
  *   storage.ssl    → false
  */
 function applyDefaults(config) {
+    if (config.mode === undefined) {
+        config.mode = 'development';
+    }
     if (config.retentionDays === undefined) {
         config.retentionDays = 30;
     }
@@ -75,25 +78,29 @@ function applyDefaults(config) {
  *   4. `retentionDays` (when provided) must be a positive integer in [1, 365].
  */
 function validateConfig(config) {
-    const { storage, retentionDays } = config;
-    // 1. Validate storage.type
+    const { storage, retentionDays, mode } = config;
+    // 1. Validate mode
+    if (mode !== undefined && mode !== 'development' && mode !== 'production') {
+        throw new Error(`Invalid mode: '${mode}'. Supported values are: development, production`);
+    }
+    // 2. Validate storage.type
     if (!SUPPORTED_STORAGE_TYPES.includes(storage.type)) {
         throw new Error(`Invalid storage type: '${storage.type}'. Supported values are: mongodb, mysql, postgresql`);
     }
-    // 2. MongoDB: uri is required
+    // 3. MongoDB: uri is required
     if (storage.type === 'mongodb') {
         if (!storage.uri) {
             throw new Error("storage.uri is required when storage.type is 'mongodb'");
         }
     }
-    // 3. MySQL / PostgreSQL: all SQL required fields must be present
+    // 4. MySQL / PostgreSQL: all SQL required fields must be present
     if (storage.type === 'mysql' || storage.type === 'postgresql') {
         const missing = SQL_REQUIRED_FIELDS.filter((field) => storage[field] === undefined || storage[field] === null);
         if (missing.length > 0) {
             throw new Error(`Missing required storage fields: ${missing.join(', ')}`);
         }
     }
-    // 4. retentionDays: must be a positive integer in [1, 365] when provided
+    // 5. retentionDays: must be a positive integer in [1, 365] when provided
     if (retentionDays !== undefined) {
         const isValidInteger = typeof retentionDays === 'number' &&
             Number.isInteger(retentionDays) &&

package/dist/cjs/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;AA0CH,sCAsBC;AAgBD,wCA0CC;AAaD,wDAMC;AAzID,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,MAAM,uBAAuB,GAAG,CAAC,SAAS,EAAE,OAAO,EAAE,YAAY,CAAU,CAAC;AAC5E,MAAM,mBAAmB,GAAuC;IAC9D,MAAM;IACN,UAAU;IACV,UAAU;IACV,UAAU;CACX,CAAC;AAEF,wEAAwE;AACxE,MAAM,wBAAwB,GAA0B;IACtD,UAAU;IACV,OAAO;IACP,eAAe;IACf,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,KAAK;CACN,CAAC;AAEF,8EAA8E;AAC9E,gBAAgB;AAChB,8EAA8E;AAE9E;;;;;;;;;;GAUG;AACH,SAAgB,aAAa,CAAC,MAA0B;IACtD,IAAI,MAAM,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;QACvC,MAAM,CAAC,aAAa,GAAG,EAAE,CAAC;IAC5B,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAChC,MAAM,CAAC,MAAM,GAAG,CAAC,cAAc,EAAE,mBAAmB,EAAE,sBAAsB,CAAC,CAAC;IAChF,CAAC;IAED,IAAI,MAAM,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QACpC,MAAM,CAAC,UAAU,GAAG,EAAE,CAAC;IACzB,CAAC;IAED,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC1C,MAAM,CAAC,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IAC9B,CAAC;IAED,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;QACrC,MAAM,CAAC,OAAO,CAAC,GAAG,GAAG,KAAK,CAAC;IAC7B,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E;;;;;;;;;GASG;AACH,SAAgB,cAAc,CAAC,MAA0B;IACvD,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,GAAG,MAAM,CAAC;IAE1C,2BAA2B;IAC3B,IAAI,CAAC,uBAAuB,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAgD,CAAC,EAAE,CAAC;QAChG,MAAM,IAAI,KAAK,CACb,0BAA0B,OAAO,CAAC,IAAI,qDAAqD,CAC5F,CAAC;IACJ,CAAC;IAED,8BAA8B;IAC9B,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC/B,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;QAC5E,CAAC;IACH,CAAC;IAED,iEAAiE;IACjE,IAAI,OAAO,CAAC,IAAI,KAAK,OAAO,IAAI,OAAO,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;QAC9D,MAAM,OAAO,GAAG,mBAAmB,CAAC,MAAM,CACxC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,SAAS,IAAI,OAAO,CAAC,KAAK,CAAC,KAAK,IAAI,CACnE,CAAC;QAEF,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,oCAAoC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC5E,CAAC;IACH,CAAC;IAED,yEAAyE;IACzE,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;QAChC,MAAM,cAAc,GAClB,OAAO,aAAa,KAAK,QAAQ;YACjC,MAAM,CAAC,SAAS,CAAC,aAAa,CAAC;YAC/B,aAAa,IAAI,CAAC;YAClB,aAAa,IAAI,GAAG,CAAC;QAEvB,IAAI,CAAC,cAAc,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CACb,yEAAyE,aAAa,EAAE,CACzF,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,yBAAyB;AACzB,8EAA8E;AAE9E;;;;;;GAMG;AACH,SAAgB,sBAAsB,CAAC,MAA0B;IAC/D,MAAM,KAAK,GAAa;QACtB,GAAG,wBAAwB;QAC3B,GAAG,CAAC,MAAM,CAAC,UAAU,IAAI,EAAE,CAAC;KAC7B,CAAC;IACF,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;AACpD,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"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"}

package/dist/cjs/index.js

@@ -15,11 +15,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.requestscopeMiddleware = exports.errorHandler = exports.setup = void 0;
 exports.dashboard = dashboard;
+exports.shutdown = shutdown;
 const express_1 = __importDefault(require("express"));
 const middleware_js_1 = require("./middleware.js");
 Object.defineProperty(exports, "errorHandler", { enumerable: true, get: function () { return middleware_js_1.errorHandler; } });
 Object.defineProperty(exports, "setup", { enumerable: true, get: function () { return middleware_js_1.setup; } });
 const router_js_1 = require("./dashboard/router.js");
+const shutdown_manager_js_1 = require("./shutdown-manager.js");
 // ---------------------------------------------------------------------------
 // Main middleware factory
 // ---------------------------------------------------------------------------
@@ -40,14 +42,13 @@ exports.default = middleware_js_1.requestscope;
  * @param adapter - Optional storage adapter instance
  * @returns Express Router
  */
-function dashboard(config, adapter) {
-    // Check if running in production environment
-    const nodeEnv = process.env.NODE_ENV;
-    if (nodeEnv === 'production') {
-        process.stderr.write('[RequestScope] Dashboard disabled in production environment (NODE_ENV=production)\n');
+function dashboard(config, adapter, mode = 'development') {
+    // Check mode - if production, return disabled router
+    if (mode === 'production') {
+        process.stderr.write('[RequestScope] Dashboard disabled in production mode\n');
         const router = express_1.default.Router();
         router.use((req, res, next) => {
-            res.status(404).send('RequestScope dashboard is disabled in production environment');
+            res.status(404).send('RequestScope dashboard is disabled in production mode');
         });
         return router;
     }
@@ -56,6 +57,26 @@ function dashboard(config, adapter) {
 // Attach dashboard as a named property on the default export for convenience
 middleware_js_1.requestscope.dashboard = dashboard;
 // ---------------------------------------------------------------------------
+// Shutdown function
+// ---------------------------------------------------------------------------
+/**
+ * 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)
+ */
+async function shutdown(options) {
+    await shutdown_manager_js_1.shutdownManager.shutdown(options);
+}
+// ---------------------------------------------------------------------------
 // Named exports for convenience
 // ---------------------------------------------------------------------------
 var middleware_js_2 = require("./middleware.js");

package/dist/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;;;;AAuCH,8BAaC;AAjDD,sDAA8B;AAC9B,mDAA8F;AA+DrF,6FA/DwC,4BAAY,OA+DxC;AANZ,sFAzDsD,qBAAK,OAyDtD;AAxDd,qDAA8D;AAW9D,8EAA8E;AAC9E,0BAA0B;AAC1B,8EAA8E;AAE9E;;;;;GAKG;AACH,kBAAe,4BAAsB,CAAC;AAEtC,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E;;;;;;GAMG;AACH,SAAgB,SAAS,CAAC,MAAwB,EAAE,OAAwB;IAC1E,6CAA6C;IAC7C,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC;IACrC,IAAI,OAAO,KAAK,YAAY,EAAE,CAAC;QAC7B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,qFAAqF,CAAC,CAAC;QAC5G,MAAM,MAAM,GAAG,iBAAO,CAAC,MAAM,EAAE,CAAC;QAChC,MAAM,CAAC,GAAG,CAAC,CAAC,GAAQ,EAAE,GAAQ,EAAE,IAAS,EAAE,EAAE;YAC3C,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,8DAA8D,CAAC,CAAC;QACvF,CAAC,CAAC,CAAC;QACH,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,OAAO,IAAA,iCAAqB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAChD,CAAC;AAED,6EAA6E;AAC5E,4BAA8B,CAAC,SAAS,GAAG,SAAS,CAAC;AA4BtD,8EAA8E;AAC9E,gCAAgC;AAChC,8EAA8E;AAE9E,iDAAyE;AAAhE,uHAAA,YAAY,OAA0B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;;;;AAwCH,8BAYC;AAmCD,4BAEC;AAtFD,sDAA8B;AAC9B,mDAA8F;AA+DrF,6FA/DwC,4BAAY,OA+DxC;AANZ,sFAzDsD,qBAAK,OAyDtD;AAxDd,qDAA8D;AAC9D,+DAAwD;AAWxD,8EAA8E;AAC9E,0BAA0B;AAC1B,8EAA8E;AAE9E;;;;;GAKG;AACH,kBAAe,4BAAsB,CAAC;AAEtC,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E;;;;;;GAMG;AACH,SAAgB,SAAS,CAAC,MAAwB,EAAE,OAAwB,EAAE,OAAqC,aAAa;IAC9H,qDAAqD;IACrD,IAAI,IAAI,KAAK,YAAY,EAAE,CAAC;QAC1B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,wDAAwD,CAAC,CAAC;QAC/E,MAAM,MAAM,GAAG,iBAAO,CAAC,MAAM,EAAE,CAAC;QAChC,MAAM,CAAC,GAAG,CAAC,CAAC,GAAQ,EAAE,GAAQ,EAAE,IAAS,EAAE,EAAE;YAC3C,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,uDAAuD,CAAC,CAAC;QAChF,CAAC,CAAC,CAAC;QACH,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,OAAO,IAAA,iCAAqB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAChD,CAAC;AAED,6EAA6E;AAC5E,4BAA8B,CAAC,SAAS,GAAG,SAAS,CAAC;AActD,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E;;;;;;;;;;;;;GAaG;AACI,KAAK,UAAU,QAAQ,CAAC,OAA2D;IACxF,MAAM,qCAAe,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;AAC1C,CAAC;AAgBD,8EAA8E;AAC9E,gCAAgC;AAChC,8EAA8E;AAE9E,iDAAyE;AAAhE,uHAAA,YAAY,OAA0B"}

package/dist/cjs/middleware.js

@@ -21,6 +21,7 @@ const retention_js_1 = require("./retention.js");
 const capture_js_1 = require("./capture.js");
 const router_js_1 = require("./dashboard/router.js");
 const adapter_singleton_js_1 = require("./adapter-singleton.js");
+const shutdown_manager_js_1 = require("./shutdown-manager.js");
 const ALWAYS_IGNORED_PATHS = ['/favicon.ico', '/requestscope/api', '/requestscope/assets'];
 // ---------------------------------------------------------------------------
 // Factory function
@@ -49,21 +50,22 @@ const ALWAYS_IGNORED_PATHS = ['/favicon.ico', '/requestscope/api', '/requestscop
  * @returns Express RequestHandler middleware
  */
 function requestscope(config, adapter) {
-    // Check if running in production environment
-    const nodeEnv = process.env.NODE_ENV;
-    if (nodeEnv === 'production') {
-        process.stderr.write('[RequestScope] Package disabled in production environment (NODE_ENV=production)\n');
-        return (req, res, next) => next();
-    }
     // 1. Validate and apply defaults synchronously
     (0, config_js_1.validateConfig)(config);
     (0, config_js_1.applyDefaults)(config);
+    // 2. Check mode - if production, act as no-op
+    if (config.mode === 'production') {
+        process.stderr.write('[RequestScope] Running in production mode - request tracking disabled\n');
+        return (req, res, next) => next();
+    }
+    // 3. Log development mode
+    process.stderr.write('[RequestScope] Running in development mode - request tracking enabled\n');
     const sensitiveFields = (0, config_js_1.buildSensitiveFieldSet)(config);
-    // 2. Get or create singleton adapter instance
+    // 4. Get or create singleton adapter instance
     if (!adapter) {
         adapter = adapter_singleton_js_1.adapterSingleton.getOrCreate(config.storage);
     }
-    // 3. Initialize adapter asynchronously (log errors, don't throw)
+    // 5. Initialize adapter asynchronously (log errors, don't throw)
     // Only initialize if not already initialized
     void adapter.initialize().then(() => {
         adapter_singleton_js_1.adapterSingleton.markInitialized(adapter, config.storage);
@@ -71,31 +73,22 @@ function requestscope(config, adapter) {
         const message = err instanceof Error ? err.message : String(err);
         process.stderr.write(`[RequestScope] Failed to initialize storage adapter: ${message}\n`);
     });
-    // 4. Create and start AsyncQueue and RetentionScheduler
+    // 6. Create and start AsyncQueue and RetentionScheduler
     const queue = new queue_js_1.AsyncQueue(adapter);
     const retentionDays = config.retentionDays ?? 30;
     const retentionScheduler = new retention_js_1.RetentionScheduler(adapter, retentionDays);
     retentionScheduler.start();
-    // 5. Attach graceful shutdown handlers (only once per process)
-    const shutdown = async () => {
-        retentionScheduler.stop();
-        await queue.drain(10000);
-        queue.destroy();
-        // Close all database connections via singleton
-        await adapter_singleton_js_1.adapterSingleton.closeAll();
-    };
-    // Use a flag to ensure shutdown handlers are only attached once
-    const shutdownKey = '__requestscope_shutdown_attached__';
-    if (!process[shutdownKey]) {
-        process[shutdownKey] = true;
-        process.on('SIGTERM', () => {
-            void shutdown();
-        });
-        process.on('SIGINT', () => {
-            void shutdown();
-        });
-    }
-    // 6. Return the request handler middleware
+    // 7. Register resources with shutdown manager
+    shutdown_manager_js_1.shutdownManager.registerResources({
+        queue: {
+            drain: (timeoutMs) => queue.drain(timeoutMs),
+            destroy: () => queue.destroy(),
+        },
+        retentionScheduler: {
+            stop: () => retentionScheduler.stop(),
+        },
+    });
+    // 8. Return the request handler middleware
     return async (req, res, next) => {
         // Check ignore list
         const ignoreList = [...ALWAYS_IGNORED_PATHS, ...(config.ignore ?? [])];
@@ -139,15 +132,16 @@ function requestscope(config, adapter) {
  * @param config - RequestScope configuration object
  */
 function setup(app, config) {
-    // Check if running in production environment
-    const nodeEnv = process.env.NODE_ENV;
-    if (nodeEnv === 'production') {
-        process.stderr.write('[RequestScope] Package disabled in production environment (NODE_ENV=production)\n');
-        return;
-    }
     // Validate and apply defaults
     (0, config_js_1.validateConfig)(config);
     (0, config_js_1.applyDefaults)(config);
+    // Check mode - if production, act as no-op
+    if (config.mode === 'production') {
+        process.stderr.write('[RequestScope] Running in production mode - request tracking disabled\n');
+        return;
+    }
+    // Log development mode
+    process.stderr.write('[RequestScope] Running in development mode - request tracking enabled\n');
     // Get or create singleton adapter instance
     const adapter = adapter_singleton_js_1.adapterSingleton.getOrCreate(config.storage);
     // Initialize adapter asynchronously

package/dist/cjs/middleware.js.map

@@ -1 +1 @@
-{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../../src/middleware.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../../src/middleware.ts"],"names":[],"mappings":"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"}

package/dist/cjs/retention.js

@@ -30,6 +30,10 @@ class RetentionScheduler {
         this.intervalHandle = setInterval(() => {
             void this.runOnce();
         }, TWENTY_FOUR_HOURS_MS);
+        // Allow the Node.js process to exit even if this timer is still active.
+        if (this.intervalHandle.unref) {
+            this.intervalHandle.unref();
+        }
     }
     /**
      * Stops the scheduled retention job.  Inflight `runOnce()` calls are allowed

package/dist/cjs/retention.js.map

@@ -1 +1 @@
-{"version":3,"file":"retention.js","sourceRoot":"","sources":["../../src/retention.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAIH,MAAM,oBAAoB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,gBAAgB;AAElE,MAAa,kBAAkB;IAG7B,YACmB,OAAuB,EACvB,aAAqB;QADrB,YAAO,GAAP,OAAO,CAAgB;QACvB,kBAAa,GAAb,aAAa,CAAQ;QAJhC,mBAAc,GAA0C,IAAI,CAAC;IAKlE,CAAC;IAEJ;;;;OAIG;IACH,KAAK;QACH,yEAAyE;QACzE,yCAAyC;QACzC,KAAK,IAAI,CAAC,OAAO,EAAE,CAAC;QAEpB,2CAA2C;QAC3C,IAAI,IAAI,CAAC,cAAc,KAAK,IAAI,EAAE,CAAC;YACjC,aAAa,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QACrC,CAAC;QAED,IAAI,CAAC,cAAc,GAAG,WAAW,CAAC,GAAG,EAAE;YACrC,KAAK,IAAI,CAAC,OAAO,EAAE,CAAC;QACtB,CAAC,EAAE,oBAAoB,CAAC,CAAC;IAC3B,CAAC;IAED;;;OAGG;IACH,IAAI;QACF,IAAI,IAAI,CAAC,cAAc,KAAK,IAAI,EAAE,CAAC;YACjC,aAAa,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;YACnC,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAC7B,CAAC;IACH,CAAC;IAED;;;;OAIG;IACK,KAAK,CAAC,OAAO;QACnB,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,aAAa,GAAG,QAAU,CAAC,CAAC;QACtE,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;YAC3D,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;gBAChB,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,8CAA8C,OAAO,yBAAyB,MAAM,CAAC,WAAW,EAAE,IAAI,CACvG,CAAC;YACJ,CAAC;QACH,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjE,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,4CAA4C,OAAO,IAAI,CACxD,CAAC;QACJ,CAAC;IACH,CAAC;CACF;AA5DD,gDA4DC"}
+{"version":3,"file":"retention.js","sourceRoot":"","sources":["../../src/retention.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAIH,MAAM,oBAAoB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,gBAAgB;AAElE,MAAa,kBAAkB;IAG7B,YACmB,OAAuB,EACvB,aAAqB;QADrB,YAAO,GAAP,OAAO,CAAgB;QACvB,kBAAa,GAAb,aAAa,CAAQ;QAJhC,mBAAc,GAA0C,IAAI,CAAC;IAKlE,CAAC;IAEJ;;;;OAIG;IACH,KAAK;QACH,yEAAyE;QACzE,yCAAyC;QACzC,KAAK,IAAI,CAAC,OAAO,EAAE,CAAC;QAEpB,2CAA2C;QAC3C,IAAI,IAAI,CAAC,cAAc,KAAK,IAAI,EAAE,CAAC;YACjC,aAAa,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QACrC,CAAC;QAED,IAAI,CAAC,cAAc,GAAG,WAAW,CAAC,GAAG,EAAE;YACrC,KAAK,IAAI,CAAC,OAAO,EAAE,CAAC;QACtB,CAAC,EAAE,oBAAoB,CAAC,CAAC;QAEzB,wEAAwE;QACxE,IAAI,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,CAAC;YAC9B,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,CAAC;QAC9B,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,IAAI;QACF,IAAI,IAAI,CAAC,cAAc,KAAK,IAAI,EAAE,CAAC;YACjC,aAAa,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;YACnC,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAC7B,CAAC;IACH,CAAC;IAED;;;;OAIG;IACK,KAAK,CAAC,OAAO;QACnB,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,aAAa,GAAG,QAAU,CAAC,CAAC;QACtE,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;YAC3D,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;gBAChB,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,8CAA8C,OAAO,yBAAyB,MAAM,CAAC,WAAW,EAAE,IAAI,CACvG,CAAC;YACJ,CAAC;QACH,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjE,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,4CAA4C,OAAO,IAAI,CACxD,CAAC;QACJ,CAAC;IACH,CAAC;CACF;AAjED,gDAiEC"}

package/dist/cjs/shutdown-manager.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shutdownManager = void 0;
+const adapter_singleton_js_1 = require("./adapter-singleton.js");
+class ShutdownManager {
+    constructor() {
+        this.isShuttingDown = false;
+        this.resources = {};
+    }
+    /**
+     * Registers resources that need to be cleaned up during shutdown.
+     */
+    registerResources(resources) {
+        this.resources = { ...this.resources, ...resources };
+    }
+    /**
+     * 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
+     */
+    async shutdown(options = {}) {
+        const { drainTimeoutMs = 5000, logHandles = false } = options;
+        // Prevent multiple shutdown executions
+        if (this.isShuttingDown) {
+            process.stderr.write('[RequestScope] Shutdown already in progress, skipping duplicate call\n');
+            return;
+        }
+        this.isShuttingDown = true;
+        process.stderr.write('[RequestScope] Starting graceful shutdown...\n');
+        const startTime = Date.now();
+        try {
+            // 1. Stop retention scheduler
+            if (this.resources.retentionScheduler) {
+                process.stderr.write('[RequestScope] Stopping retention scheduler...\n');
+                this.resources.retentionScheduler.stop();
+            }
+            // 2. Drain queue with timeout
+            if (this.resources.queue) {
+                process.stderr.write(`[RequestScope] Draining queue (timeout: ${drainTimeoutMs}ms)...\n`);
+                try {
+                    await Promise.race([
+                        this.resources.queue.drain(drainTimeoutMs),
+                        new Promise((_, reject) => setTimeout(() => reject(new Error('Queue drain timeout')), drainTimeoutMs))
+                    ]);
+                    process.stderr.write('[RequestScope] Queue drained successfully\n');
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    process.stderr.write(`[RequestScope] Queue drain warning: ${message}\n`);
+                }
+                // 3. Destroy queue (clears timer)
+                process.stderr.write('[RequestScope] Destroying queue...\n');
+                this.resources.queue.destroy();
+            }
+            // 4. Close all database connections
+            process.stderr.write('[RequestScope] Closing database connections...\n');
+            await adapter_singleton_js_1.adapterSingleton.closeAll();
+            process.stderr.write('[RequestScope] Database connections closed\n');
+            const duration = Date.now() - startTime;
+            process.stderr.write(`[RequestScope] Graceful shutdown completed in ${duration}ms\n`);
+            // 5. Log remaining active handles for debugging
+            if (logHandles) {
+                this.logActiveHandles();
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[RequestScope] Shutdown error: ${message}\n`);
+            // Log active handles even on error
+            if (logHandles) {
+                this.logActiveHandles();
+            }
+        }
+    }
+    /**
+     * Logs active handles to help identify what's preventing process exit.
+     */
+    logActiveHandles() {
+        try {
+            // @ts-ignore - _getActiveHandles is not in TypeScript definitions
+            const handles = process._getActiveHandles();
+            process.stderr.write(`[RequestScope] Active handles (${handles.length}):\n`);
+            for (let i = 0; i < Math.min(handles.length, 20); i++) {
+                const handle = handles[i];
+                const type = handle.constructor.name;
+                // @ts-ignore
+                const details = handle._handle?.type || '';
+                process.stderr.write(`  [${i}] ${type}${details ? ` (${details})` : ''}\n`);
+            }
+            if (handles.length > 20) {
+                process.stderr.write(`  ... and ${handles.length - 20} more\n`);
+            }
+        }
+        catch (err) {
+            process.stderr.write('[RequestScope] Could not log active handles\n');
+        }
+    }
+    /**
+     * Returns whether shutdown is currently in progress.
+     */
+    isShutdownInProgress() {
+        return this.isShuttingDown;
+    }
+}
+// Export singleton instance
+exports.shutdownManager = new ShutdownManager();
+//# sourceMappingURL=shutdown-manager.js.map

package/dist/cjs/shutdown-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown-manager.js","sourceRoot":"","sources":["../../src/shutdown-manager.ts"],"names":[],"mappings":"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"}

package/dist/esm/config.js

@@ -39,6 +39,9 @@ const DEFAULT_SENSITIVE_FIELDS = [
  *   storage.ssl    → false
  */
 export function applyDefaults(config) {
+    if (config.mode === undefined) {
+        config.mode = 'development';
+    }
     if (config.retentionDays === undefined) {
         config.retentionDays = 30;
     }
@@ -70,25 +73,29 @@ export function applyDefaults(config) {
  *   4. `retentionDays` (when provided) must be a positive integer in [1, 365].
  */
 export function validateConfig(config) {
-    const { storage, retentionDays } = config;
-    // 1. Validate storage.type
+    const { storage, retentionDays, mode } = config;
+    // 1. Validate mode
+    if (mode !== undefined && mode !== 'development' && mode !== 'production') {
+        throw new Error(`Invalid mode: '${mode}'. Supported values are: development, production`);
+    }
+    // 2. Validate storage.type
     if (!SUPPORTED_STORAGE_TYPES.includes(storage.type)) {
         throw new Error(`Invalid storage type: '${storage.type}'. Supported values are: mongodb, mysql, postgresql`);
     }
-    // 2. MongoDB: uri is required
+    // 3. MongoDB: uri is required
     if (storage.type === 'mongodb') {
         if (!storage.uri) {
             throw new Error("storage.uri is required when storage.type is 'mongodb'");
         }
     }
-    // 3. MySQL / PostgreSQL: all SQL required fields must be present
+    // 4. MySQL / PostgreSQL: all SQL required fields must be present
     if (storage.type === 'mysql' || storage.type === 'postgresql') {
         const missing = SQL_REQUIRED_FIELDS.filter((field) => storage[field] === undefined || storage[field] === null);
         if (missing.length > 0) {
             throw new Error(`Missing required storage fields: ${missing.join(', ')}`);
         }
     }
-    // 4. retentionDays: must be a positive integer in [1, 365] when provided
+    // 5. retentionDays: must be a positive integer in [1, 365] when provided
     if (retentionDays !== undefined) {
         const isValidInteger = typeof retentionDays === 'number' &&
             Number.isInteger(retentionDays) &&

package/dist/esm/index.js

@@ -11,6 +11,7 @@
 import express from 'express';
 import { requestscope as requestscopeMiddleware, errorHandler, setup } from './middleware.js';
 import { createDashboardRouter } from './dashboard/router.js';
+import { shutdownManager } from './shutdown-manager.js';
 // ---------------------------------------------------------------------------
 // Main middleware factory
 // ---------------------------------------------------------------------------
@@ -31,14 +32,13 @@ export default requestscopeMiddleware;
  * @param adapter - Optional storage adapter instance
  * @returns Express Router
  */
-export function dashboard(config, adapter) {
-    // Check if running in production environment
-    const nodeEnv = process.env.NODE_ENV;
-    if (nodeEnv === 'production') {
-        process.stderr.write('[RequestScope] Dashboard disabled in production environment (NODE_ENV=production)\n');
+export function dashboard(config, adapter, mode = 'development') {
+    // Check mode - if production, return disabled router
+    if (mode === 'production') {
+        process.stderr.write('[RequestScope] Dashboard disabled in production mode\n');
         const router = express.Router();
         router.use((req, res, next) => {
-            res.status(404).send('RequestScope dashboard is disabled in production environment');
+            res.status(404).send('RequestScope dashboard is disabled in production mode');
         });
         return router;
     }
@@ -55,6 +55,26 @@ export { setup };
 // ---------------------------------------------------------------------------
 export { errorHandler };
 // ---------------------------------------------------------------------------
+// Shutdown function
+// ---------------------------------------------------------------------------
+/**
+ * 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 async function shutdown(options) {
+    await shutdownManager.shutdown(options);
+}
+// ---------------------------------------------------------------------------
 // Named exports for convenience
 // ---------------------------------------------------------------------------
 export { requestscope as requestscopeMiddleware } from './middleware.js';

package/dist/esm/middleware.js

@@ -16,6 +16,7 @@ import { RetentionScheduler } from './retention.js';
 import { bufferRequestBody, wrapResponse, normalizeRequestUrl, ERROR_DATA_SYMBOL, } from './capture.js';
 import { createDashboardRouter } from './dashboard/router.js';
 import { adapterSingleton } from './adapter-singleton.js';
+import { shutdownManager } from './shutdown-manager.js';
 const ALWAYS_IGNORED_PATHS = ['/favicon.ico', '/requestscope/api', '/requestscope/assets'];
 // ---------------------------------------------------------------------------
 // Factory function
@@ -44,21 +45,22 @@ const ALWAYS_IGNORED_PATHS = ['/favicon.ico', '/requestscope/api', '/requestscop
  * @returns Express RequestHandler middleware
  */
 export function requestscope(config, adapter) {
-    // Check if running in production environment
-    const nodeEnv = process.env.NODE_ENV;
-    if (nodeEnv === 'production') {
-        process.stderr.write('[RequestScope] Package disabled in production environment (NODE_ENV=production)\n');
-        return (req, res, next) => next();
-    }
     // 1. Validate and apply defaults synchronously
     validateConfig(config);
     applyDefaults(config);
+    // 2. Check mode - if production, act as no-op
+    if (config.mode === 'production') {
+        process.stderr.write('[RequestScope] Running in production mode - request tracking disabled\n');
+        return (req, res, next) => next();
+    }
+    // 3. Log development mode
+    process.stderr.write('[RequestScope] Running in development mode - request tracking enabled\n');
     const sensitiveFields = buildSensitiveFieldSet(config);
-    // 2. Get or create singleton adapter instance
+    // 4. Get or create singleton adapter instance
     if (!adapter) {
         adapter = adapterSingleton.getOrCreate(config.storage);
     }
-    // 3. Initialize adapter asynchronously (log errors, don't throw)
+    // 5. Initialize adapter asynchronously (log errors, don't throw)
     // Only initialize if not already initialized
     void adapter.initialize().then(() => {
         adapterSingleton.markInitialized(adapter, config.storage);
@@ -66,31 +68,22 @@ export function requestscope(config, adapter) {
         const message = err instanceof Error ? err.message : String(err);
         process.stderr.write(`[RequestScope] Failed to initialize storage adapter: ${message}\n`);
     });
-    // 4. Create and start AsyncQueue and RetentionScheduler
+    // 6. Create and start AsyncQueue and RetentionScheduler
     const queue = new AsyncQueue(adapter);
     const retentionDays = config.retentionDays ?? 30;
     const retentionScheduler = new RetentionScheduler(adapter, retentionDays);
     retentionScheduler.start();
-    // 5. Attach graceful shutdown handlers (only once per process)
-    const shutdown = async () => {
-        retentionScheduler.stop();
-        await queue.drain(10000);
-        queue.destroy();
-        // Close all database connections via singleton
-        await adapterSingleton.closeAll();
-    };
-    // Use a flag to ensure shutdown handlers are only attached once
-    const shutdownKey = '__requestscope_shutdown_attached__';
-    if (!process[shutdownKey]) {
-        process[shutdownKey] = true;
-        process.on('SIGTERM', () => {
-            void shutdown();
-        });
-        process.on('SIGINT', () => {
-            void shutdown();
-        });
-    }
-    // 6. Return the request handler middleware
+    // 7. Register resources with shutdown manager
+    shutdownManager.registerResources({
+        queue: {
+            drain: (timeoutMs) => queue.drain(timeoutMs),
+            destroy: () => queue.destroy(),
+        },
+        retentionScheduler: {
+            stop: () => retentionScheduler.stop(),
+        },
+    });
+    // 8. Return the request handler middleware
     return async (req, res, next) => {
         // Check ignore list
         const ignoreList = [...ALWAYS_IGNORED_PATHS, ...(config.ignore ?? [])];
@@ -134,15 +127,16 @@ export function requestscope(config, adapter) {
  * @param config - RequestScope configuration object
  */
 export function setup(app, config) {
-    // Check if running in production environment
-    const nodeEnv = process.env.NODE_ENV;
-    if (nodeEnv === 'production') {
-        process.stderr.write('[RequestScope] Package disabled in production environment (NODE_ENV=production)\n');
-        return;
-    }
     // Validate and apply defaults
     validateConfig(config);
     applyDefaults(config);
+    // Check mode - if production, act as no-op
+    if (config.mode === 'production') {
+        process.stderr.write('[RequestScope] Running in production mode - request tracking disabled\n');
+        return;
+    }
+    // Log development mode
+    process.stderr.write('[RequestScope] Running in development mode - request tracking enabled\n');
     // Get or create singleton adapter instance
     const adapter = adapterSingleton.getOrCreate(config.storage);
     // Initialize adapter asynchronously

package/dist/esm/retention.js

@@ -27,6 +27,10 @@ export class RetentionScheduler {
         this.intervalHandle = setInterval(() => {
             void this.runOnce();
         }, TWENTY_FOUR_HOURS_MS);
+        // Allow the Node.js process to exit even if this timer is still active.
+        if (this.intervalHandle.unref) {
+            this.intervalHandle.unref();
+        }
     }
     /**
      * Stops the scheduled retention job.  Inflight `runOnce()` calls are allowed

package/dist/esm/shutdown-manager.js

@@ -0,0 +1,116 @@
+/**
+ * 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.
+ */
+import { adapterSingleton } from './adapter-singleton.js';
+class ShutdownManager {
+    constructor() {
+        this.isShuttingDown = false;
+        this.resources = {};
+    }
+    /**
+     * Registers resources that need to be cleaned up during shutdown.
+     */
+    registerResources(resources) {
+        this.resources = { ...this.resources, ...resources };
+    }
+    /**
+     * 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
+     */
+    async shutdown(options = {}) {
+        const { drainTimeoutMs = 5000, logHandles = false } = options;
+        // Prevent multiple shutdown executions
+        if (this.isShuttingDown) {
+            process.stderr.write('[RequestScope] Shutdown already in progress, skipping duplicate call\n');
+            return;
+        }
+        this.isShuttingDown = true;
+        process.stderr.write('[RequestScope] Starting graceful shutdown...\n');
+        const startTime = Date.now();
+        try {
+            // 1. Stop retention scheduler
+            if (this.resources.retentionScheduler) {
+                process.stderr.write('[RequestScope] Stopping retention scheduler...\n');
+                this.resources.retentionScheduler.stop();
+            }
+            // 2. Drain queue with timeout
+            if (this.resources.queue) {
+                process.stderr.write(`[RequestScope] Draining queue (timeout: ${drainTimeoutMs}ms)...\n`);
+                try {
+                    await Promise.race([
+                        this.resources.queue.drain(drainTimeoutMs),
+                        new Promise((_, reject) => setTimeout(() => reject(new Error('Queue drain timeout')), drainTimeoutMs))
+                    ]);
+                    process.stderr.write('[RequestScope] Queue drained successfully\n');
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    process.stderr.write(`[RequestScope] Queue drain warning: ${message}\n`);
+                }
+                // 3. Destroy queue (clears timer)
+                process.stderr.write('[RequestScope] Destroying queue...\n');
+                this.resources.queue.destroy();
+            }
+            // 4. Close all database connections
+            process.stderr.write('[RequestScope] Closing database connections...\n');
+            await adapterSingleton.closeAll();
+            process.stderr.write('[RequestScope] Database connections closed\n');
+            const duration = Date.now() - startTime;
+            process.stderr.write(`[RequestScope] Graceful shutdown completed in ${duration}ms\n`);
+            // 5. Log remaining active handles for debugging
+            if (logHandles) {
+                this.logActiveHandles();
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[RequestScope] Shutdown error: ${message}\n`);
+            // Log active handles even on error
+            if (logHandles) {
+                this.logActiveHandles();
+            }
+        }
+    }
+    /**
+     * Logs active handles to help identify what's preventing process exit.
+     */
+    logActiveHandles() {
+        try {
+            // @ts-ignore - _getActiveHandles is not in TypeScript definitions
+            const handles = process._getActiveHandles();
+            process.stderr.write(`[RequestScope] Active handles (${handles.length}):\n`);
+            for (let i = 0; i < Math.min(handles.length, 20); i++) {
+                const handle = handles[i];
+                const type = handle.constructor.name;
+                // @ts-ignore
+                const details = handle._handle?.type || '';
+                process.stderr.write(`  [${i}] ${type}${details ? ` (${details})` : ''}\n`);
+            }
+            if (handles.length > 20) {
+                process.stderr.write(`  ... and ${handles.length - 20} more\n`);
+            }
+        }
+        catch (err) {
+            process.stderr.write('[RequestScope] Could not log active handles\n');
+        }
+    }
+    /**
+     * Returns whether shutdown is currently in progress.
+     */
+    isShutdownInProgress() {
+        return this.isShuttingDown;
+    }
+}
+// Export singleton instance
+export const shutdownManager = new ShutdownManager();

package/dist/types/index.d.ts

@@ -25,8 +25,26 @@ export default requestscopeMiddleware;
  * @param adapter - Optional storage adapter instance
  * @returns Express Router
  */
-export declare function dashboard(config?: DashboardConfig, adapter?: StorageAdapter): express.Router;
+export declare function dashboard(config?: DashboardConfig, adapter?: StorageAdapter, mode?: 'development' | 'production'): 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

@@ -69,6 +69,8 @@ export interface DashboardConfig {
 }
 export interface RequestScopeConfig {
     storage: StorageConfig;
+    /** Package mode: 'development' enables all features, 'production' disables all tracking. Default: 'development' */
+    mode?: 'development' | 'production';
     /** Number of days to retain records. Range: 1–365. Default: 30 */
     retentionDays?: number;
     /** Exact URL paths to skip (no capture). Default: [] */

package/package.json

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