express-performance-toolkit 1.0.0 → 2.0.0

package/README.md

@@ -1,7 +1,8 @@
 # ⚡ Express Performance Toolkit
 
-A powerful, all-in-one Express middleware that automatically optimizes your app with **request caching**, **response compression**, **slow API detection**, **query optimization helpers**, and a stunning **real-time performance dashboard**.
+A powerful, all-in-one Express middleware that automatically optimizes your app with **request caching**, **response compression**, **smart rate limiting**, **bandwidth tracking**, **slow API detection**, **query optimization helpers**, and a stunning **real-time modular performance dashboard**.
 
+[![npm version](https://img.shields.io/npm/v/express-performance-toolkit.svg?style=flat-square)](https://www.npmjs.com/package/express-performance-toolkit)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue)](https://www.typescriptlang.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
 
@@ -11,10 +12,14 @@ A powerful, all-in-one Express middleware that automatically optimizes your app
 
 - 🚀 **Request Caching** — In-memory LRU cache with TTL (+ optional Redis adapter)
 - 🗜️ **Response Compression** — Gzip/deflate with configurable thresholds
+- 🛡️ **Smart Rate Limiting** — Protect your API with IP-based limits and blocked traffic tracking
+- 📉 **Bandwidth Monitoring** — Real-time tracking of network egress and payload sizes
 - 🔥 **Slow API Detection** — Flag & log requests exceeding response time thresholds
-- 🔍 **Query Optimization** — N+1 query detection with `req.perfToolkit.trackQuery()`
-- 📊 **Real-time Dashboard** — Beautiful dark-themed dashboard at `/__perf`
-- 📝 **Structured Logging** — Per-request timing, status codes, cache status
+- 🔍 **Insights** — Automatic detection of N+1 queries, slow routes, and caching opportunities
+- 📊 **Modular Dashboard** — Multi-page real-time dashboard at `/__perf` (Overview, Routes, Insights, Logs)
+- 🔐 **Secure by Default** — Built-in dashboard authentication with session protection
+- 🧠 **Memory Efficient** — Automatic path normalization and route capping to prevent memory leaks in production
+- 📝 **Structured Logging** — Per-request timing, status codes, cache status, and optional file-based logging with rotation
 - 🎯 **Fully Typed** — Written in TypeScript with complete type definitions
 
 ---
@@ -30,106 +35,139 @@ npm install express-performance-toolkit
 ## 🚀 Quick Start
 
 ```typescript
-import express from 'express';
-import { performanceToolkit } from 'express-performance-toolkit';
+import express from "express";
+import { performanceToolkit } from "express-performance-toolkit";
 
 const app = express();
 
 const toolkit = performanceToolkit({
   cache: true,
   logSlowRequests: true,
-  dashboard: true,
+  dashboard: {
+    enabled: true,
+    auth: {
+      username: "admin",
+      password: "your-password", // Change this!
+      secret: "your-session-secret", // Change this!
+    },
+  },
+  rateLimit: {
+    enabled: true,
+    windowMs: 60000,
+    max: 100,
+  },
 });
 
 // Apply the composable middleware
 app.use(toolkit.middleware);
 
 // Mount the performance dashboard
-app.use('/__perf', toolkit.dashboardRouter);
+app.use("/__perf", toolkit.dashboardRouter);
 
-app.get('/api/users', (req, res) => {
-  res.json({ users: [{ id: 1, name: 'Alice' }] });
+app.get("/api/users", (req, res) => {
+  res.json({ users: [{ id: 1, name: "Alice" }] });
 });
 
 app.listen(3000, () => {
-  console.log('Server running on http://localhost:3000');
-  console.log('Dashboard at http://localhost:3000/__perf');
+  console.log("Server running on http://localhost:3000");
+  console.log("Dashboard at http://localhost:3000/__perf");
 });
 ```
 
 ---
 
-## ⚙️ Configuration
+## ⚙️ Configuration Properties
+
+| Option            | Type                            | Default | Description                         |
+| :---------------- | :------------------------------ | :------ | :---------------------------------- |
+| `cache`           | `boolean \| CacheOptions`       | `true`  | LRU caching configuration.          |
+| `compression`     | `boolean \| CompressionOptions` | `true`  | Response compression settings.      |
+| `logSlowRequests` | `boolean \| LoggerOptions`      | `true`  | Slow request detection & logging.   |
+| `rateLimit`       | `boolean \| RateLimitOptions`   | `false` | Smart IP-based rate limiting.       |
+| `queryHelper`     | `boolean \| QueryHelperOptions` | `true`  | N+1 query detection helper.         |
+| `dashboard`       | `boolean \| DashboardOptions`   | `true`  | Real-time modular dashboard & auth. |
+| `maxLogs`         | `number`                        | `1000`  | Max log entries to keep in memory.  |
+
+### Advanced Usage Examples
+
+#### Caching with Redis
 
 ```typescript
 const toolkit = performanceToolkit({
   // Cache — boolean or CacheOptions
   cache: {
-    ttl: 60000,           // Cache TTL in ms (default: 60000)
-    maxSize: 100,         // Max LRU entries (default: 100)
-    methods: ['GET'],     // HTTP methods to cache (default: ['GET'])
-    exclude: ['/health', /^\/admin/], // URL patterns to skip
-    redis: {              // Optional Redis adapter (requires ioredis)
-      host: 'localhost',
+    ttl: 60000, // Cache TTL in ms (default: 60000)
+    maxSize: 100, // Max LRU entries (default: 100)
+    methods: ["GET"], // HTTP methods to cache (default: ['GET'])
+    exclude: ["/health", /^\/admin/], // URL patterns to skip
+    redis: {
+      // Optional Redis adapter (requires ioredis)
+      host: "localhost",
       port: 6379,
     },
   },
 
   // Compression — boolean or CompressionOptions
   compression: {
-    threshold: 1024,      // Min response size to compress (default: 1024 bytes)
-    level: 6,             // Compression level 1-9 (default: 6)
+    threshold: 1024, // Min response size to compress (default: 1024 bytes)
+    level: 6, // Compression level 1-9 (default: 6)
   },
 
   // Logger / Slow Detection — boolean or LoggerOptions
   logSlowRequests: {
-    slowThreshold: 1000,  // Flag requests slower than this (default: 1000ms)
-    console: true,        // Log to console (default: true)
-    formatter: (entry) => `${entry.method} ${entry.path} ${entry.responseTime}ms`,
+    slowThreshold: 1000, // Flag requests slower than this (default: 1000ms)
+    console: true, // Log to console (default: true)
+    file: "logs/perf.log", // Optional: Log all requests to a file (JSON Lines format)
+    rotation: true, // Optional: Daily log rotation (e.g. perf-2023-10-27.log)
+    maxDays: 7, // Optional: Auto-delete logs older than this (requires rotation)
+    formatter: (entry) =>
+      `${entry.method} ${entry.path} ${entry.responseTime}ms`,
   },
 
   // Query Helper — boolean or QueryHelperOptions
   queryHelper: {
-    threshold: 10,        // Warn after this many queries/request (default: 10)
+    threshold: 10, // Warn after this many queries/request (default: 10)
   },
 
   // Dashboard — boolean or DashboardOptions
   dashboard: {
-    path: '/__perf',      // Dashboard mount path (default: '/__perf')
+    path: "/__perf", // Dashboard mount path (default: '/__perf')
+    auth: {
+      username: "admin",
+      password: "your-password", // Change this!
+      secret: "your-session-secret", // Change this!
+    },
   },
 
-  maxLogs: 1000,          // Max log entries in memory (default: 1000)
+  maxLogs: 1000, // Max log entries in memory (default: 1000)
 });
 ```
 
 ---
 
-## 📊 Dashboard
+## 📊 Performance Dashboard
 
-Access the performance dashboard at `http://localhost:3000/__perf`:
+Access the performance dashboard at `http://localhost:3000/__perf` (Protected with `admin`/`perf-toolkit` by default).
 
-- **Real-time stats** — Total requests, avg response time, slow request count
-- **Cache performance** — Hit/miss ratio donut chart
-- **Status code breakdown** — Visual bar chart
-- **Slowest routes** — Table of routes sorted by average response time
-- **Request log** — Filterable log with timing, cache status, and 🔥 slow flags
+The dashboard is now modular and divided into four key views:
 
-### Dashboard API
+- **🏠 Overview**: Real-time KPI grid, Event Loop lag, Heap Memory usage, and Cache efficiency.
+- **🛣️ Routes**: Per-endpoint breakdown of latency, call counts, and payload sizes.
+- **💡 Insights**: Smart recommendations for caching, N+1 query fixing, and heavy payload optimization.
+- **📋 Logs**: A live stream of request logs with 🔥 slow markers and cache status.
 
-```
-GET  /__perf              → Dashboard HTML
-GET  /__perf/api/metrics  → JSON metrics snapshot
-POST /__perf/api/reset    → Reset all metrics
-```
+### Memory Optimization
+
+The toolkit automatically **normalizes paths** (e.g., grouping `/users/1` and `/users/2` under `/users/:id`) and **caps unique routes** (max 200) to prevent memory leaks in production environments with heavy dynamic traffic.
 
 ---
 
-## 🔍 Query Tracking
+## 🔍 Smart Insights & Query Tracking
 
 Track database queries per request to detect N+1 patterns:
 
 ```typescript
-app.get('/api/posts', async (req, res) => {
+app.get("/api/posts", async (req, res) => {
   const posts = await db.getPosts();
 
   for (const post of posts) {
@@ -139,49 +177,42 @@ app.get('/api/posts', async (req, res) => {
 
   res.json(posts);
 });
-// Console: ⚠️  N+1 Alert: GET /api/posts has made 10+ queries
+// Dashboard will now show an "N+1 Query Detected" alert for this route!
 ```
 
 ---
 
 ## 🏗️ Programmatic API
 
+You can access the toolkit state programmatically:
+
 ```typescript
 const toolkit = performanceToolkit({ cache: true });
 
-// Access metrics programmatically
+// Access metrics snapshot
 const metrics = toolkit.getMetrics();
 console.log(metrics.totalRequests, metrics.avgResponseTime);
 
-// Reset metrics
-toolkit.resetMetrics();
-
 // Manual cache control
 toolkit.cache?.clear();
-toolkit.cache?.delete('GET:/api/users');
+toolkit.cache?.delete("GET /api/users");
+
+// Reset metrics
+toolkit.resetMetrics();
 ```
 
 ---
 
-## 🧪 Running Tests
+## 🧪 Testing & Development
 
 ```bash
+# Run unit & integration tests
 npm test
-```
-
----
-
-## 🏃 Running the Example
 
-```bash
-npx ts-node example/server.ts
+# Run the example server
+npm run example
 ```
 
-Then visit:
-- `http://localhost:3000/api/users` — fast, cached response
-- `http://localhost:3000/api/slow` — triggers slow request alert
-- `http://localhost:3000/__perf` — performance dashboard
-
 ---
 
 ## 📁 Project Structure
@@ -189,29 +220,41 @@ Then visit:
 ```
 express-performance-toolkit/
 ├── src/
-│   ├── index.ts              # Main entrypoint & performanceToolkit()
+│   ├── index.ts              # Entrypoint & performanceToolkit()
 │   ├── types.ts              # TypeScript interfaces
-│   ├── store.ts              # Metrics store (ring buffer + counters)
-│   ├── cache.ts              # LRU cache + Redis adapter
-│   ├── compression.ts        # Compression middleware wrapper
-│   ├── logger.ts             # Request timing & slow detection
-│   ├── queryHelper.ts        # N+1 query detection
+│   ├── store.ts              # Metrics store (Capped routes & ring buffer)
+│   ├── cache.ts              # Cache middleware + adapters
+│   ├── logger.ts             # Path normalization & request timing
+│   ├── rateLimit.ts          # Smart IP-based rate limiter
+│   ├── analyzer.ts          # Insights engine
 │   └── dashboard/
-│       ├── dashboardRouter.ts # Dashboard Express router
-│       └── dashboard.html     # Dashboard UI
-├── tests/
-│   ├── cache.test.ts
-│   ├── store.test.ts
-│   └── integration.test.ts
+│       └── dashboardRouter.ts # Web UI backend & auth
+├── dashboard-ui/             # React dashboard source
 ├── example/
-│   └── server.ts             # Example Express app
+│   └── server.ts             # Comprehensive demo server
 ├── package.json
-├── tsconfig.json
-└── jest.config.js
+└── tsconfig.json
 ```
 
 ---
 
+## 🤝 Contributing
+
+We love open source! This package is public and open for anyone to use and improve. If you have ideas for new features, performance optimizations, or bug fixes, we highly encourage you to contribute!
+
+**How to contribute:**
+
+1. Fork the repository
+2. Create a new branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes and add tests if applicable
+4. Commit your changes (`git commit -m 'Add amazing feature'`)
+5. Push to the branch (`git push origin feature/amazing-feature`)
+6. Open a Pull Request!
+
+Every contribution helps make this toolkit better for the community. Let's build something awesome together! 🚀
+
+---
+
 ## 📄 License
 
 MIT

package/dashboard-ui/README.md

@@ -0,0 +1,73 @@
+# React + TypeScript + Vite
+
+This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+
+Currently, two official plugins are available:
+
+- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs)
+- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/)
+
+## React Compiler
+
+The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+
+## Expanding the ESLint configuration
+
+If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+
+```js
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+
+      // Remove tseslint.configs.recommended and replace with this
+      tseslint.configs.recommendedTypeChecked,
+      // Alternatively, use this for stricter rules
+      tseslint.configs.strictTypeChecked,
+      // Optionally, add this for stylistic rules
+      tseslint.configs.stylisticTypeChecked,
+
+      // Other configs...
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```
+
+You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
+
+```js
+// eslint.config.js
+import reactX from 'eslint-plugin-react-x'
+import reactDom from 'eslint-plugin-react-dom'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+      // Enable lint rules for React
+      reactX.configs['recommended-typescript'],
+      // Enable lint rules for React DOM
+      reactDom.configs.recommended,
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```

package/dashboard-ui/eslint.config.js

@@ -0,0 +1,23 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+import { defineConfig, globalIgnores } from 'eslint/config'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+  },
+])

package/dashboard-ui/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Express Performance Toolkit</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>