express-performance-toolkit 1.0.0 → 2.0.0

package/package.json

@@ -1,16 +1,17 @@
 {
   "name": "express-performance-toolkit",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "⚡ A powerful Express middleware that automatically optimizes your app with request caching, response compression, slow API detection, and a real-time performance dashboard.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
-    "build": "tsc",
+    "build:ui": "cd dashboard-ui && npm install && npm run build",
+    "build": "tsc && npm run build:ui",
     "postbuild": "npm run copy-assets",
-    "copy-assets": "mkdir -p dist/dashboard && cp src/dashboard/dashboard.html dist/dashboard/",
+    "copy-assets": "rm -rf dist/dashboard-ui && cp -R dashboard-ui/dist dist/dashboard-ui",
     "dev": "tsc --watch",
     "test": "jest --verbose",
-    "example": "ts-node example/server.ts",
+    "example": "npm run build && ts-node example/server.ts",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -26,11 +27,13 @@
     "logging",
     "typescript"
   ],
-  "author": "",
+  "author": "Mayank Saini",
   "license": "MIT",
   "dependencies": {
     "compression": "^1.7.4",
-    "on-finished": "^2.4.1"
+    "lucide-react": "^0.577.0",
+    "on-finished": "^2.4.1",
+    "recharts": "^3.8.0"
   },
   "peerDependencies": {
     "express": ">=4.0.0"

package/src/analyzer.ts

@@ -0,0 +1,78 @@
+import { Metrics, Insight } from "./types";
+
+/**
+ * Heuristic-based analysis engine that transforms raw metrics into actionable advice.
+ */
+export function analyzeMetrics(metrics: Metrics): Insight[] {
+  const insights: Insight[] = [];
+
+  // 1. Caching Suggestions
+  Object.entries(metrics.routes).forEach(([path, stats]) => {
+    // If a route is slow and has low/zero cache hits
+    if (stats.avgTime > 500 && stats.count > 5) {
+      if (metrics.cacheHitRate < 10) {
+        insights.push({
+          type: "warning",
+          title: "Slow Route: Caching Opportunity",
+          message: `Route "${path}" is slow (avg ${stats.avgTime}ms).`,
+          action: "Consider enabling the cache middleware for this route.",
+        });
+      }
+    }
+
+    // 2. N+1 Query Detection
+    if (stats.highQueryCount > stats.count * 0.3) {
+      insights.push({
+        type: "error",
+        title: "Potential N+1 Query Detected",
+        message: `Route "${path}" triggers high query counts in ${Math.round((stats.highQueryCount / stats.count) * 100)}% of calls.`,
+        action: "Review your database logic and use eager loading (JOINs).",
+      });
+    }
+
+    // 3. Payload Size Alerts
+    if (stats.avgSize > 1024 * 1024) {
+      // > 1MB
+      insights.push({
+        type: "warning",
+        title: "Heavy Payload Detected",
+        message: `Route "${path}" sends large responses (avg ${(stats.avgSize / 1024 / 1024).toFixed(1)} MB).`,
+        action:
+          "Consider pagination or reducing the number of returned fields.",
+      });
+    }
+
+    // 4. Rate Limiting Insights
+    if (stats.rateLimitHits > stats.count * 0.1) {
+      insights.push({
+        type: "info",
+        title: "High Rate Limiting Activity",
+        message: `Route "${path}" has a high block rate (${Math.round((stats.rateLimitHits / stats.count) * 100)}%).`,
+        action:
+          "Verify if your Rate Limit 'max' is too low or if an IP is scraping you.",
+      });
+    }
+  });
+
+  // 5. System Health
+  if (metrics.eventLoopLag > 100) {
+    insights.push({
+      type: "error",
+      title: "Event Loop Lagging",
+      message: `Critical event loop delay detected (${metrics.eventLoopLag}ms).`,
+      action: "Identify blocking synchronous operations in your code.",
+    });
+  }
+
+  if (metrics.memoryUsage.heapUsed > metrics.memoryUsage.heapLimit * 0.8) {
+    insights.push({
+      type: "warning",
+      title: "High Memory Pressure",
+      message: "Node.js heap usage is above 80% of total limit.",
+      action:
+        "Monitor for memory leaks or increase memory limit (--max-old-space-size).",
+    });
+  }
+
+  return insights;
+}

package/src/dashboard/dashboardRouter.ts

@@ -1,8 +1,15 @@
-import { Router, Request, Response } from 'express';
-import * as path from 'path';
-import * as fs from 'fs';
-import { MetricsStore } from '../store';
-import { DashboardOptions } from '../types';
+import express, { Router, Request, Response, NextFunction } from "express";
+import * as path from "path";
+import { MetricsStore } from "../store";
+import { DashboardOptions } from "../types";
+
+/**
+ * Simple session-less auth token based on the secret.
+ * In a real-world scenario, you'd use a more robust session manager or JWT.
+ */
+const generateToken = (secret: string) => {
+  return Buffer.from(`auth:${secret}`).toString("base64");
+};
 
 /**
  * Create the dashboard Express router.
@@ -10,36 +17,94 @@ import { DashboardOptions } from '../types';
  */
 export function createDashboardRouter(
   store: MetricsStore,
-  _options: DashboardOptions = {}
+  options: DashboardOptions = {},
 ): Router {
   const router = Router();
 
-  // Cache the HTML file in memory
-  const htmlPath = path.join(__dirname, 'dashboard.html');
-  let dashboardHtml: string;
+  // Default auth settings if none provided (Security by default)
+  const auth = options.auth || {
+    username: "admin",
+    password: "perf-toolkit",
+    secret: "toolkit-secret",
+  };
+
+  const mountPath = options.path || "/__perf";
+
+  // Use JSON parsing for login endpoint
+  router.use(express.json());
+
+  // Authentication Middleware
+  const requireAuth = (req: Request, res: Response, next: NextFunction) => {
+    if (!auth) return next();
+
+    const expectedToken = generateToken(auth.secret || "toolkit-secret");
+    const cookie = req.headers.cookie || "";
+    const hasToken = cookie.includes(`perf-auth=${expectedToken}`);
+
+    if (hasToken) {
+      return next();
+    }
+
+    res.status(401).json({ success: false, message: "Unauthorized" });
+  };
 
-  try {
-    dashboardHtml = fs.readFileSync(htmlPath, 'utf-8');
-  } catch {
-    dashboardHtml = '<h1>Dashboard HTML not found</h1><p>Ensure dashboard.html is in the dist/dashboard/ directory.</p>';
-  }
+  // Login Endpoint
+  router.post("/api/login", (req: Request, res: Response) => {
+    if (!auth) {
+      return res.json({ success: true, message: "Auth disabled" });
+    }
 
-  // Serve dashboard HTML
-  router.get('/', (_req: Request, res: Response) => {
-    res.set('Content-Type', 'text/html');
-    res.send(dashboardHtml);
+    const { username, password } = req.body;
+    const defaultUser = auth.username || "admin";
+    const defaultPass = auth.password || "perf-toolkit";
+
+    if (username === defaultUser && password === defaultPass) {
+      const token = generateToken(auth.secret || "toolkit-secret");
+      // Set cookie with HttpOnly and reasonable maxAge
+      res.setHeader(
+        "Set-Cookie",
+        `perf-auth=${token}; Path=${mountPath}; HttpOnly; Max-Age=86400; SameSite=Lax`,
+      );
+      return res.json({ success: true });
+    }
+
+    res.status(401).json({ success: false, message: "Invalid credentials" });
   });
 
-  // JSON metrics API endpoint
-  router.get('/api/metrics', (_req: Request, res: Response) => {
+  // Logout Endpoint
+  router.post("/api/logout", (_req: Request, res: Response) => {
+    res.setHeader(
+      "Set-Cookie",
+      `perf-auth=; Path=${mountPath}; HttpOnly; Max-Age=0`,
+    );
+    res.json({ success: true });
+  });
+
+  // Check auth status endpoint
+  router.get("/api/auth-check", (req: Request, res: Response) => {
+    if (!auth) return res.json({ authenticated: true, required: false });
+
+    const expectedToken = generateToken(auth.secret || "toolkit-secret");
+    const cookie = req.headers.cookie || "";
+    const authenticated = cookie.includes(`perf-auth=${expectedToken}`);
+
+    res.json({ authenticated, required: true });
+  });
+
+  // JSON metrics API endpoint (Protected)
+  router.get("/api/metrics", requireAuth, (_req: Request, res: Response) => {
     res.json(store.getMetrics());
   });
 
-  // Reset metrics endpoint
-  router.post('/api/reset', (_req: Request, res: Response) => {
+  // Reset metrics endpoint (Protected)
+  router.post("/api/reset", requireAuth, (_req: Request, res: Response) => {
     store.reset();
-    res.json({ success: true, message: 'Metrics reset' });
+    res.json({ success: true, message: "Metrics reset" });
   });
 
+  // Serve React Dashboard UI bundle
+  const uiPath = path.resolve(__dirname, "../../dist/dashboard-ui");
+  router.use("/", express.static(uiPath));
+
   return router;
 }

package/src/index.ts

@@ -1,20 +1,22 @@
-import { Request, Response, NextFunction, Router } from 'express';
-import { MetricsStore } from './store';
-import { createCacheMiddleware, LRUCache } from './cache';
-import { createCompressionMiddleware } from './compression';
-import { createLoggerMiddleware } from './logger';
-import { createQueryHelperMiddleware } from './queryHelper';
-import { createDashboardRouter } from './dashboard/dashboardRouter';
+import { Request, Response, NextFunction, Router } from "express";
+import { MetricsStore } from "./store";
+import { createCacheMiddleware, LRUCache } from "./cache";
+import { createCompressionMiddleware } from "./compression";
+import { createLoggerMiddleware } from "./logger";
+import { createQueryHelperMiddleware } from "./queryHelper";
+import { createRateLimiter } from "./rateLimit";
+import { createDashboardRouter } from "./dashboard/dashboardRouter";
 import {
   ToolkitOptions,
   CacheOptions,
   CompressionOptions,
   LoggerOptions,
   QueryHelperOptions,
+  RateLimitOptions,
   DashboardOptions,
   Metrics,
   CacheMiddleware,
-} from './types';
+} from "./types";
 
 export interface ToolkitInstance {
   /** The composed Express middleware */
@@ -50,44 +52,83 @@ export interface ToolkitInstance {
  * app.use('/__perf', toolkit.dashboardRouter);
  * ```
  */
-export function performanceToolkit(options: ToolkitOptions = {}): ToolkitInstance {
+export function performanceToolkit(
+  options: ToolkitOptions = {},
+): ToolkitInstance {
   const store = new MetricsStore({ maxLogs: options.maxLogs || 1000 });
 
-  const middlewares: ((req: Request, res: Response, next: NextFunction) => void)[] = [];
+  const middlewares: ((
+    req: Request,
+    res: Response,
+    next: NextFunction,
+  ) => void)[] = [];
   let cacheMiddlewareInstance: CacheMiddleware | null = null;
 
+  // ── Dashboard Config ─────────────────────────────────────
+  const dashboardConfig = normalizeOption<DashboardOptions>(options.dashboard, {
+    enabled: true,
+  });
+  const dashboardExcludePath = dashboardConfig.path || "/__perf";
+
+  // ── Rate Limiter ─────────────────────────────────────────
+  const rateLimitConfig = normalizeOption<RateLimitOptions>(options.rateLimit, {
+    enabled: false,
+  });
+  if (rateLimitConfig.enabled !== false) {
+    // Automatically exclude dashboard from rate limiting to prevent UI lockouts
+    rateLimitConfig.exclude = [
+      ...(rateLimitConfig.exclude || []),
+      dashboardExcludePath,
+    ];
+    middlewares.push(createRateLimiter(store, rateLimitConfig));
+  }
+
   // ── Compression ──────────────────────────────────────────
-  const compressionConfig = normalizeOption<CompressionOptions>(options.compression, { enabled: true });
+  const compressionConfig = normalizeOption<CompressionOptions>(
+    options.compression,
+    { enabled: true },
+  );
   if (compressionConfig.enabled !== false) {
     middlewares.push(createCompressionMiddleware(compressionConfig));
   }
 
   // ── Query Helper ─────────────────────────────────────────
-  const queryConfig = normalizeOption<QueryHelperOptions>(options.queryHelper, { enabled: false });
+  const queryConfig = normalizeOption<QueryHelperOptions>(options.queryHelper, {
+    enabled: false,
+  });
   if (queryConfig.enabled !== false) {
     middlewares.push(createQueryHelperMiddleware(queryConfig));
   }
 
   // ── Logger (slow request detection) ──────────────────────
-  const loggerConfig = normalizeOption<LoggerOptions>(options.logSlowRequests, { enabled: true });
+  const loggerConfig = normalizeOption<LoggerOptions>(options.logSlowRequests, {
+    enabled: true,
+  });
   if (loggerConfig.enabled !== false) {
     middlewares.push(createLoggerMiddleware(loggerConfig, store));
   }
 
   // ── Cache ────────────────────────────────────────────────
-  const cacheConfig = normalizeOption<CacheOptions>(options.cache, { enabled: false });
+  const cacheConfig = normalizeOption<CacheOptions>(options.cache, {
+    enabled: false,
+  });
   if (cacheConfig.enabled !== false) {
     cacheMiddlewareInstance = createCacheMiddleware(cacheConfig, store);
     middlewares.push(cacheMiddlewareInstance);
   }
 
   // ── Dashboard Router ─────────────────────────────────────
-  const dashboardConfig = normalizeOption<DashboardOptions>(options.dashboard, { enabled: true });
-  const dashboardPath = dashboardConfig.path || '/__perf';
-  const dashboardRouter = createDashboardRouter(store, dashboardConfig);
+  const dashboardRouter = createDashboardRouter(store, {
+    ...dashboardConfig,
+    path: "/", // Always serve at the root of the provided router
+  });
 
   // ── Composed Middleware ──────────────────────────────────
-  function composedMiddleware(req: Request, res: Response, next: NextFunction): void {
+  function composedMiddleware(
+    req: Request,
+    res: Response,
+    next: NextFunction,
+  ): void {
     let index = 0;
 
     function runNext(err?: unknown): void {
@@ -117,25 +158,24 @@ export function performanceToolkit(options: ToolkitOptions = {}): ToolkitInstanc
 
 /**
  * Normalize a boolean | object option into a config object.
- * - `true` → defaults with enabled: true
- * - `false` → defaults with enabled: false
- * - object → merged with defaults
  */
 function normalizeOption<T extends { enabled?: boolean }>(
   value: boolean | T | undefined,
-  defaults: T
+  defaults: T,
 ): T {
   if (value === true) return { ...defaults, enabled: true };
   if (value === false) return { ...defaults, enabled: false };
-  if (typeof value === 'object') return { ...defaults, ...value, enabled: true };
+  if (typeof value === "object")
+    return { ...defaults, ...value, enabled: true };
   return defaults;
 }
 
 // ── Re-exports ─────────────────────────────────────────────
-export { MetricsStore } from './store';
-export { LRUCache, createCacheMiddleware } from './cache';
-export { createCompressionMiddleware } from './compression';
-export { createLoggerMiddleware } from './logger';
-export { createQueryHelperMiddleware } from './queryHelper';
-export { createDashboardRouter } from './dashboard/dashboardRouter';
-export * from './types';
+export { MetricsStore } from "./store";
+export { LRUCache, createCacheMiddleware } from "./cache";
+export { createCompressionMiddleware } from "./compression";
+export { createLoggerMiddleware } from "./logger";
+export { createQueryHelperMiddleware } from "./queryHelper";
+export { createRateLimiter } from "./rateLimit";
+export { createDashboardRouter } from "./dashboard/dashboardRouter";
+export * from "./types";

package/src/logger.ts

@@ -1,42 +1,195 @@
-import { Request, Response, NextFunction } from 'express';
-import onFinished from 'on-finished';
-import { LoggerOptions, LogEntry } from './types';
-import { MetricsStore } from './store';
+import { Request, Response, NextFunction } from "express";
+import onFinished from "on-finished";
+import * as fs from "fs";
+import * as path from "path";
+import { LoggerOptions, LogEntry } from "./types";
+import { MetricsStore } from "./store";
 
 /**
  * Default log formatter for console output.
  */
 function defaultFormatter(entry: LogEntry): string {
-  const slow = entry.slow ? ' 🔥 SLOW' : '';
-  const cached = entry.cached ? ' [CACHED]' : '';
+  const slow = entry.slow ? " 🔥 SLOW" : "";
+  const cached = entry.cached ? " [CACHED]" : "";
   const status = entry.statusCode;
   const time = `${entry.responseTime}ms`;
 
   return `[perf] ${entry.method} ${entry.path} → ${status} ${time}${cached}${slow}`;
 }
 
+/**
+ * Helper class for managing log file rotation and cleanup.
+ */
+class LogRotator {
+  private currentStream: fs.WriteStream | null = null;
+  private currentDateStr: string = "";
+  private basePath: string;
+  private logDir: string;
+  private rotation: boolean;
+  private maxDays: number;
+
+  constructor(filePath: string, rotation: boolean, maxDays: number) {
+    this.basePath = path.resolve(process.cwd(), filePath);
+    this.logDir = path.dirname(this.basePath);
+    this.rotation = rotation;
+    this.maxDays = maxDays;
+
+    if (!fs.existsSync(this.logDir)) {
+      fs.mkdirSync(this.logDir, { recursive: true });
+    }
+
+    this.getStream(); // Initialize
+  }
+
+  private getDateStr(date: Date = new Date()): string {
+    return date.toISOString().split("T")[0];
+  }
+
+  private getRotatedPath(dateStr: string): string {
+    if (!this.rotation) return this.basePath;
+    const ext = path.extname(this.basePath);
+    const base = path.basename(this.basePath, ext);
+    return path.join(this.logDir, `${base}-${dateStr}${ext}`);
+  }
+
+  public getStream(): fs.WriteStream {
+    if (!this.rotation) {
+      if (!this.currentStream) {
+        this.currentStream = fs.createWriteStream(this.basePath, {
+          flags: "a",
+        });
+      }
+      return this.currentStream;
+    }
+
+    const todayStr = this.getDateStr();
+    if (this.currentDateStr !== todayStr) {
+      if (this.currentStream) {
+        this.currentStream.end();
+      }
+      this.currentDateStr = todayStr;
+      const newPath = this.getRotatedPath(todayStr);
+      this.currentStream = fs.createWriteStream(newPath, { flags: "a" });
+
+      // Run cleanup asynchronously in the background
+      this.cleanupOldLogs();
+    }
+    return this.currentStream!;
+  }
+
+  private cleanupOldLogs() {
+    if (!this.rotation || this.maxDays <= 0) return;
+
+    fs.readdir(this.logDir, (err, files) => {
+      if (err) return;
+
+      const ext = path.extname(this.basePath);
+      const base = path.basename(this.basePath, ext);
+      const prefix = `${base}-`;
+
+      const now = Date.now();
+      const maxAgeMs = this.maxDays * 24 * 60 * 60 * 1000;
+
+      files.forEach((file) => {
+        if (file.startsWith(prefix) && file.endsWith(ext)) {
+          const datePart = file.slice(prefix.length, -ext.length);
+          const fileDate = new Date(datePart).getTime();
+
+          if (!isNaN(fileDate) && now - fileDate > maxAgeMs) {
+            fs.unlink(path.join(this.logDir, file), (unlinkErr) => {
+              if (unlinkErr)
+                console.error(
+                  `[perf-toolkit] Failed to delete old log: ${file}`,
+                );
+            });
+          }
+        }
+      });
+    });
+  }
+}
+
 /**
  * Create request logging & slow API detection middleware.
  */
 export function createLoggerMiddleware(
   options: LoggerOptions = {},
-  store: MetricsStore
+  store: MetricsStore,
 ): (req: Request, res: Response, next: NextFunction) => void {
   const {
     slowThreshold = 1000,
     console: logToConsole = true,
+    file: logFilePath,
+    rotation = false,
+    maxDays = 7,
     formatter = defaultFormatter,
   } = options;
 
+  let rotator: LogRotator | null = null;
+  if (logFilePath) {
+    try {
+      rotator = new LogRotator(logFilePath, rotation, maxDays);
+    } catch (err) {
+      console.error(`[perf-toolkit] Failed to initialize log rotator: ${err}`);
+    }
+  }
+
   return (req: Request, res: Response, next: NextFunction): void => {
     const startTime = Date.now();
+    const reqPath = req.originalUrl || req.url;
+
+    // Ignore dashboard API paths
+    if (
+      reqPath.includes("/api/metrics") ||
+      reqPath.includes("/api/reset") ||
+      reqPath.includes("/api/__perf")
+    ) {
+      return next();
+    }
+
+    // Byte counting logic
+    let bytesSent = 0;
+    const originalWrite = res.write;
+    const originalEnd = res.end;
+
+    res.write = function (
+      chunk: any,
+      encoding?: any,
+      _callback?: any,
+    ): boolean {
+      if (chunk) {
+        bytesSent += Buffer.isBuffer(chunk)
+          ? chunk.length
+          : Buffer.byteLength(
+              chunk,
+              (typeof encoding === "string"
+                ? encoding
+                : "utf8") as BufferEncoding,
+            );
+      }
+      return originalWrite.apply(res, arguments as any);
+    };
+
+    res.end = function (chunk: any, encoding?: any, _callback?: any): Response {
+      if (chunk && typeof chunk !== "function") {
+        bytesSent += Buffer.isBuffer(chunk)
+          ? chunk.length
+          : Buffer.byteLength(
+              chunk,
+              (typeof encoding === "string"
+                ? encoding
+                : "utf8") as BufferEncoding,
+            );
+      }
+      return originalEnd.apply(res, arguments as any);
+    };
 
     // Attach perf data to request
     if (!req.perfToolkit) {
       req.perfToolkit = {
         startTime,
         queryCount: 0,
-        trackQuery: (label?: string) => {
+        trackQuery: () => {
           req.perfToolkit!.queryCount++;
         },
       };
@@ -46,22 +199,27 @@ export function createLoggerMiddleware(
       const responseTime = Date.now() - startTime;
       const isSlow = responseTime >= slowThreshold;
 
+      // Extract route pattern if available (e.g. /users/:id)
+      const routePattern = (req as any).route?.path;
+
       const entry: LogEntry = {
         method: req.method,
-        path: req.originalUrl || req.url,
+        path: reqPath,
+        routePattern,
         statusCode: finishedRes.statusCode,
         responseTime,
         timestamp: Date.now(),
         slow: isSlow,
-        cached: res.getHeader('X-Cache') === 'HIT',
+        cached: res.getHeader("X-Cache") === "HIT",
+        highQueries: req.perfToolkit?.highQueries || false,
         queryCount: req.perfToolkit?.queryCount,
-        contentLength: parseInt(res.getHeader('content-length') as string, 10) || undefined,
-        userAgent: req.get('user-agent'),
+        bytesSent,
+        userAgent: req.get("user-agent"),
         ip: req.ip,
       };
 
       // Record in store
-      store.addLog(entry);
+      store.recordLog(entry);
 
       if (isSlow) {
         store.recordSlowRequest();
@@ -76,6 +234,12 @@ export function createLoggerMiddleware(
           console.log(message);
         }
       }
+
+      // File output
+      if (rotator) {
+        const logLine = JSON.stringify(entry) + "\n";
+        rotator.getStream().write(logLine);
+      }
     });
 
     next();

package/src/queryHelper.ts

@@ -31,6 +31,8 @@ export function createQueryHelperMiddleware(
 
       // Warn if threshold exceeded
       if (req.perfToolkit!.queryCount === threshold) {
+        req.perfToolkit!.highQueries = true;
+        
         console.warn(
           `[perf] ⚠️  N+1 Alert: ${req.method} ${req.originalUrl || req.url} ` +
             `has made ${threshold}+ queries. Consider optimizing with batch/join queries.`