request-scope-api 1.0.0

package/dist/types/dashboard/router.d.ts

@@ -0,0 +1,28 @@
+/**
+ * RequestScope — Dashboard router.
+ *
+ * Provides an Express router with:
+ *   - Optional BasicAuth middleware
+ *   - API routes for querying records
+ *   - Static file serving for the React SPA
+ *   - SPA fallback for client-side routing
+ *
+ * Requirements: 8.1, 8.2, 8.3, 8.4
+ */
+import { Router } from 'express';
+import type { DashboardConfig, StorageAdapter } from '../types';
+/**
+ * Creates and returns an Express router for the RequestScope dashboard.
+ *
+ * The router includes:
+ *   - BasicAuth middleware (if auth config is provided)
+ *   - GET /api/records — List records with filtering and pagination
+ *   - GET /api/records/:id — Get a single record by ID
+ *   - Static file serving for the React SPA
+ *   - SPA fallback for client-side routing
+ *
+ * @param config - Optional dashboard configuration
+ * @param adapter - Storage adapter instance (must be set on the app)
+ * @returns Express Router
+ */
+export declare function createDashboardRouter(config?: DashboardConfig, adapter?: StorageAdapter): Router;

package/dist/types/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * RequestScope — Public API entry point.
+ *
+ * Exports:
+ *   - Default export: requestscope(config) middleware factory
+ *   - requestscope.dashboard: dashboard router factory
+ *   - All public TypeScript interfaces
+ *
+ * Requirements: 1.1, 12.1, 12.2, 12.3, 12.4
+ */
+import { requestscope as requestscopeMiddleware, errorHandler, setup } from './middleware';
+import type { RequestScopeConfig, StorageConfig, AuthConfig, RequestRecord, StorageAdapter, QueryFilters, DashboardConfig } from './types';
+/**
+ * Creates and returns an Express middleware that captures HTTP requests.
+ *
+ * @param config - RequestScope configuration object
+ * @returns Express RequestHandler middleware
+ */
+export default requestscopeMiddleware;
+/**
+ * Creates and returns an Express router for the RequestScope dashboard.
+ *
+ * @param config - Optional dashboard configuration
+ * @param adapter - Optional storage adapter instance
+ * @returns Express Router
+ */
+export declare function dashboard(config?: DashboardConfig, adapter?: StorageAdapter): import("express").Router;
+export { setup };
+export { errorHandler };
+export type { RequestScopeConfig, StorageConfig, AuthConfig, RequestRecord, StorageAdapter, QueryFilters, DashboardConfig, };
+export { requestscope as requestscopeMiddleware } from './middleware';

package/dist/types/masker.d.ts

@@ -0,0 +1,15 @@
+/**
+ * masker.ts — Recursive sensitive field masking
+ *
+ * Provides a pure function that recursively replaces sensitive field values
+ * with "******" at any nesting depth.
+ */
+/**
+ * Recursively masks sensitive fields in an object.
+ *
+ * @param obj - The object to mask
+ * @param sensitiveFields - Set of field names to mask (stored in lowercase)
+ * @param depth - Current recursion depth (default: 0)
+ * @returns A new object with sensitive fields replaced by "******"
+ */
+export declare function maskObject(obj: Record<string, unknown>, sensitiveFields: Set<string>, depth?: number): Record<string, unknown>;

package/dist/types/middleware.d.ts

@@ -0,0 +1,67 @@
+/**
+ * RequestScope — Core middleware factory.
+ *
+ * Provides:
+ *   - requestscope(config) — Express middleware factory that validates config,
+ *     instantiates the appropriate storage adapter, creates AsyncQueue and
+ *     RetentionScheduler, and returns a request handler.
+ *   - errorHandler — 4-arity error middleware that attaches error data to
+ *     the request for capture by the finish handler.
+ *
+ * Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 2.2, 4.1, 4.2, 4.3, 5.1
+ */
+import type { Request, Response, NextFunction, RequestHandler } from 'express';
+import type { RequestScopeConfig, StorageAdapter } from './types';
+/**
+ * Creates and returns an Express middleware that captures HTTP requests.
+ *
+ * Validation and initialization:
+ *   1. Calls `validateConfig()`, `applyDefaults()`, and `buildSensitiveFieldSet()`
+ *      synchronously; throws on any validation error.
+ *   2. Instantiates the correct `StorageAdapter` based on `storage.type` (unless adapter is provided).
+ *   3. Calls `adapter.initialize()` asynchronously; logs errors to `stderr`
+ *      without throwing (middleware continues to function even if storage fails).
+ *   4. Creates `AsyncQueue` and `RetentionScheduler`; starts both.
+ *   5. Attaches queue `drain()` to `process.on('SIGTERM')` and
+ *      `process.on('SIGINT')` for graceful shutdown.
+ *
+ * Request handling:
+ *   - Checks `ignore` list; skips capture and calls `next()` if matched.
+ *   - Buffers request body via `bufferRequestBody()`.
+ *   - Wraps response via `wrapResponse()` to accumulate response chunks.
+ *   - On response finish, builds `RequestRecord` and enqueues it.
+ *
+ * @param config - RequestScope configuration object
+ * @param adapter - Optional storage adapter instance (for sharing with dashboard)
+ * @returns Express RequestHandler middleware
+ */
+export declare function requestscope(config: RequestScopeConfig, adapter?: StorageAdapter): RequestHandler;
+/**
+ * Sets up RequestScope middleware and automatically mounts the dashboard at /requestscope.
+ *
+ * This function:
+ *   1. Creates the storage adapter
+ *   2. Sets up the request capture middleware
+ *   3. Automatically mounts the dashboard at /requestscope
+ *
+ * @param app - Express application instance
+ * @param config - RequestScope configuration object
+ */
+export declare function setup(app: any, config: RequestScopeConfig): void;
+/**
+ * 4-arity error middleware that attaches error data to the request.
+ *
+ * The error data (message, stack, statusCode) is attached via a Symbol-keyed
+ * property so the response finish handler can include it in the RequestRecord.
+ *
+ * Usage:
+ *   app.use(requestscope(config));
+ *   app.use(errorHandler);
+ *   // ... route handlers that may throw
+ *
+ * @param err - Error object
+ * @param req - Express Request
+ * @param res - Express Response
+ * @param next - Express NextFunction
+ */
+export declare function errorHandler(err: Error, req: Request, res: Response, next: NextFunction): void;

package/dist/types/queue.d.ts

@@ -0,0 +1,49 @@
+/**
+ * AsyncQueue — In-process batch write queue.
+ *
+ * Decouples the hot-path enqueue (synchronous, ≤1 ms) from database writes,
+ * which happen asynchronously in configurable batches. Fault isolation is
+ * total: adapter failures are caught, logged to stderr, and discarded so
+ * they never propagate to the caller.
+ */
+import type { RequestRecord, StorageAdapter } from './types';
+export declare class AsyncQueue {
+    private readonly adapter;
+    private readonly batchSize;
+    private readonly flushIntervalMs;
+    private readonly maxCapacity;
+    private items;
+    private flushTimer;
+    private isFlushing;
+    constructor(adapter: StorageAdapter, batchSize?: number, flushIntervalMs?: number, maxCapacity?: number);
+    /**
+     * Synchronously adds a record to the queue.
+     *
+     * If the queue is at capacity, the record is discarded and a warning is
+     * written to stderr. If the queue has reached `batchSize` after this push,
+     * a flush is triggered immediately (fire-and-forget).
+     */
+    enqueue(record: RequestRecord): void;
+    /**
+     * Flushes up to `batchSize` items from the front of the queue.
+     *
+     * A guard (`isFlushing`) prevents concurrent flushes. The splice is
+     * performed atomically before the async adapter call so no records are
+     * lost even if the adapter rejects. On failure the batch is discarded
+     * and the error is written to stderr.
+     */
+    private flush;
+    /**
+     * Flushes all remaining items in the queue, waiting at most `timeoutMs`
+     * milliseconds. Any items that could not be flushed before the timeout
+     * are logged to stderr.
+     *
+     * Used during graceful shutdown (SIGTERM / SIGINT).
+     */
+    drain(timeoutMs?: number): Promise<void>;
+    /**
+     * Clears the periodic flush timer. Call this to allow the Node.js process
+     * to exit cleanly, or when the queue is no longer needed.
+     */
+    destroy(): void;
+}

package/dist/types/retention.d.ts

@@ -0,0 +1,30 @@
+/**
+ * RetentionScheduler — automatically purges records older than the configured
+ * retention window by calling `adapter.deleteOlderThan()` once per day.
+ *
+ * Requirements: 7.1, 7.2, 7.4, 7.5
+ */
+import type { StorageAdapter } from './adapters/adapter.interface';
+export declare class RetentionScheduler {
+    private readonly adapter;
+    private readonly retentionDays;
+    private intervalHandle;
+    constructor(adapter: StorageAdapter, retentionDays: number);
+    /**
+     * Runs the retention job immediately, then schedules it to repeat every 24 h.
+     * Calling `start()` more than once has no additional effect until `stop()` is
+     * called first (the previous interval is replaced by the new one).
+     */
+    start(): void;
+    /**
+     * Stops the scheduled retention job.  Inflight `runOnce()` calls are allowed
+     * to complete naturally because they are fire-and-forget.
+     */
+    stop(): void;
+    /**
+     * Computes the cutoff date from `retentionDays` and asks the adapter to
+     * delete every record older than that date.  Any error is logged to `stderr`
+     * but never rethrown so the scheduler stays alive for the next tick.
+     */
+    private runOnce;
+}

package/dist/types/types.d.ts

@@ -0,0 +1,101 @@
+/**
+ * RequestScope — All exported TypeScript interfaces.
+ *
+ * This file is the single source of truth for every public type in the library.
+ * All interfaces are written to compile under `strict: true` with zero errors.
+ */
+export interface RequestRecord {
+    id: string;
+    method: string;
+    url: string;
+    route: string | null;
+    queryParams: Record<string, string>;
+    pathParams: Record<string, string>;
+    requestHeaders: Record<string, string>;
+    requestBody: string;
+    requestBodySize: number;
+    clientIp: string;
+    userAgent: string;
+    statusCode: number;
+    responseHeaders: Record<string, string>;
+    responseBody: string;
+    responseBodySize: number;
+    responseTime: number;
+    errorMessage: string | null;
+    errorStack: string | null;
+    errorStatusCode: number | null;
+    timestamp: string;
+}
+export interface QueryFilters {
+    /** Case-insensitive substring match on url */
+    search?: string;
+    /** ISO 8601 — inclusive lower bound on timestamp */
+    startDate?: string;
+    /** ISO 8601 — inclusive upper bound on timestamp */
+    endDate?: string;
+    statusCodeGroup?: '2xx' | '3xx' | '4xx' | '5xx';
+    /** Exact match; takes precedence over statusCodeGroup */
+    statusCode?: number;
+    /** Exact match, case-insensitive */
+    method?: string;
+    /** Exact match on record ID */
+    id?: string;
+    sortBy?: 'timestamp' | 'responseTime' | 'statusCode';
+    sortOrder?: 'asc' | 'desc';
+    page: number;
+    pageSize: number;
+}
+export interface StorageConfig {
+    type: 'mongodb' | 'mysql' | 'postgresql';
+    uri?: string;
+    host?: string;
+    port?: number;
+    database?: string;
+    username?: string;
+    password?: string;
+    /** Connection pool size. Default: 5 */
+    poolSize?: number;
+    /** Enable SSL/TLS. Default: false */
+    ssl?: boolean;
+}
+export interface AuthConfig {
+    username: string;
+    password: string;
+}
+export interface DashboardConfig {
+    auth?: AuthConfig;
+    /** Mount path for the dashboard. Default: "/requestscope" */
+    mountPath?: string;
+}
+export interface RequestScopeConfig {
+    storage: StorageConfig;
+    /** Number of days to retain records. Range: 1–365. Default: 30 */
+    retentionDays?: number;
+    /** Exact URL paths to skip (no capture). Default: [] */
+    ignore?: string[];
+    /** Additional field names to mask. Merged with the built-in defaults. Default: [] */
+    maskFields?: string[];
+    dashboard?: DashboardConfig;
+}
+export interface StorageAdapter {
+    /** Creates tables / collections if they do not already exist. */
+    initialize(): Promise<void>;
+    /** Batch-inserts an array of request records. */
+    insert(records: RequestRecord[]): Promise<void>;
+    /**
+     * Returns the page slice of records matching `filters` together with the
+     * total count of all matching records (across all pages).
+     */
+    query(filters: QueryFilters, pagination: {
+        page: number;
+        pageSize: number;
+    }): Promise<{
+        records: RequestRecord[];
+        total: number;
+    }>;
+    /**
+     * Deletes all records whose creation timestamp is older than `date`.
+     * Returns the number of deleted records.
+     */
+    deleteOlderThan(date: Date): Promise<number>;
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "request-scope-api",
+  "version": "1.0.0",
+  "description": "Zero-friction API request observability for Express.js applications",
+  "keywords": [
+    "express",
+    "middleware",
+    "monitoring",
+    "telescope",
+    "observability",
+    "request-logging"
+  ],
+  "license": "MIT",
+  "author": "jaydip",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "types": "./dist/types/index.d.ts"
+    }
+  },
+  "main": "dist/cjs/index.js",
+  "types": "dist/types/index.d.ts",
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc --project tsconfig.json",
+    "build:esm": "tsc --project tsconfig.esm.json",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "express": "4.18.2",
+    "mongodb": "6.3.0",
+    "mysql2": "3.6.5",
+    "pg": "8.11.3",
+    "uuid": "9.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "4.17.21",
+    "@types/node": "20.10.0",
+    "@types/pg": "8.10.9",
+    "@types/uuid": "9.0.7",
+    "typescript": "^5.9.3"
+  },
+  "module": "dist/esm/index.js"
+}