express-performance-toolkit 1.0.0

package/tests/integration.test.ts

@@ -0,0 +1,124 @@
+import express from 'express';
+import request from 'supertest';
+import { performanceToolkit } from '../src/index';
+
+describe('Integration Tests', () => {
+  let app: express.Application;
+
+  beforeEach(() => {
+    app = express();
+
+    const toolkit = performanceToolkit({
+      cache: {
+        ttl: 60000,
+        exclude: ['/no-cache'],
+      },
+      compression: false,  // disable for easier testing
+      logSlowRequests: {
+        slowThreshold: 100,
+        console: false,  // suppress console in tests
+      },
+      dashboard: true,
+    });
+
+    app.use(toolkit.middleware);
+    app.use('/__perf', toolkit.dashboardRouter);
+
+    app.get('/api/test', (_req, res) => {
+      res.json({ message: 'hello' });
+    });
+
+    app.get('/api/slow', (_req, res) => {
+      setTimeout(() => {
+        res.json({ message: 'slow response' });
+      }, 150);
+    });
+
+    app.get('/no-cache', (_req, res) => {
+      res.json({ random: Math.random() });
+    });
+
+    app.post('/api/data', express.json(), (req, res) => {
+      res.status(201).json({ received: req.body });
+    });
+  });
+
+  describe('Cache Middleware', () => {
+    it('should cache GET responses', async () => {
+      // First request — cache miss
+      const res1 = await request(app).get('/api/test');
+      expect(res1.status).toBe(200);
+      expect(res1.headers['x-cache']).toBe('MISS');
+
+      // Second request — cache hit
+      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' });
+    });
+
+    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();
+    });
+
+    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();
+    });
+  });
+
+  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');
+    });
+
+    it('should serve metrics JSON', async () => {
+      // Make some requests first
+      await request(app).get('/api/test');
+      await request(app).get('/api/test');
+
+      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.totalRequests).toBeGreaterThanOrEqual(2);
+    });
+
+    it('should reset metrics via POST', async () => {
+      await request(app).get('/api/test');
+
+      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');
+      // 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');
+
+      // Give on-finished time to fire
+      await new Promise((r) => setTimeout(r, 50));
+
+      const metricsRes = await request(app).get('/__perf/api/metrics');
+      expect(metricsRes.body.slowRequests).toBeGreaterThanOrEqual(1);
+    });
+  });
+});

package/tests/store.test.ts

@@ -0,0 +1,103 @@
+import { MetricsStore } from '../src/store';
+import { LogEntry } from '../src/types';
+
+describe('MetricsStore', () => {
+  let store: MetricsStore;
+
+  beforeEach(() => {
+    store = new MetricsStore({ maxLogs: 5 });
+  });
+
+  function makeEntry(overrides: Partial<LogEntry> = {}): LogEntry {
+    return {
+      method: 'GET',
+      path: '/api/test',
+      statusCode: 200,
+      responseTime: 50,
+      timestamp: Date.now(),
+      slow: false,
+      cached: false,
+      ...overrides,
+    };
+  }
+
+  it('should add log entries and update aggregate stats', () => {
+    store.addLog(makeEntry({ responseTime: 100 }));
+    store.addLog(makeEntry({ responseTime: 200 }));
+
+    const metrics = store.getMetrics();
+    expect(metrics.totalRequests).toBe(2);
+    expect(metrics.avgResponseTime).toBe(150);
+  });
+
+  it('should enforce ring buffer max size', () => {
+    for (let i = 0; i < 10; i++) {
+      store.addLog(makeEntry({ responseTime: i * 10 }));
+    }
+    const metrics = store.getMetrics();
+    expect(metrics.totalRequests).toBe(10);
+    // Ring buffer should only keep last 5
+    expect(metrics.recentLogs.length).toBeLessThanOrEqual(5);
+  });
+
+  it('should track status codes', () => {
+    store.addLog(makeEntry({ statusCode: 200 }));
+    store.addLog(makeEntry({ statusCode: 200 }));
+    store.addLog(makeEntry({ statusCode: 404 }));
+    store.addLog(makeEntry({ statusCode: 500 }));
+
+    const metrics = store.getMetrics();
+    expect(metrics.statusCodes[200]).toBe(2);
+    expect(metrics.statusCodes[404]).toBe(1);
+    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 }));
+
+    const metrics = store.getMetrics();
+    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 }));
+    store.recordSlowRequest();
+
+    const metrics = store.getMetrics();
+    expect(metrics.slowRequests).toBe(1);
+    expect(metrics.routes['GET /api/slow'].slowCount).toBe(1);
+  });
+
+  it('should track cache hits and misses', () => {
+    store.recordCacheHit();
+    store.recordCacheHit();
+    store.recordCacheMiss();
+
+    const metrics = store.getMetrics();
+    expect(metrics.cacheHits).toBe(2);
+    expect(metrics.cacheMisses).toBe(1);
+    expect(metrics.cacheHitRate).toBe(67); // 2/3 = 66.7% → rounds to 67
+  });
+
+  it('should reset all metrics', () => {
+    store.addLog(makeEntry());
+    store.recordCacheHit();
+    store.recordSlowRequest();
+    store.reset();
+
+    const metrics = store.getMetrics();
+    expect(metrics.totalRequests).toBe(0);
+    expect(metrics.cacheHits).toBe(0);
+    expect(metrics.slowRequests).toBe(0);
+    expect(metrics.recentLogs.length).toBe(0);
+  });
+
+  it('should calculate cache hit rate as 0 when no cache activity', () => {
+    const metrics = store.getMetrics();
+    expect(metrics.cacheHitRate).toBe(0);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "moduleResolution": "node",
+    "removeComments": false
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests", "example"]
+}