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

package/lib/cjs/middleware/middleware-registry.js

@@ -0,0 +1,160 @@
+"use strict";
+/**
+ * ExpressoTS v4 Middleware Registry
+ *
+ * Singleton registry for named middleware that can be used in routes.
+ *
+ * @module middleware-registry
+ * @public API
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MiddlewareRegistry = void 0;
+exports.getMiddlewareRegistry = getMiddlewareRegistry;
+exports.resetMiddlewareRegistry = resetMiddlewareRegistry;
+/**
+ * Singleton middleware registry instance.
+ * @internal
+ */
+let registryInstance = null;
+/**
+ * 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
+ */
+class MiddlewareRegistry {
+    constructor() {
+        this.registry = new Map();
+    }
+    /**
+     * Register a named middleware.
+     *
+     * @param name - Unique name for the middleware
+     * @param handler - Express handler, array of handlers, or ExpressoMiddleware class
+     */
+    register(name, handler) {
+        const normalizedHandler = this.normalizeHandler(handler);
+        this.registry.set(name, {
+            name,
+            handler: normalizedHandler,
+            registeredAt: new Date(),
+        });
+    }
+    /**
+     * Get a registered middleware by name.
+     *
+     * @param name - Middleware name
+     * @returns The middleware handler(s) or undefined
+     */
+    get(name) {
+        return this.registry.get(name)?.handler;
+    }
+    /**
+     * Check if a middleware is registered.
+     *
+     * @param name - Middleware name
+     * @returns True if registered
+     */
+    has(name) {
+        return this.registry.has(name);
+    }
+    /**
+     * Get all registered middleware names.
+     *
+     * @returns Array of registered names
+     */
+    getRegisteredNames() {
+        return Array.from(this.registry.keys());
+    }
+    /**
+     * Get all registered middleware entries.
+     *
+     * @returns Array of registered middleware
+     */
+    getAll() {
+        return Array.from(this.registry.values());
+    }
+    /**
+     * Unregister a middleware by name.
+     *
+     * @param name - Middleware name
+     * @returns True if removed
+     */
+    unregister(name) {
+        return this.registry.delete(name);
+    }
+    /**
+     * Clear all registered middleware.
+     */
+    clear() {
+        this.registry.clear();
+    }
+    /**
+     * Normalize different handler types to RequestHandler or Array<RequestHandler>.
+     */
+    normalizeHandler(handler) {
+        // If it's already a function (RequestHandler)
+        if (typeof handler === "function") {
+            return handler;
+        }
+        // If it's an array of handlers
+        if (Array.isArray(handler)) {
+            return handler.map((h) => {
+                if (typeof h === "function") {
+                    return h;
+                }
+                // Handle ExpressoMiddleware in array
+                const handlerObj = h;
+                if (handlerObj &&
+                    typeof handlerObj === "object" &&
+                    "use" in handlerObj &&
+                    typeof handlerObj.use === "function") {
+                    return handlerObj.use.bind(handlerObj);
+                }
+                throw new Error(`Invalid middleware in array: ${typeof h}`);
+            });
+        }
+        // If it's an ExpressoMiddleware class instance
+        const handlerObj = handler;
+        if (handlerObj &&
+            typeof handlerObj === "object" &&
+            "use" in handlerObj &&
+            typeof handlerObj.use === "function") {
+            return handlerObj.use.bind(handlerObj);
+        }
+        throw new Error(`Invalid middleware type: ${typeof handler}`);
+    }
+}
+exports.MiddlewareRegistry = MiddlewareRegistry;
+/**
+ * Get the singleton middleware registry instance.
+ *
+ * @returns The global middleware registry
+ * @public API
+ */
+function getMiddlewareRegistry() {
+    if (!registryInstance) {
+        registryInstance = new MiddlewareRegistry();
+    }
+    return registryInstance;
+}
+/**
+ * Reset the middleware registry (for testing).
+ *
+ * @internal
+ */
+function resetMiddlewareRegistry() {
+    registryInstance = null;
+}

package/lib/cjs/middleware/middleware-resolver.js

@@ -1,72 +1,333 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIDDLEWARE_REGISTRY = void 0;
 exports.middlewareResolver = middlewareResolver;
-const logger_provider_1 = require("../provider/logger/logger.provider");
-/**
- * MiddlewareResolver class is responsible for resolving and retrieving Express middlewares
- * by their names. It maintains a registry of available middlewares and provides
- * a method to retrieve them by their name. If a middleware is not installed, it logs
- * an informative message.
- */
-class MiddlewareResolver {
-    constructor() {
-        /**
-         * A registry object mapping middleware names to their corresponding package names.
-         * It is used to identify and require the middleware from the current working directory.
-         */
-        this.middlewareRegistry = {
-            cors: "cors",
-            compression: "compression",
-            cookieParser: "cookie-parser",
-            cookieSession: "cookie-session",
-            serveFavicon: "serve-favicon",
-            morgan: "morgan",
-            helmet: "helmet",
-            rateLimit: "express-rate-limit",
-            multer: "multer",
-            session: "express-session",
-            urlencoded: "urlencodedParser",
-            // Add other middlewares
-        };
-        this.logger = new logger_provider_1.Logger();
+exports.isMiddlewareAvailable = isMiddlewareAvailable;
+exports.isPackageAvailable = isPackageAvailable;
+exports.resolvePackage = resolvePackage;
+exports.getAvailableMiddleware = getAvailableMiddleware;
+exports.getRegisteredMiddleware = getRegisteredMiddleware;
+exports.clearMiddlewareCache = clearMiddlewareCache;
+exports.getPackageName = getPackageName;
+exports.getResolverStartupWarnings = getResolverStartupWarnings;
+exports.clearResolverStartupWarnings = clearResolverStartupWarnings;
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const logger_provider_js_1 = require("../provider/logger/logger.provider.js");
+/**
+ * Registry mapping middleware names to their npm package names.
+ * @internal
+ */
+const MIDDLEWARE_REGISTRY = {
+    cors: "cors",
+    compression: "compression",
+    cookieParser: "cookie-parser",
+    cookieSession: "cookie-session",
+    serveFavicon: "serve-favicon",
+    morgan: "morgan",
+    helmet: "helmet",
+    rateLimit: "express-rate-limit",
+    multer: "multer",
+    session: "express-session",
+    // v4 additions
+    pino: "pino-http",
+    winston: "express-winston",
+    shrinkRay: "shrink-ray-current",
+};
+exports.MIDDLEWARE_REGISTRY = MIDDLEWARE_REGISTRY;
+/**
+ * Cached resolved modules for O(1) subsequent access.
+ * @internal
+ */
+const moduleCache = new Map();
+/**
+ * Cached package installation status to avoid repeated filesystem checks.
+ * @internal
+ */
+const installStatusCache = new Map();
+/**
+ * Singleton logger instance - lazily initialized.
+ * @internal
+ */
+let loggerInstance = null;
+/**
+ * Buffered startup warnings from resolver (for display after banner).
+ * @internal
+ */
+const resolverStartupWarnings = [];
+/**
+ * Get the singleton logger instance.
+ * @returns Logger instance
+ * @internal
+ */
+function getLogger() {
+    if (!loggerInstance) {
+        loggerInstance = new logger_provider_js_1.Logger();
     }
-    /**
-     * Retrieves a middleware by its name and optionally configures it with provided options.
-     *
-     * @param {string} middlewareName - The name of the middleware to be retrieved.
-     * @param {...any} options - Optional arguments to configure the middleware.
-     * @returns {express.RequestHandler | null} - Returns the configured middleware or null if not found or not installed.
-     */
-    getMiddleware(middlewareName, ...options) {
-        const packageName = this.middlewareRegistry[middlewareName];
-        if (!packageName) {
-            this.logger.error(`Middleware ${packageName} not found`, "middleware-resolver");
-            return null;
+    return loggerInstance;
+}
+/**
+ * Get buffered resolver startup warnings.
+ * @returns Array of warning messages
+ * @public API
+ */
+function getResolverStartupWarnings() {
+    return [...resolverStartupWarnings];
+}
+/**
+ * Clear buffered resolver startup warnings.
+ * @public API
+ */
+function clearResolverStartupWarnings() {
+    resolverStartupWarnings.length = 0;
+}
+/**
+ * Buffer a startup warning instead of logging immediately.
+ * @internal
+ */
+function bufferStartupWarning(message) {
+    resolverStartupWarnings.push({ message, type: "warn" });
+}
+/**
+ * Check if a package is installed in the project.
+ * Results are cached for performance.
+ *
+ * @param packageName - The npm package name to check
+ * @returns True if the package is installed
+ * @internal
+ */
+function isPackageInstalled(packageName) {
+    const cached = installStatusCache.get(packageName);
+    if (cached !== undefined) {
+        return cached;
+    }
+    try {
+        require.resolve(packageName, { paths: [process.cwd()] });
+        installStatusCache.set(packageName, true);
+        return true;
+    }
+    catch {
+        installStatusCache.set(packageName, false);
+        return false;
+    }
+}
+/**
+ * Resolve and cache a middleware module.
+ *
+ * @param packageName - The npm package name to resolve
+ * @returns The resolved module or null if not installed/failed
+ * @internal
+ */
+function resolveModule(packageName) {
+    const cached = moduleCache.get(packageName);
+    if (cached !== undefined) {
+        return cached;
+    }
+    if (!isPackageInstalled(packageName)) {
+        return null;
+    }
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const mod = require(packageName);
+        // Handle various module export patterns:
+        // 1. CommonJS: module.exports = fn → mod is the function
+        // 2. ES Module with default: export default fn → mod.default is the function
+        // 3. ES Module transpiled: mod.__esModule with default → mod.default
+        let resolved;
+        if (typeof mod === "function") {
+            // Direct function export (most CommonJS modules like morgan, cors, etc.)
+            resolved = mod;
         }
-        let hasMiddleware = "";
-        try {
-            hasMiddleware = require.resolve(packageName, { paths: [process.cwd()] });
+        else if (mod && typeof mod.default === "function") {
+            // ES module with default export
+            resolved = mod.default;
         }
-        catch (error) {
-            this.logger.warn(`Middleware [${packageName}] not installed. Please install it using your package manager.`, "middleware-resolver");
+        else if (mod && mod.__esModule && mod.default) {
+            // Transpiled ES module
+            resolved = mod.default;
         }
-        if (hasMiddleware) {
-            // eslint-disable-next-line @typescript-eslint/no-var-requires
-            const middleware = require(hasMiddleware);
-            return middleware(...options) || middleware.default(...options);
+        else {
+            // Object export (for modules like express-winston that export { logger })
+            resolved = mod;
         }
+        moduleCache.set(packageName, resolved);
+        return resolved;
+    }
+    catch (error) {
+        getLogger().error(`Failed to load middleware [${packageName}]: ${error}`, "middleware-resolver");
+        return null;
+    }
+}
+/**
+ * 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
+ */
+function middlewareResolver(middlewareName, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+...options) {
+    const packageName = MIDDLEWARE_REGISTRY[middlewareName];
+    if (!packageName) {
+        getLogger().error(`Unknown middleware: ${middlewareName}. Available: ${Object.keys(MIDDLEWARE_REGISTRY).join(", ")}`, "middleware-resolver");
+        return null;
+    }
+    // Check installation status first (cached)
+    if (!isPackageInstalled(packageName)) {
+        // Buffer warning for display after banner instead of immediate log
+        bufferStartupWarning(`${packageName} not installed`);
+        return null;
+    }
+    // Resolve the module (cached)
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const middlewareFactory = resolveModule(packageName);
+    if (!middlewareFactory) {
+        return null;
+    }
+    // Handle both function exports and objects with default export
+    const factory = typeof middlewareFactory === "function"
+        ? middlewareFactory
+        : typeof middlewareFactory.default === "function"
+            ? middlewareFactory.default
+            : null;
+    if (!factory) {
+        getLogger().error(`Middleware [${middlewareName}] does not export a function. Got: ${typeof middlewareFactory}`, "middleware-resolver");
+        return null;
+    }
+    try {
+        // Filter out undefined options to avoid passing them to middleware
+        const filteredOptions = options.filter((opt) => opt !== undefined);
+        return factory(...filteredOptions);
+    }
+    catch (error) {
+        getLogger().error(`Failed to initialize middleware [${middlewareName}]: ${error}`, "middleware-resolver");
         return null;
     }
 }
 /**
- * A utility function that wraps the creation and retrieval of middleware.
- * It creates a new instance of MiddlewareResolver and calls the getMiddleware method.
+ * 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
+ */
+function isMiddlewareAvailable(middlewareName) {
+    const packageName = MIDDLEWARE_REGISTRY[middlewareName];
+    return packageName ? isPackageInstalled(packageName) : false;
+}
+/**
+ * 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
+ */
+function getAvailableMiddleware() {
+    return Object.keys(MIDDLEWARE_REGISTRY).filter((name) => isMiddlewareAvailable(name));
+}
+/**
+ * Get all registered middleware names (whether installed or not).
+ *
+ * @returns Array of all registered middleware names
+ * @public API
+ */
+function getRegisteredMiddleware() {
+    return Object.keys(MIDDLEWARE_REGISTRY);
+}
+/**
+ * Clear all middleware caches.
+ * Useful for testing or when packages are installed at runtime.
+ *
+ * @public API
+ */
+function clearMiddlewareCache() {
+    moduleCache.clear();
+    installStatusCache.clear();
+}
+/**
+ * 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
+ */
+function getPackageName(middlewareName) {
+    return MIDDLEWARE_REGISTRY[middlewareName];
+}
+/**
+ * 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
+ */
+function isPackageAvailable(packageName) {
+    return isPackageInstalled(packageName);
+}
+/**
+ * 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
  *
- * @param {string} middleware - The name of the middleware to be retrieved.
- * @param {...any} options - Optional arguments to configure the middleware.
- * @returns {express.RequestHandler | null} - Returns the configured middleware or null if not found or not installed.
+ * @public API
  */
-function middlewareResolver(middleware, ...options) {
-    const resolver = new MiddlewareResolver();
-    return resolver.getMiddleware(middleware, ...options);
+function resolvePackage(packageName) {
+    return resolveModule(packageName);
 }