@expressots/core 3.0.0-beta.4 → 4.0.0-preview.1

package/lib/esm/types/middleware/middleware-presets.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Individual middleware configuration within a preset.
+ * @public API
+ */
+export interface PresetMiddlewareConfig {
+    /** Middleware name (matches the add* method name without 'add' prefix) */
+    name: string;
+    /** Configuration options for the middleware */
+    options?: unknown;
+    /** Whether this middleware is optional (won't fail if not installed) */
+    optional?: boolean;
+}
+/**
+ * Available preset names.
+ * @public API
+ */
+export type MiddlewarePresetName = "api" | "web" | "microservice" | "graphql" | "minimal" | "secure" | "development" | "production";
+/**
+ * Preset configuration with metadata.
+ * @public API
+ */
+export interface MiddlewarePreset {
+    /** Preset name */
+    name: MiddlewarePresetName;
+    /** Human-readable description */
+    description: string;
+    /** List of middleware to apply */
+    middleware: Array<PresetMiddlewareConfig>;
+    /** Tags for categorization */
+    tags?: Array<string>;
+}
+/**
+ * Options for applying a preset.
+ * @public API
+ */
+export interface ApplyPresetOptions {
+    /** Override specific middleware options */
+    overrides?: Record<string, unknown>;
+    /** Skip specific middleware by name */
+    skip?: Array<string>;
+    /** Only apply middleware that are already installed */
+    onlyInstalled?: boolean;
+}
+/**
+ * Built-in middleware presets.
+ * @public API
+ */
+export declare const MIDDLEWARE_PRESETS: Record<MiddlewarePresetName, MiddlewarePreset>;
+/**
+ * Get a preset by name.
+ *
+ * @param name - The preset name
+ * @returns The preset configuration or undefined
+ * @public API
+ */
+export declare function getPreset(name: MiddlewarePresetName): MiddlewarePreset | undefined;
+/**
+ * Get all available preset names.
+ *
+ * @returns Array of preset names
+ * @public API
+ */
+export declare function getPresetNames(): Array<MiddlewarePresetName>;
+/**
+ * Get presets by tag.
+ *
+ * @param tag - The tag to filter by
+ * @returns Array of matching presets
+ * @public API
+ */
+export declare function getPresetsByTag(tag: string): Array<MiddlewarePreset>;
+/**
+ * Create a custom preset.
+ *
+ * @param config - The preset configuration
+ * @returns The created preset
+ * @public API
+ */
+export declare function createPreset(config: Omit<MiddlewarePreset, "name"> & {
+    name: string;
+}): MiddlewarePreset;
+/**
+ * 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 declare function mergePresets(base: MiddlewarePreset, override: Partial<MiddlewarePreset>): MiddlewarePreset;

package/lib/esm/types/middleware/middleware-profiler.d.ts

@@ -0,0 +1,199 @@
+import { RequestHandler } from "express";
+/**
+ * Performance metrics for a single middleware.
+ * @public API
+ */
+export interface MiddlewareMetrics {
+    /** Middleware name */
+    name: string;
+    /** Average execution time in milliseconds */
+    avgExecutionMs: number;
+    /** Minimum execution time in milliseconds */
+    minExecutionMs: number;
+    /** Maximum execution time in milliseconds */
+    maxExecutionMs: number;
+    /** 50th percentile (median) execution time */
+    p50ExecutionMs: number;
+    /** 95th percentile execution time */
+    p95ExecutionMs: number;
+    /** 99th percentile execution time */
+    p99ExecutionMs: number;
+    /** Total number of executions */
+    totalCalls: number;
+    /** Number of errors encountered */
+    errors: number;
+    /** Last execution timestamp */
+    lastExecutionAt: Date | null;
+}
+/**
+ * Aggregated profiler statistics.
+ * @public API
+ */
+export interface ProfilerStats {
+    /** Total middleware tracked */
+    totalMiddleware: number;
+    /** Total requests processed */
+    totalRequests: number;
+    /** Average total pipeline execution time */
+    avgPipelineMs: number;
+    /** Slowest middleware by average time */
+    slowestMiddleware: string | null;
+    /** Fastest middleware by average time */
+    fastestMiddleware: string | null;
+    /** Individual middleware metrics */
+    metrics: Array<MiddlewareMetrics>;
+}
+/**
+ * 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 declare class MiddlewareProfiler {
+    private timings;
+    private pipelineTimes;
+    private totalRequests;
+    private enabled;
+    private 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?: {
+        maxSamples?: number;
+        enabled?: boolean;
+    });
+    /**
+     * Enable or disable profiling.
+     *
+     * @param enabled - Whether to enable profiling
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Check if profiling is enabled.
+     *
+     * @returns True if profiling is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * 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: string, handler: RequestHandler): RequestHandler;
+    /**
+     * 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(): RequestHandler;
+    /**
+     * Calculate percentile from an array of numbers.
+     *
+     * @param arr - Array of numbers
+     * @param percentile - Percentile to calculate (0-100)
+     * @returns The percentile value
+     * @internal
+     */
+    private percentile;
+    /**
+     * Get metrics for a specific middleware.
+     *
+     * @param name - The middleware name
+     * @returns Metrics for the middleware or null if not found
+     */
+    getMetricsFor(name: string): MiddlewareMetrics | null;
+    /**
+     * Get all middleware metrics.
+     *
+     * @returns Array of all middleware metrics
+     */
+    getAllMetrics(): Array<MiddlewareMetrics>;
+    /**
+     * Get aggregated profiler statistics.
+     *
+     * @returns Aggregated statistics including all middleware metrics
+     */
+    getStats(): ProfilerStats;
+    /**
+     * Get a formatted text report of all metrics.
+     *
+     * @returns Formatted string report
+     */
+    getReport(): string;
+    /**
+     * Reset all collected metrics.
+     */
+    reset(): void;
+    /**
+     * Get metrics as JSON for API responses.
+     *
+     * @returns JSON-serializable metrics object
+     */
+    toJSON(): ProfilerStats;
+}

package/lib/esm/types/middleware/middleware-registry.d.ts

@@ -0,0 +1,103 @@
+/**
+ * ExpressoTS v4 Middleware Registry
+ *
+ * Singleton registry for named middleware that can be used in routes.
+ *
+ * @module middleware-registry
+ * @public API
+ */
+import type { RequestHandler } from "express";
+import type { RegisteredMiddleware } from "./middleware-config.js";
+/**
+ * ExpressoMiddleware interface for class-based middleware.
+ */
+interface IExpressoMiddleware {
+    use: RequestHandler;
+}
+/**
+ * Middleware entry type (can be handler, array, or class).
+ */
+export type MiddlewareEntry = RequestHandler | Array<RequestHandler> | IExpressoMiddleware;
+/**
+ * Middleware Registry for named middleware.
+ *
+ * Allows registering middleware by name in app.ts and using them
+ * in controllers via the use() utility function.
+ *
+ * @example
+ * ```typescript
+ * // In app.ts
+ * this.Middleware.register('auth', verifyJwtMiddleware);
+ *
+ * // In controller
+ * @httpGet('/', ...use('auth'))
+ * async getUsers() { }
+ * ```
+ *
+ * @public API
+ */
+export declare class MiddlewareRegistry {
+    private registry;
+    /**
+     * Register a named middleware.
+     *
+     * @param name - Unique name for the middleware
+     * @param handler - Express handler, array of handlers, or ExpressoMiddleware class
+     */
+    register(name: string, handler: MiddlewareEntry): void;
+    /**
+     * Get a registered middleware by name.
+     *
+     * @param name - Middleware name
+     * @returns The middleware handler(s) or undefined
+     */
+    get(name: string): RequestHandler | Array<RequestHandler> | undefined;
+    /**
+     * Check if a middleware is registered.
+     *
+     * @param name - Middleware name
+     * @returns True if registered
+     */
+    has(name: string): boolean;
+    /**
+     * Get all registered middleware names.
+     *
+     * @returns Array of registered names
+     */
+    getRegisteredNames(): Array<string>;
+    /**
+     * Get all registered middleware entries.
+     *
+     * @returns Array of registered middleware
+     */
+    getAll(): Array<RegisteredMiddleware>;
+    /**
+     * Unregister a middleware by name.
+     *
+     * @param name - Middleware name
+     * @returns True if removed
+     */
+    unregister(name: string): boolean;
+    /**
+     * Clear all registered middleware.
+     */
+    clear(): void;
+    /**
+     * Normalize different handler types to RequestHandler or Array<RequestHandler>.
+     */
+    private normalizeHandler;
+}
+/**
+ * Get the singleton middleware registry instance.
+ *
+ * @returns The global middleware registry
+ * @public API
+ */
+export declare function getMiddlewareRegistry(): MiddlewareRegistry;
+/**
+ * Reset the middleware registry (for testing).
+ *
+ * @internal
+ */
+export declare function resetMiddlewareRegistry(): void;
+export {};

package/lib/esm/types/middleware/middleware-resolver.d.ts

@@ -0,0 +1,159 @@
+import type { ExpressHandler } from "./middleware-service.js";
+/**
+ * Registry mapping middleware names to their npm package names.
+ * @internal
+ */
+declare const MIDDLEWARE_REGISTRY: {
+    readonly cors: "cors";
+    readonly compression: "compression";
+    readonly cookieParser: "cookie-parser";
+    readonly cookieSession: "cookie-session";
+    readonly serveFavicon: "serve-favicon";
+    readonly morgan: "morgan";
+    readonly helmet: "helmet";
+    readonly rateLimit: "express-rate-limit";
+    readonly multer: "multer";
+    readonly session: "express-session";
+    readonly pino: "pino-http";
+    readonly winston: "express-winston";
+    readonly shrinkRay: "shrink-ray-current";
+};
+/**
+ * Type for registered middleware names.
+ * @public API
+ */
+export type RegisteredMiddlewareName = keyof typeof MIDDLEWARE_REGISTRY;
+/**
+ * Get buffered resolver startup warnings.
+ * @returns Array of warning messages
+ * @public API
+ */
+declare function getResolverStartupWarnings(): Array<{
+    message: string;
+    type: "info" | "warn";
+}>;
+/**
+ * Clear buffered resolver startup warnings.
+ * @public API
+ */
+declare function clearResolverStartupWarnings(): void;
+/**
+ * Resolve a middleware by name and configure it with the provided options.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept middleware-resolution
+ * @difficulty intermediate
+ *
+ * @summary Quick Start
+ * Resolve and configure middleware packages automatically.
+ *
+ * @example
+ * ```typescript
+ * const corsMiddleware = middlewareResolver("cors", { origin: true });
+ * const helmetMiddleware = middlewareResolver("helmet");
+ *
+ * if (corsMiddleware) {
+ *   app.use(corsMiddleware);
+ * }
+ * ```
+ *
+ * **Features:**
+ * - Auto-discovers installed middleware packages
+ * - Caches resolved modules for performance
+ * - Returns null if middleware not installed
+ * - Supports all registered middleware types
+ *
+ * @param middlewareName - The name of the middleware (e.g., "cors", "helmet")
+ * @param options - Configuration options to pass to the middleware factory
+ * @returns The configured middleware handler or null if not available
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Behavior**
+ * - Checks package installation status (cached)
+ * - Resolves module using require.resolve (cached)
+ * - Calls middleware factory with options
+ * - Returns null on failure (logs error)
+ *
+ * @see {@link MIDDLEWARE_REGISTRY} for registered middleware
+ * @see {@link isMiddlewareAvailable} for availability check
+ *
+ * @public API
+ */
+declare function middlewareResolver(middlewareName: RegisteredMiddlewareName | string, ...options: Array<any>): ExpressHandler | null;
+/**
+ * Check if a middleware package is available without logging warnings.
+ * Useful for conditional middleware loading.
+ *
+ * @param middlewareName - The middleware name to check
+ * @returns True if the middleware is installed and available
+ *
+ * @example
+ * ```typescript
+ * if (isMiddlewareAvailable("helmet")) {
+ *   middleware.addHelmet();
+ * }
+ * ```
+ *
+ * @public API
+ */
+declare function isMiddlewareAvailable(middlewareName: RegisteredMiddlewareName | string): boolean;
+/**
+ * Get a list of all installed middleware from the registry.
+ *
+ * @returns Array of installed middleware names
+ *
+ * @example
+ * ```typescript
+ * const available = getAvailableMiddleware();
+ * console.log("Installed middleware:", available);
+ * // Output: ["cors", "helmet", "compression"]
+ * ```
+ *
+ * @public API
+ */
+declare function getAvailableMiddleware(): Array<RegisteredMiddlewareName>;
+/**
+ * Get all registered middleware names (whether installed or not).
+ *
+ * @returns Array of all registered middleware names
+ * @public API
+ */
+declare function getRegisteredMiddleware(): Array<RegisteredMiddlewareName>;
+/**
+ * Clear all middleware caches.
+ * Useful for testing or when packages are installed at runtime.
+ *
+ * @public API
+ */
+declare function clearMiddlewareCache(): void;
+/**
+ * Get the npm package name for a registered middleware.
+ *
+ * @param middlewareName - The middleware name
+ * @returns The npm package name or undefined if not registered
+ * @public API
+ */
+declare function getPackageName(middlewareName: RegisteredMiddlewareName | string): string | undefined;
+/**
+ * Check if any npm package is installed (not just registered middleware).
+ *
+ * @param packageName - The npm package name to check
+ * @returns True if the package is installed
+ *
+ * @public API
+ */
+declare function isPackageAvailable(packageName: string): boolean;
+/**
+ * Resolve any npm module by package name.
+ * Used for dynamic logger and compression resolution.
+ *
+ * @param packageName - The npm package name
+ * @returns The resolved module or null
+ *
+ * @public API
+ */
+declare function resolvePackage<T = unknown>(packageName: string): T | null;
+export { middlewareResolver, isMiddlewareAvailable, isPackageAvailable, resolvePackage, getAvailableMiddleware, getRegisteredMiddleware, clearMiddlewareCache, getPackageName, getResolverStartupWarnings, clearResolverStartupWarnings, MIDDLEWARE_REGISTRY, };