express-performance-toolkit 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,135 @@
+import { Request, Response, NextFunction } from "express";
+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;
+}
+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;
+}
+declare global {
+    namespace Express {
+        interface Request {
+            perfToolkit?: {
+                startTime: number;
+                queryCount: number;
+                trackQuery: (label?: string) => void;
+            };
+        }
+    }
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/example/server.ts

@@ -0,0 +1,126 @@
+import express, { Request, Response } from 'express';
+import { performanceToolkit } from '../src/index';
+
+const app = express();
+const PORT = 3000;
+
+// ── Initialize Performance Toolkit ──────────────────────────
+const toolkit = performanceToolkit({
+  cache: {
+    ttl: 30000,       // 30s cache TTL
+    maxSize: 50,
+    exclude: ['/api/random', '/__perf'],
+  },
+  compression: true,
+  logSlowRequests: {
+    slowThreshold: 500,  // Flag requests > 500ms as slow
+    console: true,
+  },
+  queryHelper: {
+    threshold: 5,
+  },
+  dashboard: true,
+});
+
+// Apply the middleware
+app.use(toolkit.middleware);
+
+// Mount the dashboard
+app.use('/__perf', toolkit.dashboardRouter);
+
+// ── Sample API Routes ───────────────────────────────────────
+
+// Fast route — should be cached after first hit
+app.get('/api/users', (_req: Request, res: Response) => {
+  const users = [
+    { id: 1, name: 'Alice Johnson', email: 'alice@example.com', role: 'admin' },
+    { id: 2, name: 'Bob Smith', email: 'bob@example.com', role: 'user' },
+    { id: 3, name: 'Charlie Brown', email: 'charlie@example.com', role: 'user' },
+    { id: 4, name: 'Diana Prince', email: 'diana@example.com', role: 'moderator' },
+    { id: 5, name: 'Eve Wilson', email: 'eve@example.com', role: 'user' },
+  ];
+  res.json({ users, count: users.length });
+});
+
+// Slow route — simulates a 1.5s delay (triggers slow detection)
+app.get('/api/slow', (_req: Request, res: Response) => {
+  setTimeout(() => {
+    res.json({
+      message: 'This response was intentionally delayed',
+      processingTime: '1500ms',
+    });
+  }, 1500);
+});
+
+// Medium-speed route
+app.get('/api/products', (_req: Request, res: Response) => {
+  setTimeout(() => {
+    res.json({
+      products: [
+        { id: 1, name: 'Laptop Pro', price: 1299.99, stock: 25 },
+        { id: 2, name: 'Wireless Mouse', price: 29.99, stock: 150 },
+        { id: 3, name: 'USB-C Hub', price: 49.99, stock: 75 },
+      ],
+    });
+  }, 300);
+});
+
+// Random data — excluded from cache
+app.get('/api/random', (_req: Request, res: Response) => {
+  res.json({
+    value: Math.random(),
+    timestamp: Date.now(),
+  });
+});
+
+// Route demonstrating query tracking
+app.get('/api/posts', (req: Request, res: Response) => {
+  // Simulate multiple DB queries (potential N+1)
+  const posts = [];
+  for (let i = 0; i < 12; i++) {
+    req.perfToolkit?.trackQuery(`SELECT * FROM comments WHERE post_id=${i}`);
+    posts.push({
+      id: i,
+      title: `Post ${i}`,
+      commentCount: Math.floor(Math.random() * 20),
+    });
+  }
+  res.json({ posts });
+});
+
+// POST route — not cached
+app.post('/api/users', express.json(), (req: Request, res: Response) => {
+  res.status(201).json({
+    message: 'User created',
+    user: req.body,
+  });
+});
+
+// Error route
+app.get('/api/error', (_req: Request, _res: Response) => {
+  throw new Error('Something went wrong!');
+});
+
+// Error handler
+app.use((err: Error, _req: Request, res: Response, _next: express.NextFunction) => {
+  console.error(err.stack);
+  res.status(500).json({ error: err.message });
+});
+
+// ── Start Server ────────────────────────────────────────────
+app.listen(PORT, () => {
+  console.log('');
+  console.log('  ⚡ Express Performance Toolkit — Example Server');
+  console.log('  ────────────────────────────────────────────────');
+  console.log(`  🚀 Server:    http://localhost:${PORT}`);
+  console.log(`  📊 Dashboard: http://localhost:${PORT}/__perf`);
+  console.log('');
+  console.log('  Try these endpoints:');
+  console.log(`    GET  http://localhost:${PORT}/api/users     (fast, cached)`);
+  console.log(`    GET  http://localhost:${PORT}/api/slow      (slow, triggers alert)`);
+  console.log(`    GET  http://localhost:${PORT}/api/products  (medium speed)`);
+  console.log(`    GET  http://localhost:${PORT}/api/random    (not cached)`);
+  console.log(`    GET  http://localhost:${PORT}/api/posts     (N+1 query warning)`);
+  console.log(`    POST http://localhost:${PORT}/api/users     (not cached)`);
+  console.log('');
+});

package/example/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "moduleResolution": "node",
+    "outDir": "./dist",
+    "rootDir": "."
+  },
+  "include": ["server.ts"],
+  "references": [{ "path": ".." }]
+}

package/jest.config.js

@@ -0,0 +1,10 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/tests'],
+  testMatch: ['**/*.test.ts'],
+  moduleFileExtensions: ['ts', 'js', 'json'],
+  collectCoverageFrom: ['src/**/*.ts', '!src/dashboard/dashboard.html'],
+  coverageDirectory: 'coverage',
+};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "express-performance-toolkit",
+  "version": "1.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",
+    "postbuild": "npm run copy-assets",
+    "copy-assets": "mkdir -p dist/dashboard && cp src/dashboard/dashboard.html dist/dashboard/",
+    "dev": "tsc --watch",
+    "test": "jest --verbose",
+    "example": "ts-node example/server.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "express",
+    "performance",
+    "middleware",
+    "caching",
+    "compression",
+    "monitoring",
+    "dashboard",
+    "slow-api",
+    "optimization",
+    "logging",
+    "typescript"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "compression": "^1.7.4",
+    "on-finished": "^2.4.1"
+  },
+  "peerDependencies": {
+    "express": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ioredis": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/compression": "^1.7.5",
+    "@types/express": "^4.17.21",
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.11.0",
+    "@types/on-finished": "^2.3.4",
+    "@types/supertest": "^7.2.0",
+    "express": "^4.21.0",
+    "jest": "^29.7.0",
+    "supertest": "^6.3.3",
+    "ts-jest": "^29.1.2",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.3"
+  }
+}

package/src/cache.ts

@@ -0,0 +1,228 @@
+import { Request, Response, NextFunction } from "express";
+import {
+  CacheOptions,
+  CacheEntry,
+  CacheAdapter,
+  LRUCacheEntry,
+  CacheMiddleware,
+} from "./types";
+import { MetricsStore } from "./store";
+
+/**
+ * In-memory LRU cache with TTL support.
+ */
+export class LRUCache<T = CacheEntry> implements CacheAdapter<T> {
+  private maxSize: number;
+  private ttl: number;
+  private cache: Map<string, LRUCacheEntry<T>>;
+
+  constructor(options: { maxSize?: number; ttl?: number } = {}) {
+    this.maxSize = options.maxSize || 100;
+    this.ttl = options.ttl || 60000;
+    this.cache = new Map();
+  }
+
+  get(key: string): T | null {
+    const entry = this.cache.get(key);
+    if (!entry) return null;
+
+    // Check TTL
+    if (Date.now() - entry.createdAt > this.ttl) {
+      this.cache.delete(key);
+      return null;
+    }
+
+    // Move to end (most recently used)
+    this.cache.delete(key);
+    this.cache.set(key, entry);
+    return entry.value;
+  }
+
+  set(key: string, value: T): void {
+    // Remove oldest if at capacity
+    if (this.cache.size >= this.maxSize && !this.cache.has(key)) {
+      const firstKey = this.cache.keys().next().value;
+      if (firstKey !== undefined) {
+        this.cache.delete(firstKey);
+      }
+    }
+
+    this.cache.set(key, {
+      value,
+      createdAt: Date.now(),
+    });
+  }
+
+  has(key: string): boolean {
+    return this.get(key) !== null;
+  }
+
+  delete(key: string): boolean {
+    return this.cache.delete(key);
+  }
+
+  clear(): void {
+    this.cache.clear();
+  }
+
+  get size(): number {
+    return this.cache.size;
+  }
+}
+
+/**
+ * Create a Redis cache adapter (requires ioredis as peer dependency).
+ */
+function createRedisAdapter(
+  redisConfig: Record<string, unknown>,
+): CacheAdapter | null {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const Redis = require("ioredis");
+    const client = new Redis(redisConfig);
+    const prefix = (redisConfig.prefix as string) || "ept:";
+    const ttl = (redisConfig.ttl as number) || 60;
+
+    return {
+      async get(key: string): Promise<CacheEntry | null> {
+        const data = await client.get(`${prefix}${key}`);
+        return data ? JSON.parse(data) : null;
+      },
+      async set(key: string, value: CacheEntry): Promise<void> {
+        await client.setex(`${prefix}${key}`, ttl, JSON.stringify(value));
+      },
+      async has(key: string): Promise<boolean> {
+        return (await client.exists(`${prefix}${key}`)) === 1;
+      },
+      async delete(key: string): Promise<void> {
+        await client.del(`${prefix}${key}`);
+      },
+      async clear(): Promise<void> {
+        const keys = await client.keys(`${prefix}*`);
+        if (keys.length > 0) await client.del(...keys);
+      },
+      get size(): number {
+        return -1; // Cannot easily get size from Redis
+      },
+    };
+  } catch {
+    console.warn(
+      "[express-performance-toolkit] ioredis not installed. Falling back to in-memory cache.",
+    );
+    return null;
+  }
+}
+
+/**
+ * Create cache middleware.
+ */
+export function createCacheMiddleware(
+  options: CacheOptions = {},
+  store?: MetricsStore,
+): CacheMiddleware {
+  const {
+    ttl = 60000,
+    maxSize = 100,
+    exclude = [],
+    redis = null,
+    methods = ["GET"],
+  } = options;
+
+  let cacheAdapter: CacheAdapter;
+
+  if (redis) {
+    const redisAdapter = createRedisAdapter({
+      ...redis,
+      ttl: Math.ceil(ttl / 1000),
+    });
+    cacheAdapter = redisAdapter || new LRUCache({ maxSize, ttl });
+  } else {
+    cacheAdapter = new LRUCache({ maxSize, ttl });
+  }
+
+  function shouldExclude(url: string): boolean {
+    return exclude.some((pattern) => {
+      if (pattern instanceof RegExp) return pattern.test(url);
+      return url.includes(pattern);
+    });
+  }
+
+  function getCacheKey(req: Request): string {
+    return `${req.method}:${req.originalUrl || req.url}`;
+  }
+
+  const handler = async (
+    req: Request,
+    res: Response,
+    next: NextFunction,
+  ): Promise<void> => {
+    // Only cache specified methods
+    if (!methods.includes(req.method)) {
+      return next();
+    }
+
+    // Check exclusion patterns
+    const url = req.originalUrl || req.url;
+    if (shouldExclude(url)) {
+      return next();
+    }
+
+    const key = getCacheKey(req);
+
+    try {
+      const cached = await cacheAdapter.get(key);
+      if (cached) {
+        if (store) store.recordCacheHit();
+        const entry = cached as CacheEntry;
+
+        res.set("X-Cache", "HIT");
+        res.set("Content-Type", entry.contentType || "application/json");
+        res.status(entry.statusCode || 200).send(entry.body);
+        return;
+      }
+    } catch {
+      // Cache read failed — continue to handler
+    }
+
+    if (store) store.recordCacheMiss();
+    res.set("X-Cache", "MISS");
+
+    // Intercept response to cache it
+    const originalSend = res.send.bind(res);
+    res.send = function (body: unknown): Response {
+      // Only cache successful responses
+      if (res.statusCode >= 200 && res.statusCode < 400) {
+        const entry: CacheEntry = {
+          body: body as string | Buffer,
+          statusCode: res.statusCode,
+          contentType: res.get("Content-Type"),
+        };
+
+        try {
+          cacheAdapter.set(key, entry);
+          if (
+            store &&
+            typeof cacheAdapter.size === "number" &&
+            cacheAdapter.size >= 0
+          ) {
+            store.setCacheSize(cacheAdapter.size);
+          }
+        } catch {
+          // Cache write failed — ignore
+        }
+      }
+
+      return originalSend(body);
+    };
+
+    next();
+  };
+
+  // Build the CacheMiddleware with attached control methods
+  const middleware = handler as unknown as CacheMiddleware;
+  middleware.clear = () => cacheAdapter.clear();
+  middleware.delete = (key: string) => cacheAdapter.delete(key);
+  middleware.adapter = cacheAdapter;
+
+  return middleware;
+}

package/src/compression.ts

@@ -0,0 +1,25 @@
+import { Request, Response, NextFunction } from 'express';
+import compressionMiddleware from 'compression';
+import { CompressionOptions } from './types';
+
+/**
+ * Create compression middleware with sensible defaults.
+ */
+export function createCompressionMiddleware(
+  options: CompressionOptions = {}
+): (req: Request, res: Response, next: NextFunction) => void {
+  const { threshold = 1024, level = 6 } = options;
+
+  return compressionMiddleware({
+    threshold,
+    level,
+    filter: (req: Request, res: Response): boolean => {
+      // Don't compress if the client didn't request it
+      if (req.headers['x-no-compression']) {
+        return false;
+      }
+      // Use compression's default filter
+      return compressionMiddleware.filter(req, res);
+    },
+  });
+}