express-performance-toolkit 1.0.0

package/src/dashboard/dashboardRouter.ts

@@ -0,0 +1,45 @@
+import { Router, Request, Response } from 'express';
+import * as path from 'path';
+import * as fs from 'fs';
+import { MetricsStore } from '../store';
+import { DashboardOptions } from '../types';
+
+/**
+ * Create the dashboard Express router.
+ * Serves the HTML dashboard and JSON metrics API.
+ */
+export function createDashboardRouter(
+  store: MetricsStore,
+  _options: DashboardOptions = {}
+): Router {
+  const router = Router();
+
+  // Cache the HTML file in memory
+  const htmlPath = path.join(__dirname, 'dashboard.html');
+  let dashboardHtml: string;
+
+  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>';
+  }
+
+  // Serve dashboard HTML
+  router.get('/', (_req: Request, res: Response) => {
+    res.set('Content-Type', 'text/html');
+    res.send(dashboardHtml);
+  });
+
+  // JSON metrics API endpoint
+  router.get('/api/metrics', (_req: Request, res: Response) => {
+    res.json(store.getMetrics());
+  });
+
+  // Reset metrics endpoint
+  router.post('/api/reset', (_req: Request, res: Response) => {
+    store.reset();
+    res.json({ success: true, message: 'Metrics reset' });
+  });
+
+  return router;
+}

package/src/index.ts

@@ -0,0 +1,141 @@
+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 {
+  ToolkitOptions,
+  CacheOptions,
+  CompressionOptions,
+  LoggerOptions,
+  QueryHelperOptions,
+  DashboardOptions,
+  Metrics,
+  CacheMiddleware,
+} from './types';
+
+export interface ToolkitInstance {
+  /** The composed Express middleware */
+  middleware: (req: Request, res: Response, next: NextFunction) => void;
+  /** The dashboard Express router — mount this if you want the dashboard */
+  dashboardRouter: Router;
+  /** Get current metrics snapshot */
+  getMetrics: () => Metrics;
+  /** Reset all metrics */
+  resetMetrics: () => void;
+  /** Access the cache middleware (for manual cache control) */
+  cache: CacheMiddleware | null;
+  /** The underlying metrics store */
+  store: MetricsStore;
+}
+
+/**
+ * ⚡ Express Performance Toolkit
+ *
+ * Creates a composable middleware stack that optimizes your Express app.
+ *
+ * @example
+ * ```ts
+ * import { performanceToolkit } from 'express-performance-toolkit';
+ *
+ * const toolkit = performanceToolkit({
+ *   cache: true,
+ *   logSlowRequests: true,
+ *   dashboard: true,
+ * });
+ *
+ * app.use(toolkit.middleware);
+ * app.use('/__perf', toolkit.dashboardRouter);
+ * ```
+ */
+export function performanceToolkit(options: ToolkitOptions = {}): ToolkitInstance {
+  const store = new MetricsStore({ maxLogs: options.maxLogs || 1000 });
+
+  const middlewares: ((req: Request, res: Response, next: NextFunction) => void)[] = [];
+  let cacheMiddlewareInstance: CacheMiddleware | null = null;
+
+  // ── Compression ──────────────────────────────────────────
+  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 });
+  if (queryConfig.enabled !== false) {
+    middlewares.push(createQueryHelperMiddleware(queryConfig));
+  }
+
+  // ── Logger (slow request detection) ──────────────────────
+  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 });
+  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);
+
+  // ── Composed Middleware ──────────────────────────────────
+  function composedMiddleware(req: Request, res: Response, next: NextFunction): void {
+    let index = 0;
+
+    function runNext(err?: unknown): void {
+      if (err) return next(err);
+      if (index >= middlewares.length) return next();
+
+      const current = middlewares[index++];
+      try {
+        current(req, res, runNext);
+      } catch (e) {
+        next(e);
+      }
+    }
+
+    runNext();
+  }
+
+  return {
+    middleware: composedMiddleware,
+    dashboardRouter,
+    getMetrics: () => store.getMetrics(),
+    resetMetrics: () => store.reset(),
+    cache: cacheMiddlewareInstance,
+    store,
+  };
+}
+
+/**
+ * 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
+): T {
+  if (value === true) return { ...defaults, enabled: true };
+  if (value === false) return { ...defaults, enabled: false };
+  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';

package/src/logger.ts

@@ -0,0 +1,83 @@
+import { Request, Response, NextFunction } from 'express';
+import onFinished from 'on-finished';
+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 status = entry.statusCode;
+  const time = `${entry.responseTime}ms`;
+
+  return `[perf] ${entry.method} ${entry.path} → ${status} ${time}${cached}${slow}`;
+}
+
+/**
+ * Create request logging & slow API detection middleware.
+ */
+export function createLoggerMiddleware(
+  options: LoggerOptions = {},
+  store: MetricsStore
+): (req: Request, res: Response, next: NextFunction) => void {
+  const {
+    slowThreshold = 1000,
+    console: logToConsole = true,
+    formatter = defaultFormatter,
+  } = options;
+
+  return (req: Request, res: Response, next: NextFunction): void => {
+    const startTime = Date.now();
+
+    // Attach perf data to request
+    if (!req.perfToolkit) {
+      req.perfToolkit = {
+        startTime,
+        queryCount: 0,
+        trackQuery: (label?: string) => {
+          req.perfToolkit!.queryCount++;
+        },
+      };
+    }
+
+    onFinished(res, (_err, finishedRes) => {
+      const responseTime = Date.now() - startTime;
+      const isSlow = responseTime >= slowThreshold;
+
+      const entry: LogEntry = {
+        method: req.method,
+        path: req.originalUrl || req.url,
+        statusCode: finishedRes.statusCode,
+        responseTime,
+        timestamp: Date.now(),
+        slow: isSlow,
+        cached: res.getHeader('X-Cache') === 'HIT',
+        queryCount: req.perfToolkit?.queryCount,
+        contentLength: parseInt(res.getHeader('content-length') as string, 10) || undefined,
+        userAgent: req.get('user-agent'),
+        ip: req.ip,
+      };
+
+      // Record in store
+      store.addLog(entry);
+
+      if (isSlow) {
+        store.recordSlowRequest();
+      }
+
+      // Console output
+      if (logToConsole) {
+        const message = formatter(entry);
+        if (isSlow) {
+          console.warn(message);
+        } else {
+          console.log(message);
+        }
+      }
+    });
+
+    next();
+  };
+}

package/src/queryHelper.ts

@@ -0,0 +1,49 @@
+import { Request, Response, NextFunction } from 'express';
+import { QueryHelperOptions } from './types';
+
+/**
+ * Create query optimization helper middleware.
+ * Tracks database queries per request and warns about potential N+1 issues.
+ */
+export function createQueryHelperMiddleware(
+  options: QueryHelperOptions = {}
+): (req: Request, res: Response, next: NextFunction) => void {
+  const { threshold = 10 } = options;
+
+  return (req: Request, _res: Response, next: NextFunction): void => {
+    const queries: { label: string; timestamp: number }[] = [];
+
+    // Initialize or extend perfToolkit on the request
+    if (!req.perfToolkit) {
+      req.perfToolkit = {
+        startTime: Date.now(),
+        queryCount: 0,
+        trackQuery: () => {},
+      };
+    }
+
+    req.perfToolkit.trackQuery = (label?: string): void => {
+      req.perfToolkit!.queryCount++;
+      queries.push({
+        label: label || `query-${req.perfToolkit!.queryCount}`,
+        timestamp: Date.now(),
+      });
+
+      // Warn if threshold exceeded
+      if (req.perfToolkit!.queryCount === threshold) {
+        console.warn(
+          `[perf] ⚠️  N+1 Alert: ${req.method} ${req.originalUrl || req.url} ` +
+            `has made ${threshold}+ queries. Consider optimizing with batch/join queries.`
+        );
+        console.warn(
+          `[perf]   Recent queries: ${queries
+            .slice(-5)
+            .map((q) => q.label)
+            .join(', ')}`
+        );
+      }
+    };
+
+    next();
+  };
+}

package/src/store.ts

@@ -0,0 +1,134 @@
+import { LogEntry, Metrics, RouteStats } from './types';
+
+/**
+ * In-memory metrics store — shared state between all middleware components.
+ * Uses a ring buffer for request logs and counters for aggregate stats.
+ */
+export class MetricsStore {
+  private maxLogs: number;
+  private logs: LogEntry[];
+  private stats: {
+    totalRequests: number;
+    totalResponseTime: number;
+    slowRequests: number;
+    cacheHits: number;
+    cacheMisses: number;
+    cacheSize: number;
+    statusCodes: Record<number, number>;
+    routes: Record<string, RouteStats>;
+    startTime: number;
+  };
+
+  constructor(options: { maxLogs?: number } = {}) {
+    this.maxLogs = options.maxLogs || 1000;
+    this.logs = [];
+    this.stats = {
+      totalRequests: 0,
+      totalResponseTime: 0,
+      slowRequests: 0,
+      cacheHits: 0,
+      cacheMisses: 0,
+      cacheSize: 0,
+      statusCodes: {},
+      routes: {},
+      startTime: Date.now(),
+    };
+  }
+
+  /** Add a request log entry to the ring buffer. */
+  addLog(entry: LogEntry): void {
+    this.logs.push({
+      ...entry,
+      timestamp: entry.timestamp || Date.now(),
+    });
+
+    // Ring buffer — drop oldest entries when full
+    if (this.logs.length > this.maxLogs) {
+      this.logs.shift();
+    }
+
+    // Update aggregate stats
+    this.stats.totalRequests++;
+    this.stats.totalResponseTime += entry.responseTime || 0;
+
+    // Track status codes
+    const code = entry.statusCode || 0;
+    this.stats.statusCodes[code] = (this.stats.statusCodes[code] || 0) + 1;
+
+    // Track per-route stats
+    const routeKey = `${entry.method} ${entry.path}`;
+    if (!this.stats.routes[routeKey]) {
+      this.stats.routes[routeKey] = {
+        count: 0,
+        totalTime: 0,
+        slowCount: 0,
+        avgTime: 0,
+      };
+    }
+    const route = this.stats.routes[routeKey];
+    route.count++;
+    route.totalTime += entry.responseTime || 0;
+    route.avgTime = Math.round(route.totalTime / route.count);
+    if (entry.slow) {
+      route.slowCount++;
+    }
+  }
+
+  recordSlowRequest(): void {
+    this.stats.slowRequests++;
+  }
+
+  recordCacheHit(): void {
+    this.stats.cacheHits++;
+  }
+
+  recordCacheMiss(): void {
+    this.stats.cacheMisses++;
+  }
+
+  setCacheSize(size: number): void {
+    this.stats.cacheSize = size;
+  }
+
+  /** Get all metrics data for the dashboard. */
+  getMetrics(): Metrics {
+    const avgResponseTime =
+      this.stats.totalRequests > 0
+        ? Math.round(this.stats.totalResponseTime / this.stats.totalRequests)
+        : 0;
+
+    const cacheTotal = this.stats.cacheHits + this.stats.cacheMisses;
+    const cacheHitRate =
+      cacheTotal > 0
+        ? Math.round((this.stats.cacheHits / cacheTotal) * 100)
+        : 0;
+
+    return {
+      uptime: Date.now() - this.stats.startTime,
+      totalRequests: this.stats.totalRequests,
+      avgResponseTime,
+      slowRequests: this.stats.slowRequests,
+      cacheHits: this.stats.cacheHits,
+      cacheMisses: this.stats.cacheMisses,
+      cacheHitRate,
+      cacheSize: this.stats.cacheSize,
+      statusCodes: { ...this.stats.statusCodes },
+      routes: { ...this.stats.routes },
+      recentLogs: this.logs.slice(-100),
+    };
+  }
+
+  /** Reset all metrics. */
+  reset(): void {
+    this.logs = [];
+    this.stats.totalRequests = 0;
+    this.stats.totalResponseTime = 0;
+    this.stats.slowRequests = 0;
+    this.stats.cacheHits = 0;
+    this.stats.cacheMisses = 0;
+    this.stats.cacheSize = 0;
+    this.stats.statusCodes = {};
+    this.stats.routes = {};
+    this.stats.startTime = Date.now();
+  }
+}

package/src/types.ts

@@ -0,0 +1,155 @@
+import { Request, Response, NextFunction } from "express";
+
+// ─── Configuration Types ────────────────────────────────────────────
+
+export interface CacheOptions {
+  /** Enable caching (default: true) */
+  enabled?: boolean;
+  /** Cache TTL in milliseconds (default: 60000) */
+  ttl?: number;
+  /** Max entries in LRU cache (default: 100) */
+  maxSize?: number;
+  /** URL patterns to exclude from caching */
+  exclude?: (string | RegExp)[];
+  /** HTTP methods to cache (default: ['GET']) */
+  methods?: string[];
+  /** Redis config — requires ioredis as peer dep */
+  redis?: RedisConfig | null;
+}
+
+export interface RedisConfig {
+  host?: string;
+  port?: number;
+  password?: string;
+  db?: number;
+  prefix?: string;
+  ttl?: number;
+  [key: string]: unknown;
+}
+
+export interface CompressionOptions {
+  /** Enable compression (default: true) */
+  enabled?: boolean;
+  /** Minimum response size to compress in bytes (default: 1024) */
+  threshold?: number;
+  /** Compression level 1-9 (default: 6) */
+  level?: number;
+}
+
+export interface LoggerOptions {
+  /** Enable request logging (default: true) */
+  enabled?: boolean;
+  /** Slow request threshold in ms (default: 1000) */
+  slowThreshold?: number;
+  /** Log to console (default: true) */
+  console?: boolean;
+  /** Custom log formatter */
+  formatter?: (entry: LogEntry) => string;
+}
+
+export interface QueryHelperOptions {
+  /** Enable query tracking (default: false) */
+  enabled?: boolean;
+  /** Warn if more than this many queries per request (default: 10) */
+  threshold?: number;
+}
+
+export interface DashboardOptions {
+  /** Enable dashboard (default: true) */
+  enabled?: boolean;
+  /** Dashboard mount path (default: '/__perf') */
+  path?: string;
+}
+
+export interface ToolkitOptions {
+  /** Cache configuration — pass true for defaults or an object to customize */
+  cache?: boolean | CacheOptions;
+  /** Compression configuration — pass true for defaults or an object */
+  compression?: boolean | CompressionOptions;
+  /** Slow request detection — pass true for defaults or an object */
+  logSlowRequests?: boolean | LoggerOptions;
+  /** Query optimization helper */
+  queryHelper?: boolean | QueryHelperOptions;
+  /** Performance dashboard */
+  dashboard?: boolean | DashboardOptions;
+  /** Max log entries to keep in memory (default: 1000) */
+  maxLogs?: number;
+}
+
+// ─── Data Types ─────────────────────────────────────────────────────
+
+export interface LogEntry {
+  method: string;
+  path: string;
+  statusCode: number;
+  responseTime: number;
+  timestamp: number;
+  slow: boolean;
+  cached: boolean;
+  queryCount?: number;
+  contentLength?: number;
+  userAgent?: string;
+  ip?: string;
+}
+
+export interface RouteStats {
+  count: number;
+  totalTime: number;
+  slowCount: number;
+  avgTime: number;
+}
+
+export interface Metrics {
+  uptime: number;
+  totalRequests: number;
+  avgResponseTime: number;
+  slowRequests: number;
+  cacheHits: number;
+  cacheMisses: number;
+  cacheHitRate: number;
+  cacheSize: number;
+  statusCodes: Record<number, number>;
+  routes: Record<string, RouteStats>;
+  recentLogs: LogEntry[];
+}
+
+export interface CacheEntry {
+  body: string | Buffer;
+  statusCode: number;
+  contentType: string | undefined;
+}
+
+export interface LRUCacheEntry<T> {
+  value: T;
+  createdAt: number;
+}
+
+export interface CacheAdapter<T = CacheEntry> {
+  get(key: string): T | null | Promise<T | null>;
+  set(key: string, value: T): void | Promise<void>;
+  has(key: string): boolean | Promise<boolean>;
+  delete(key: string): boolean | void | Promise<boolean | void>;
+  clear(): void | Promise<void>;
+  readonly size: number;
+}
+
+export interface CacheMiddleware {
+  (req: Request, res: Response, next: NextFunction): void;
+  clear: () => void | Promise<void>;
+  delete: (key: string) => boolean | void | Promise<boolean | void>;
+  adapter: CacheAdapter;
+}
+
+// ─── Express Augmentation ───────────────────────────────────────────
+
+declare global {
+  namespace Express {
+    interface Request {
+      perfToolkit?: {
+        startTime: number;
+        queryCount: number;
+        trackQuery: (label?: string) => void;
+      };
+    }
+  }
+}

package/tests/cache.test.ts

@@ -0,0 +1,76 @@
+import { LRUCache } from '../src/cache';
+
+describe('LRUCache', () => {
+  let cache: LRUCache<string>;
+
+  beforeEach(() => {
+    cache = new LRUCache<string>({ maxSize: 3, ttl: 5000 });
+  });
+
+  it('should store and retrieve values', () => {
+    cache.set('key1', 'value1');
+    expect(cache.get('key1')).toBe('value1');
+  });
+
+  it('should return null for missing keys', () => {
+    expect(cache.get('nonexistent')).toBeNull();
+  });
+
+  it('should evict oldest entry when max size is reached', () => {
+    cache.set('a', '1');
+    cache.set('b', '2');
+    cache.set('c', '3');
+    cache.set('d', '4'); // should evict 'a'
+
+    expect(cache.get('a')).toBeNull();
+    expect(cache.get('b')).toBe('2');
+    expect(cache.get('d')).toBe('4');
+    expect(cache.size).toBe(3);
+  });
+
+  it('should expire entries after TTL', () => {
+    const shortCache = new LRUCache<string>({ maxSize: 10, ttl: 50 });
+    shortCache.set('key', 'value');
+    expect(shortCache.get('key')).toBe('value');
+
+    // Fast-forward by manipulating the internal state
+    const entry = (shortCache as any).cache.get('key');
+    entry.createdAt = Date.now() - 100; // expired
+    expect(shortCache.get('key')).toBeNull();
+  });
+
+  it('should report correct size', () => {
+    expect(cache.size).toBe(0);
+    cache.set('a', '1');
+    expect(cache.size).toBe(1);
+    cache.set('b', '2');
+    expect(cache.size).toBe(2);
+  });
+
+  it('should delete entries', () => {
+    cache.set('key', 'value');
+    expect(cache.delete('key')).toBe(true);
+    expect(cache.get('key')).toBeNull();
+  });
+
+  it('should clear all entries', () => {
+    cache.set('a', '1');
+    cache.set('b', '2');
+    cache.clear();
+    expect(cache.size).toBe(0);
+  });
+
+  it('should update recently used position on get', () => {
+    cache.set('a', '1');
+    cache.set('b', '2');
+    cache.set('c', '3');
+
+    // Access 'a' to make it recently used
+    cache.get('a');
+
+    // Adding 'd' should evict 'b' (now oldest), not 'a'
+    cache.set('d', '4');
+    expect(cache.get('a')).toBe('1');
+    expect(cache.get('b')).toBeNull();
+  });
+});