@expressots/core 3.0.0 → 4.0.0-preview.1

package/lib/esm/middleware/middleware-presets.js

@@ -0,0 +1,286 @@
+/**
+ * Default CORS options for API preset.
+ */
+const API_CORS_OPTIONS = {
+    origin: true,
+    credentials: true,
+    methods: ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
+    allowedHeaders: ["Content-Type", "Authorization", "X-Requested-With"],
+};
+/**
+ * Default Helmet options for secure preset.
+ */
+const SECURE_HELMET_OPTIONS = {
+    contentSecurityPolicy: {
+        directives: {
+            "default-src": ["'self'"],
+            "style-src": ["'self'", "'unsafe-inline'"],
+            "script-src": ["'self'"],
+            "img-src": ["'self'", "data:", "https:"],
+        },
+    },
+    crossOriginEmbedderPolicy: { policy: "require-corp" },
+    crossOriginOpenerPolicy: { policy: "same-origin" },
+    crossOriginResourcePolicy: { policy: "same-origin" },
+    xDnsPrefetchControl: { allow: false },
+    xFrameOptions: { action: "deny" },
+    strictTransportSecurity: {
+        maxAge: 31536000,
+        includeSubDomains: true,
+        preload: true,
+    },
+    xDownloadOptions: "noopen",
+    xContentTypeOptions: "nosniff",
+    xPermittedCrossDomainPolicies: { permittedPolicies: "none" },
+    referrerPolicy: { policy: "strict-origin-when-cross-origin" },
+};
+/**
+ * Default rate limit options.
+ */
+const DEFAULT_RATE_LIMIT_OPTIONS = {
+    windowMs: 60 * 1000, // 1 minute
+    limit: 100, // 100 requests per minute
+    standardHeaders: "draft-7",
+    legacyHeaders: false,
+};
+/**
+ * Strict rate limit for production.
+ */
+const PRODUCTION_RATE_LIMIT_OPTIONS = {
+    windowMs: 60 * 1000,
+    limit: 60,
+    standardHeaders: "draft-7",
+    legacyHeaders: false,
+    skipSuccessfulRequests: false,
+};
+/**
+ * Built-in middleware presets.
+ * @public API
+ */
+export const MIDDLEWARE_PRESETS = {
+    /**
+     * API Preset - Optimized for REST APIs
+     * Includes: CORS, Helmet, JSON parser, URL-encoded parser, Compression, Rate limiting
+     */
+    api: {
+        name: "api",
+        description: "Optimized configuration for REST APIs with security and performance",
+        tags: ["rest", "backend", "security"],
+        middleware: [
+            { name: "Cors", options: API_CORS_OPTIONS },
+            { name: "Helmet", options: {} },
+            { name: "BodyParser", options: { limit: "10mb" } },
+            {
+                name: "UrlEncodedParser",
+                options: { extended: true },
+            },
+            { name: "Compression", options: { level: 6 } },
+            { name: "RateLimiter", options: DEFAULT_RATE_LIMIT_OPTIONS },
+        ],
+    },
+    /**
+     * Web Preset - For traditional web applications
+     * Includes: Session, Cookie parser, Static files, CORS, Helmet
+     */
+    web: {
+        name: "web",
+        description: "Configuration for traditional web applications with sessions",
+        tags: ["web", "frontend", "session"],
+        middleware: [
+            { name: "Cors", options: { origin: true } },
+            { name: "Helmet", options: {} },
+            { name: "BodyParser", options: { limit: "5mb" } },
+            {
+                name: "UrlEncodedParser",
+                options: { extended: true },
+            },
+            { name: "CookieParser", options: undefined, optional: true },
+            { name: "Compression", options: {} },
+        ],
+    },
+    /**
+     * Microservice Preset - Lightweight for service-to-service communication
+     * Minimal middleware for maximum performance
+     */
+    microservice: {
+        name: "microservice",
+        description: "Lightweight configuration for microservices",
+        tags: ["microservice", "performance", "minimal"],
+        middleware: [
+            { name: "BodyParser", options: { limit: "1mb" } },
+            { name: "Compression", options: { level: 6 } },
+        ],
+    },
+    /**
+     * GraphQL Preset - Optimized for GraphQL APIs
+     */
+    graphql: {
+        name: "graphql",
+        description: "Optimized for GraphQL API servers",
+        tags: ["graphql", "api"],
+        middleware: [
+            {
+                name: "Cors",
+                options: {
+                    origin: true,
+                    methods: ["GET", "POST", "OPTIONS"],
+                },
+            },
+            { name: "BodyParser", options: { limit: "50mb" } },
+            { name: "Compression", options: {} },
+        ],
+    },
+    /**
+     * Minimal Preset - Absolute minimum for simple apps
+     */
+    minimal: {
+        name: "minimal",
+        description: "Minimal configuration with just body parsing",
+        tags: ["minimal", "simple"],
+        middleware: [
+            { name: "BodyParser", options: {} },
+            {
+                name: "UrlEncodedParser",
+                options: { extended: false },
+            },
+        ],
+    },
+    /**
+     * Secure Preset - Maximum security configuration
+     */
+    secure: {
+        name: "secure",
+        description: "Maximum security configuration for sensitive applications",
+        tags: ["security", "production", "hardened"],
+        middleware: [
+            { name: "Helmet", options: SECURE_HELMET_OPTIONS },
+            {
+                name: "Cors",
+                options: {
+                    origin: false, // Must be explicitly configured
+                    credentials: true,
+                },
+            },
+            { name: "RateLimiter", options: PRODUCTION_RATE_LIMIT_OPTIONS },
+            { name: "BodyParser", options: { limit: "1mb" } },
+            {
+                name: "UrlEncodedParser",
+                options: { extended: false, limit: "1mb" },
+            },
+        ],
+    },
+    /**
+     * Development Preset - Verbose logging and relaxed security
+     */
+    development: {
+        name: "development",
+        description: "Development-friendly with logging and relaxed security",
+        tags: ["development", "debug", "logging"],
+        middleware: [
+            { name: "Cors", options: { origin: true } },
+            { name: "BodyParser", options: { limit: "50mb" } },
+            {
+                name: "UrlEncodedParser",
+                options: { extended: true },
+            },
+            {
+                name: "Morgan",
+                options: "dev",
+                optional: true,
+            },
+            { name: "Compression", options: {}, optional: true },
+        ],
+    },
+    /**
+     * Production Preset - Optimized for production deployment
+     */
+    production: {
+        name: "production",
+        description: "Production-optimized with security and performance",
+        tags: ["production", "performance", "security"],
+        middleware: [
+            { name: "Helmet", options: {} },
+            { name: "Cors", options: API_CORS_OPTIONS },
+            { name: "RateLimiter", options: PRODUCTION_RATE_LIMIT_OPTIONS },
+            {
+                name: "Compression",
+                options: { level: 6, threshold: 1024 },
+            },
+            { name: "BodyParser", options: { limit: "10mb" } },
+            {
+                name: "UrlEncodedParser",
+                options: { extended: true },
+            },
+        ],
+    },
+};
+/**
+ * Get a preset by name.
+ *
+ * @param name - The preset name
+ * @returns The preset configuration or undefined
+ * @public API
+ */
+export function getPreset(name) {
+    return MIDDLEWARE_PRESETS[name];
+}
+/**
+ * Get all available preset names.
+ *
+ * @returns Array of preset names
+ * @public API
+ */
+export function getPresetNames() {
+    return Object.keys(MIDDLEWARE_PRESETS);
+}
+/**
+ * Get presets by tag.
+ *
+ * @param tag - The tag to filter by
+ * @returns Array of matching presets
+ * @public API
+ */
+export function getPresetsByTag(tag) {
+    return Object.values(MIDDLEWARE_PRESETS).filter((preset) => preset.tags?.includes(tag));
+}
+/**
+ * Create a custom preset.
+ *
+ * @param config - The preset configuration
+ * @returns The created preset
+ * @public API
+ */
+export function createPreset(config) {
+    return config;
+}
+/**
+ * Merge two presets, with the second overriding the first.
+ *
+ * @param base - The base preset
+ * @param override - The overriding preset
+ * @returns Merged preset
+ * @public API
+ */
+export function mergePresets(base, override) {
+    const mergedMiddleware = [...base.middleware];
+    if (override.middleware) {
+        for (const overrideMiddleware of override.middleware) {
+            const existingIndex = mergedMiddleware.findIndex((m) => m.name === overrideMiddleware.name);
+            if (existingIndex >= 0) {
+                mergedMiddleware[existingIndex] = {
+                    ...mergedMiddleware[existingIndex],
+                    ...overrideMiddleware,
+                };
+            }
+            else {
+                mergedMiddleware.push(overrideMiddleware);
+            }
+        }
+    }
+    return {
+        ...base,
+        ...override,
+        middleware: mergedMiddleware,
+        tags: [...(base.tags ?? []), ...(override.tags ?? [])],
+    };
+}

package/lib/esm/middleware/middleware-profiler.js

@@ -0,0 +1,307 @@
+/**
+ * Middleware Profiler - Track execution time and performance of middleware.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept middleware-profiling
+ * @difficulty intermediate
+ *
+ * @summary Quick Start
+ * Profile middleware performance to identify bottlenecks.
+ *
+ * @example
+ * ```typescript
+ * const profiler = new MiddlewareProfiler();
+ *
+ * // Wrap middleware for profiling
+ * app.use(profiler.wrap("cors", corsMiddleware));
+ * app.use(profiler.wrap("helmet", helmetMiddleware));
+ *
+ * // Get metrics
+ * const stats = profiler.getStats();
+ * console.log(stats.metrics);
+ * ```
+ *
+ * **Metrics Provided:**
+ * - Average, min, max execution times
+ * - Percentile calculations (p50, p95, p99)
+ * - Error tracking
+ * - Pipeline-level statistics
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Architecture**
+ *
+ * MiddlewareProfiler:
+ * - Wraps middleware handlers with timing logic
+ * - Stores timing samples (configurable max)
+ * - Calculates percentiles on-demand
+ * - Tracks errors separately
+ * - Can be enabled/disabled dynamically
+ *
+ * **Design Decisions**
+ * - Configurable max samples (memory management)
+ * - Percentile calculation (not stored, calculated)
+ * - Error tracking separate from timing
+ * - Non-blocking (doesn't affect middleware execution)
+ *
+ * @see {@link MiddlewareMetrics} for metric structure
+ * @see {@link ProfilerStats} for aggregated stats
+ *
+ * @public API
+ */
+export class MiddlewareProfiler {
+    timings = new Map();
+    pipelineTimes = [];
+    totalRequests = 0;
+    enabled = true;
+    maxSamples;
+    /**
+     * Create a new MiddlewareProfiler.
+     *
+     * @param options - Profiler configuration options
+     * @param options.maxSamples - Maximum number of timing samples to keep per middleware (default: 1000)
+     * @param options.enabled - Whether profiling is enabled (default: true)
+     */
+    constructor(options = {}) {
+        this.maxSamples = options.maxSamples ?? 1000;
+        this.enabled = options.enabled ?? true;
+    }
+    /**
+     * Enable or disable profiling.
+     *
+     * @param enabled - Whether to enable profiling
+     */
+    setEnabled(enabled) {
+        this.enabled = enabled;
+    }
+    /**
+     * Check if profiling is enabled.
+     *
+     * @returns True if profiling is enabled
+     */
+    isEnabled() {
+        return this.enabled;
+    }
+    /**
+     * Wrap a middleware for profiling.
+     *
+     * @param name - Name to identify this middleware in metrics
+     * @param handler - The middleware handler to wrap
+     * @returns Wrapped middleware handler
+     *
+     * @example
+     * ```typescript
+     * const profiler = new MiddlewareProfiler();
+     * app.use(profiler.wrap("auth", authMiddleware));
+     * ```
+     */
+    wrap(name, handler) {
+        // Initialize timing entry if not exists
+        if (!this.timings.has(name)) {
+            this.timings.set(name, {
+                times: [],
+                errors: 0,
+                lastExecution: null,
+                maxSamples: this.maxSamples,
+            });
+        }
+        return (req, res, next) => {
+            if (!this.enabled) {
+                handler(req, res, next);
+                return;
+            }
+            const start = performance.now();
+            const entry = this.timings.get(name);
+            const recordTiming = (hadError) => {
+                const duration = performance.now() - start;
+                entry.times.push(duration);
+                entry.lastExecution = new Date();
+                // Keep only the last N samples
+                if (entry.times.length > entry.maxSamples) {
+                    entry.times.shift();
+                }
+                if (hadError) {
+                    entry.errors++;
+                }
+            };
+            const wrappedNext = (err) => {
+                recordTiming(!!err);
+                next(err);
+            };
+            try {
+                const result = handler(req, res, wrappedNext);
+                // Handle async middleware (middleware that returns a Promise)
+                if (result !== null &&
+                    result !== undefined &&
+                    typeof result.then === "function") {
+                    result.catch((err) => {
+                        recordTiming(true);
+                        next(err);
+                    });
+                }
+            }
+            catch (err) {
+                recordTiming(true);
+                next(err);
+            }
+        };
+    }
+    /**
+     * Create a pipeline timing middleware.
+     * Place at the start of your middleware chain to measure total pipeline time.
+     *
+     * @returns Middleware that tracks total request time
+     *
+     * @example
+     * ```typescript
+     * app.use(profiler.pipelineTimer());
+     * // ... other middleware
+     * ```
+     */
+    pipelineTimer() {
+        return (req, res, next) => {
+            if (!this.enabled) {
+                next();
+                return;
+            }
+            const start = performance.now();
+            this.totalRequests++;
+            res.on("finish", () => {
+                const duration = performance.now() - start;
+                this.pipelineTimes.push(duration);
+                // Keep only the last N samples
+                if (this.pipelineTimes.length > this.maxSamples) {
+                    this.pipelineTimes.shift();
+                }
+            });
+            next();
+        };
+    }
+    /**
+     * Calculate percentile from an array of numbers.
+     *
+     * @param arr - Array of numbers
+     * @param percentile - Percentile to calculate (0-100)
+     * @returns The percentile value
+     * @internal
+     */
+    percentile(arr, percentile) {
+        if (arr.length === 0)
+            return 0;
+        const sorted = [...arr].sort((a, b) => a - b);
+        const index = Math.ceil((percentile / 100) * sorted.length) - 1;
+        return sorted[Math.max(0, index)];
+    }
+    /**
+     * Get metrics for a specific middleware.
+     *
+     * @param name - The middleware name
+     * @returns Metrics for the middleware or null if not found
+     */
+    getMetricsFor(name) {
+        const entry = this.timings.get(name);
+        if (!entry || entry.times.length === 0) {
+            return null;
+        }
+        const times = entry.times;
+        const sum = times.reduce((a, b) => a + b, 0);
+        return {
+            name,
+            avgExecutionMs: sum / times.length,
+            minExecutionMs: Math.min(...times),
+            maxExecutionMs: Math.max(...times),
+            p50ExecutionMs: this.percentile(times, 50),
+            p95ExecutionMs: this.percentile(times, 95),
+            p99ExecutionMs: this.percentile(times, 99),
+            totalCalls: times.length,
+            errors: entry.errors,
+            lastExecutionAt: entry.lastExecution,
+        };
+    }
+    /**
+     * Get all middleware metrics.
+     *
+     * @returns Array of all middleware metrics
+     */
+    getAllMetrics() {
+        const metrics = [];
+        for (const name of this.timings.keys()) {
+            const metric = this.getMetricsFor(name);
+            if (metric) {
+                metrics.push(metric);
+            }
+        }
+        return metrics.sort((a, b) => b.avgExecutionMs - a.avgExecutionMs);
+    }
+    /**
+     * Get aggregated profiler statistics.
+     *
+     * @returns Aggregated statistics including all middleware metrics
+     */
+    getStats() {
+        const metrics = this.getAllMetrics();
+        const avgPipeline = this.pipelineTimes.length > 0
+            ? this.pipelineTimes.reduce((a, b) => a + b, 0) /
+                this.pipelineTimes.length
+            : 0;
+        const slowest = metrics.length > 0 ? metrics[0].name : null;
+        const fastest = metrics.length > 0 ? metrics[metrics.length - 1].name : null;
+        return {
+            totalMiddleware: metrics.length,
+            totalRequests: this.totalRequests,
+            avgPipelineMs: avgPipeline,
+            slowestMiddleware: slowest,
+            fastestMiddleware: fastest,
+            metrics,
+        };
+    }
+    /**
+     * Get a formatted text report of all metrics.
+     *
+     * @returns Formatted string report
+     */
+    getReport() {
+        const stats = this.getStats();
+        const lines = [
+            "╔══════════════════════════════════════════════════════════════════╗",
+            "║                    MIDDLEWARE PROFILER REPORT                    ║",
+            "╠══════════════════════════════════════════════════════════════════╣",
+            `║ Total Requests: ${stats.totalRequests.toString().padEnd(49)}║`,
+            `║ Avg Pipeline:   ${stats.avgPipelineMs.toFixed(2).padEnd(46)}ms ║`,
+            `║ Slowest:        ${(stats.slowestMiddleware ?? "N/A").padEnd(49)}║`,
+            `║ Fastest:        ${(stats.fastestMiddleware ?? "N/A").padEnd(49)}║`,
+            "╠══════════════════════════════════════════════════════════════════╣",
+            "║ MIDDLEWARE                  AVG      P95      P99    CALLS  ERR ║",
+            "╠══════════════════════════════════════════════════════════════════╣",
+        ];
+        for (const m of stats.metrics) {
+            const name = m.name.substring(0, 24).padEnd(24);
+            const avg = m.avgExecutionMs.toFixed(2).padStart(7);
+            const p95 = m.p95ExecutionMs.toFixed(2).padStart(7);
+            const p99 = m.p99ExecutionMs.toFixed(2).padStart(7);
+            const calls = m.totalCalls.toString().padStart(7);
+            const errors = m.errors.toString().padStart(4);
+            lines.push(`║ ${name} ${avg}ms ${p95}ms ${p99}ms ${calls} ${errors} ║`);
+        }
+        lines.push("╚══════════════════════════════════════════════════════════════════╝");
+        return lines.join("\n");
+    }
+    /**
+     * Reset all collected metrics.
+     */
+    reset() {
+        this.timings.clear();
+        this.pipelineTimes = [];
+        this.totalRequests = 0;
+    }
+    /**
+     * Get metrics as JSON for API responses.
+     *
+     * @returns JSON-serializable metrics object
+     */
+    toJSON() {
+        return this.getStats();
+    }
+}