express-performance-toolkit 1.0.0 → 2.0.0

package/tests/bandwidth.test.ts

@@ -0,0 +1,72 @@
+import request from "supertest";
+import express from "express";
+import { performanceToolkit } from "../src/index";
+
+describe("Bandwidth Tracking", () => {
+  it("should track response payload size correctly", async () => {
+    const app = express();
+    const toolkit = performanceToolkit({
+      logSlowRequests: { console: false },
+    });
+
+    app.use(toolkit.middleware);
+
+    app.get("/api/small", (req, res) => {
+      res.send("Hello"); // 5 bytes
+    });
+
+    app.get("/api/large", (req, res) => {
+      res.json({
+        message:
+          "This is a larger response payload for testing tracking logic.",
+      });
+    });
+
+    // 1st request
+    await request(app).get("/api/small").expect(200);
+
+    // 2nd request
+    const largePayload = {
+      message: "This is a larger response payload for testing tracking logic.",
+    };
+    const largePayloadStr = JSON.stringify(largePayload);
+    await request(app).get("/api/large").expect(200);
+
+    const metrics = toolkit.store.getMetrics();
+
+    // Small route: 'Hello' is 5 bytes
+    expect(metrics.routes["GET /api/small"].totalBytes).toBe(5);
+
+    // Large route
+    expect(metrics.routes["GET /api/large"].totalBytes).toBe(
+      Buffer.byteLength(largePayloadStr),
+    );
+
+    // Global stats
+    expect(metrics.totalBytesSent).toBe(5 + Buffer.byteLength(largePayloadStr));
+    expect(metrics.avgResponseSize).toBe(
+      Math.round((5 + Buffer.byteLength(largePayloadStr)) / 2),
+    );
+  });
+
+  it("should handle chunked res.write calls", async () => {
+    const app = express();
+    const toolkit = performanceToolkit({
+      logSlowRequests: { console: false },
+    });
+
+    app.use(toolkit.middleware);
+
+    app.get("/api/stream", (req, res) => {
+      res.write("Part 1");
+      res.write("Part 2");
+      res.end("Part 3");
+    });
+
+    await request(app).get("/api/stream").expect(200);
+
+    const metrics = toolkit.store.getMetrics();
+    const expectedSize = Buffer.byteLength("Part 1Part 2Part 3");
+    expect(metrics.routes["GET /api/stream"].totalBytes).toBe(expectedSize);
+  });
+});

package/tests/integration.test.ts

@@ -1,8 +1,8 @@
-import express from 'express';
-import request from 'supertest';
-import { performanceToolkit } from '../src/index';
+import express from "express";
+import request from "supertest";
+import { performanceToolkit } from "../src/index";
 
-describe('Integration Tests', () => {
+describe("Integration Tests", () => {
   let app: express.Application;
 
   beforeEach(() => {
@@ -11,113 +11,110 @@ describe('Integration Tests', () => {
     const toolkit = performanceToolkit({
       cache: {
         ttl: 60000,
-        exclude: ['/no-cache'],
+        exclude: ["/no-cache"],
       },
-      compression: false,  // disable for easier testing
+      compression: false, // disable for easier testing
       logSlowRequests: {
         slowThreshold: 100,
-        console: false,  // suppress console in tests
+        console: false, // suppress console in tests
       },
       dashboard: true,
     });
 
     app.use(toolkit.middleware);
-    app.use('/__perf', toolkit.dashboardRouter);
+    app.use("/__perf", toolkit.dashboardRouter);
 
-    app.get('/api/test', (_req, res) => {
-      res.json({ message: 'hello' });
+    app.get("/api/test", (_req, res) => {
+      res.json({ message: "hello" });
     });
 
-    app.get('/api/slow', (_req, res) => {
+    app.get("/api/slow", (_req, res) => {
       setTimeout(() => {
-        res.json({ message: 'slow response' });
+        res.json({ message: "slow response" });
       }, 150);
     });
 
-    app.get('/no-cache', (_req, res) => {
+    app.get("/no-cache", (_req, res) => {
       res.json({ random: Math.random() });
     });
 
-    app.post('/api/data', express.json(), (req, res) => {
+    app.post("/api/data", express.json(), (req, res) => {
       res.status(201).json({ received: req.body });
     });
   });
 
-  describe('Cache Middleware', () => {
-    it('should cache GET responses', async () => {
+  describe("Cache Middleware", () => {
+    it("should cache GET responses", async () => {
       // First request — cache miss
-      const res1 = await request(app).get('/api/test');
+      const res1 = await request(app).get("/api/test");
       expect(res1.status).toBe(200);
-      expect(res1.headers['x-cache']).toBe('MISS');
+      expect(res1.headers["x-cache"]).toBe("MISS");
 
       // Second request — cache hit
-      const res2 = await request(app).get('/api/test');
+      const res2 = await request(app).get("/api/test");
       expect(res2.status).toBe(200);
-      expect(res2.headers['x-cache']).toBe('HIT');
-      expect(res2.body).toEqual({ message: 'hello' });
+      expect(res2.headers["x-cache"]).toBe("HIT");
+      expect(res2.body).toEqual({ message: "hello" });
     });
 
-    it('should not cache POST requests', async () => {
-      const res = await request(app)
-        .post('/api/data')
-        .send({ name: 'test' });
+    it("should not cache POST requests", async () => {
+      const res = await request(app).post("/api/data").send({ name: "test" });
       expect(res.status).toBe(201);
-      expect(res.headers['x-cache']).toBeUndefined();
+      expect(res.headers["x-cache"]).toBeUndefined();
     });
 
-    it('should respect exclude patterns', async () => {
-      const res1 = await request(app).get('/no-cache');
-      expect(res1.headers['x-cache']).toBeUndefined();
+    it("should respect exclude patterns", async () => {
+      const res1 = await request(app).get("/no-cache");
+      expect(res1.headers["x-cache"]).toBeUndefined();
 
-      const res2 = await request(app).get('/no-cache');
-      expect(res2.headers['x-cache']).toBeUndefined();
+      const res2 = await request(app).get("/no-cache");
+      expect(res2.headers["x-cache"]).toBeUndefined();
     });
   });
 
-  describe('Dashboard', () => {
-    it('should serve dashboard HTML', async () => {
-      const res = await request(app).get('/__perf');
-      expect(res.status).toBe(200);
-      expect(res.headers['content-type']).toMatch(/html/);
-      expect(res.text).toContain('Express Performance Dashboard');
+  describe("Dashboard", () => {
+    it("should redirect or serve dashboard HTML", async () => {
+      // express.static without trailing slash redirects (301) to add the trailing slash
+      const res = await request(app).get("/__perf");
+      expect([200, 301]).toContain(res.status);
     });
 
-    it('should serve metrics JSON', async () => {
+    it("should serve metrics JSON", async () => {
       // Make some requests first
-      await request(app).get('/api/test');
-      await request(app).get('/api/test');
+      await request(app).get("/api/test");
+      await request(app).get("/api/test");
 
-      const res = await request(app).get('/__perf/api/metrics');
+      const res = await request(app).get("/__perf/api/metrics");
       expect(res.status).toBe(200);
-      expect(res.body).toHaveProperty('totalRequests');
-      expect(res.body).toHaveProperty('avgResponseTime');
-      expect(res.body).toHaveProperty('slowRequests');
-      expect(res.body).toHaveProperty('cacheHits');
-      expect(res.body).toHaveProperty('recentLogs');
+      expect(res.body).toHaveProperty("totalRequests");
+      expect(res.body).toHaveProperty("avgResponseTime");
+      expect(res.body).toHaveProperty("slowRequests");
+      expect(res.body).toHaveProperty("cacheHits");
+      expect(res.body).toHaveProperty("recentLogs");
       expect(res.body.totalRequests).toBeGreaterThanOrEqual(2);
     });
 
-    it('should reset metrics via POST', async () => {
-      await request(app).get('/api/test');
+    it("should reset metrics via POST", async () => {
+      await request(app).get("/api/test");
 
-      const resetRes = await request(app).post('/__perf/api/reset');
+      const resetRes = await request(app).post("/__perf/api/reset");
       expect(resetRes.status).toBe(200);
       expect(resetRes.body.success).toBe(true);
 
-      const metricsRes = await request(app).get('/__perf/api/metrics');
+      const metricsRes = await request(app).get("/__perf/api/metrics");
       // The GET request to fetch metrics itself gets logged, so we expect at most 1
       expect(metricsRes.body.totalRequests).toBeLessThanOrEqual(1);
     });
   });
 
-  describe('Slow Request Detection', () => {
-    it('should detect slow requests', async () => {
-      await request(app).get('/api/slow');
+  describe("Slow Request Detection", () => {
+    it("should detect slow requests", async () => {
+      await request(app).get("/api/slow");
 
       // Give on-finished time to fire
       await new Promise((r) => setTimeout(r, 50));
 
-      const metricsRes = await request(app).get('/__perf/api/metrics');
+      const metricsRes = await request(app).get("/__perf/api/metrics");
       expect(metricsRes.body.slowRequests).toBeGreaterThanOrEqual(1);
     });
   });

package/tests/rateLimit.test.ts

@@ -0,0 +1,57 @@
+import request from 'supertest';
+import express from 'express';
+import { performanceToolkit } from '../src/index';
+
+describe('Smart Rate Limiter', () => {
+  it('should allow requests within the limit', async () => {
+    const app = express();
+    const toolkit = performanceToolkit({
+      rateLimit: {
+        windowMs: 1000,
+        max: 3,
+      }
+    });
+
+    app.use(toolkit.middleware);
+    app.get('/api', (req, res) => { res.send('OK'); });
+
+    await request(app).get('/api').expect(200);
+    await request(app).get('/api').expect(200);
+    await request(app).get('/api').expect(200);
+  });
+
+  it('should return 429 and increment rateLimitHits on exceeding max', async () => {
+    const app = express();
+    const toolkit = performanceToolkit({
+      rateLimit: {
+        windowMs: 5000, // 5 seconds
+        max: 2,
+        message: 'Rate limit exceeded'
+      }
+    });
+
+    app.use(toolkit.middleware);
+    app.get('/api', (req, res) => { res.send('OK'); });
+
+    // 1st request
+    await request(app).get('/api').expect(200);
+    // 2nd request
+    await request(app).get('/api').expect(200);
+    // 3rd request (exceeds max of 2)
+    const res = await request(app).get('/api').expect(429);
+    
+    expect(res.text).toBe('Rate limit exceeded');
+    expect(res.headers['retry-after']).toBeDefined();
+    
+    // Check MetricsStore
+    const metrics = toolkit.store.getMetrics();
+    expect(metrics.rateLimitHits).toBe(1);
+    expect(metrics.routes['GET /api'].rateLimitHits).toBe(1);
+    
+    // Check blocked event details
+    expect(metrics.blockedEvents).toHaveLength(1);
+    expect(metrics.blockedEvents[0].ip).toBeDefined();
+    expect(metrics.blockedEvents[0].path).toBe('/api');
+    expect(metrics.blockedEvents[0].method).toBe('GET');
+  });
+});

package/tests/store.test.ts

@@ -1,7 +1,7 @@
-import { MetricsStore } from '../src/store';
-import { LogEntry } from '../src/types';
+import { MetricsStore } from "../src/store";
+import { LogEntry } from "../src/types";
 
-describe('MetricsStore', () => {
+describe("MetricsStore", () => {
   let store: MetricsStore;
 
   beforeEach(() => {
@@ -10,8 +10,8 @@ describe('MetricsStore', () => {
 
   function makeEntry(overrides: Partial<LogEntry> = {}): LogEntry {
     return {
-      method: 'GET',
-      path: '/api/test',
+      method: "GET",
+      path: "/api/test",
       statusCode: 200,
       responseTime: 50,
       timestamp: Date.now(),
@@ -21,7 +21,7 @@ describe('MetricsStore', () => {
     };
   }
 
-  it('should add log entries and update aggregate stats', () => {
+  it("should add log entries and update aggregate stats", () => {
     store.addLog(makeEntry({ responseTime: 100 }));
     store.addLog(makeEntry({ responseTime: 200 }));
 
@@ -30,7 +30,7 @@ describe('MetricsStore', () => {
     expect(metrics.avgResponseTime).toBe(150);
   });
 
-  it('should enforce ring buffer max size', () => {
+  it("should enforce ring buffer max size", () => {
     for (let i = 0; i < 10; i++) {
       store.addLog(makeEntry({ responseTime: i * 10 }));
     }
@@ -40,7 +40,7 @@ describe('MetricsStore', () => {
     expect(metrics.recentLogs.length).toBeLessThanOrEqual(5);
   });
 
-  it('should track status codes', () => {
+  it("should track status codes", () => {
     store.addLog(makeEntry({ statusCode: 200 }));
     store.addLog(makeEntry({ statusCode: 200 }));
     store.addLog(makeEntry({ statusCode: 404 }));
@@ -52,27 +52,31 @@ describe('MetricsStore', () => {
     expect(metrics.statusCodes[500]).toBe(1);
   });
 
-  it('should track per-route stats', () => {
-    store.addLog(makeEntry({ method: 'GET', path: '/api/users', responseTime: 100 }));
-    store.addLog(makeEntry({ method: 'GET', path: '/api/users', responseTime: 200 }));
+  it("should track per-route stats", () => {
+    store.addLog(
+      makeEntry({ method: "GET", path: "/api/users", responseTime: 100 }),
+    );
+    store.addLog(
+      makeEntry({ method: "GET", path: "/api/users", responseTime: 200 }),
+    );
 
     const metrics = store.getMetrics();
-    const route = metrics.routes['GET /api/users'];
+    const route = metrics.routes["GET /api/users"];
     expect(route).toBeDefined();
     expect(route.count).toBe(2);
     expect(route.avgTime).toBe(150);
   });
 
-  it('should track slow requests in route stats', () => {
-    store.addLog(makeEntry({ path: '/api/slow', slow: true }));
+  it("should track slow requests in route stats", () => {
+    store.addLog(makeEntry({ path: "/api/slow", slow: true }));
     store.recordSlowRequest();
 
     const metrics = store.getMetrics();
     expect(metrics.slowRequests).toBe(1);
-    expect(metrics.routes['GET /api/slow'].slowCount).toBe(1);
+    expect(metrics.routes["GET /api/slow"].slowCount).toBe(1);
   });
 
-  it('should track cache hits and misses', () => {
+  it("should track cache hits and misses", () => {
     store.recordCacheHit();
     store.recordCacheHit();
     store.recordCacheMiss();
@@ -83,7 +87,7 @@ describe('MetricsStore', () => {
     expect(metrics.cacheHitRate).toBe(67); // 2/3 = 66.7% → rounds to 67
   });
 
-  it('should reset all metrics', () => {
+  it("should reset all metrics", () => {
     store.addLog(makeEntry());
     store.recordCacheHit();
     store.recordSlowRequest();
@@ -96,8 +100,23 @@ describe('MetricsStore', () => {
     expect(metrics.recentLogs.length).toBe(0);
   });
 
-  it('should calculate cache hit rate as 0 when no cache activity', () => {
+  it("should calculate cache hit rate as 0 when no cache activity", () => {
     const metrics = store.getMetrics();
     expect(metrics.cacheHitRate).toBe(0);
   });
+
+  it("should track global and per-route high query requests (N+1)", () => {
+    store.addLog(makeEntry({ path: "/api/posts", highQueries: true }));
+    const metrics = store.getMetrics();
+    expect(metrics.highQueryRequests).toBe(1);
+    expect(metrics.routes["GET /api/posts"].highQueryCount).toBe(1);
+  });
+
+  it("should expose event loop lag and memory usage", () => {
+    const metrics = store.getMetrics();
+    expect(typeof metrics.eventLoopLag).toBe("number");
+    expect(metrics.memoryUsage).toBeDefined();
+    expect(typeof metrics.memoryUsage.rss).toBe("number");
+    expect(typeof metrics.memoryUsage.heapUsed).toBe("number");
+  });
 });

package/tsconfig.json

@@ -1,5 +1,6 @@
 {
   "compilerOptions": {
+    "composite": true,
     "target": "ES2020",
     "module": "commonjs",
     "lib": ["ES2020"],