@expressots/core 3.0.0 → 4.0.0-preview.3

package/lib/cjs/render/utils/package-resolver.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PackageNotInstalledError = exports.PackageResolver = void 0;
+exports.getPackageResolver = getPackageResolver;
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const logger_provider_js_1 = require("../../provider/logger/logger.provider.js");
+/**
+ * Package Resolver
+ *
+ * @description Enhanced package resolution with helpful error messages.
+ * Resolves packages from the user's project directory.
+ *
+ * @public API
+ */
+class PackageResolver {
+    constructor() {
+        this.logger = new logger_provider_js_1.Logger();
+    }
+    /**
+     * Resolve and require a package from the user's project.
+     *
+     * @param packageName - Package name to resolve
+     * @param options - Options to pass if package exports a function
+     * @returns The resolved package module
+     * @throws Error if package is not installed
+     */
+    resolve(packageName, ...options) {
+        try {
+            const packagePath = require.resolve(packageName, {
+                paths: [process.cwd()],
+            });
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const packageModule = require(packagePath);
+            if (typeof packageModule === "function") {
+                return packageModule(...options);
+            }
+            if (packageModule.default &&
+                typeof packageModule.default === "function") {
+                return packageModule.default(...options);
+            }
+            return packageModule;
+        }
+        catch (error) {
+            this.logger.warn(`Package [${packageName}] not installed. Install it with: npm install ${packageName}`, "package-resolver");
+            throw new PackageNotInstalledError(packageName);
+        }
+    }
+    /**
+     * Check if a package is installed without throwing.
+     *
+     * @param packageName - Package name to check
+     * @returns Whether the package is installed
+     */
+    isInstalled(packageName) {
+        try {
+            require.resolve(packageName, { paths: [process.cwd()] });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Get the installed version of a package.
+     *
+     * @param packageName - Package name
+     * @returns Version string or null if not installed
+     */
+    getVersion(packageName) {
+        try {
+            const packagePath = require.resolve(`${packageName}/package.json`, {
+                paths: [process.cwd()],
+            });
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const pkg = require(packagePath);
+            return pkg.version || null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Check multiple packages and return which ones are installed.
+     *
+     * @param packageNames - Package names to check
+     * @returns Object mapping package names to installation status
+     */
+    checkMultiple(packageNames) {
+        const result = {};
+        for (const pkg of packageNames) {
+            result[pkg] = this.isInstalled(pkg);
+        }
+        return result;
+    }
+}
+exports.PackageResolver = PackageResolver;
+/**
+ * Error thrown when a required package is not installed.
+ * @public API
+ */
+class PackageNotInstalledError extends Error {
+    constructor(packageName) {
+        super(`Package '${packageName}' is not installed. Run: npm install ${packageName}`);
+        this.name = "PackageNotInstalledError";
+        this.packageName = packageName;
+    }
+}
+exports.PackageNotInstalledError = PackageNotInstalledError;
+/** Singleton instance */
+let resolverInstance = null;
+/**
+ * Get the package resolver singleton.
+ *
+ * @returns Package resolver instance
+ */
+function getPackageResolver() {
+    if (!resolverInstance) {
+        resolverInstance = new PackageResolver();
+    }
+    return resolverInstance;
+}

package/lib/cjs/render/utils/view-scanner.js

@@ -0,0 +1,208 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ViewScanner = void 0;
+exports.getViewScanner = getViewScanner;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * View Scanner
+ *
+ * @description Scans directories for view files and provides information about them.
+ *
+ * @public API
+ */
+class ViewScanner {
+    constructor() {
+        this.registry = null;
+    }
+    /**
+     * Set the engine registry for extension mapping.
+     *
+     * @param registry - Engine registry instance
+     */
+    setRegistry(registry) {
+        this.registry = registry;
+    }
+    /**
+     * Scan a directory for view files.
+     *
+     * @param viewsDir - Directory to scan
+     * @param recursive - Whether to scan subdirectories
+     * @returns Array of view file paths
+     */
+    async scanDirectory(viewsDir, recursive = true) {
+        const views = [];
+        if (!fs.existsSync(viewsDir)) {
+            return views;
+        }
+        const files = await fs.promises.readdir(viewsDir, { withFileTypes: true });
+        for (const file of files) {
+            const fullPath = path.join(viewsDir, file.name);
+            if (file.isDirectory() && recursive) {
+                const subViews = await this.scanDirectory(fullPath, true);
+                views.push(...subViews);
+            }
+            else if (file.isFile()) {
+                const ext = path.extname(file.name);
+                if (this.isViewFile(ext)) {
+                    views.push(fullPath);
+                }
+            }
+        }
+        return views;
+    }
+    /**
+     * Scan multiple directories for view files.
+     *
+     * @param viewsDirs - Directories to scan
+     * @param recursive - Whether to scan subdirectories
+     * @returns Array of view file paths
+     */
+    async scanDirectories(viewsDirs, recursive = true) {
+        const allViews = [];
+        for (const dir of viewsDirs) {
+            const views = await this.scanDirectory(dir, recursive);
+            allViews.push(...views);
+        }
+        return allViews;
+    }
+    /**
+     * Get detailed information about view files.
+     *
+     * @param viewsDir - Directory to scan
+     * @returns Array of view information
+     */
+    async getViewInfo(viewsDir) {
+        const files = await this.scanDirectory(viewsDir);
+        const viewInfos = [];
+        for (const filePath of files) {
+            const ext = path.extname(filePath);
+            const relativePath = path.relative(viewsDir, filePath);
+            const name = relativePath.replace(ext, "").replace(/\\/g, "/");
+            viewInfos.push({
+                name,
+                path: filePath,
+                extension: ext,
+                engine: this.mapExtensionToEngine(ext),
+            });
+        }
+        return viewInfos;
+    }
+    /**
+     * Check if a file extension is a view file.
+     *
+     * @param extension - File extension
+     * @returns Whether it's a view file
+     */
+    isViewFile(extension) {
+        const viewExtensions = [
+            ".ejs",
+            ".pug",
+            ".jade",
+            ".hbs",
+            ".handlebars",
+            ".tsx",
+            ".jsx",
+            ".vue",
+            ".svelte",
+        ];
+        return viewExtensions.includes(extension.toLowerCase());
+    }
+    /**
+     * Map a file extension to an engine type.
+     *
+     * @param extension - File extension
+     * @returns Engine type
+     */
+    mapExtensionToEngine(extension) {
+        const extensionMap = {
+            ".ejs": "ejs",
+            ".pug": "pug",
+            ".jade": "pug",
+            ".hbs": "hbs",
+            ".handlebars": "hbs",
+            ".tsx": "react",
+            ".jsx": "react",
+            ".vue": "vue",
+            ".svelte": "svelte",
+        };
+        return extensionMap[extension.toLowerCase()] || "ejs";
+    }
+    /**
+     * Check if any view files exist in common directories.
+     *
+     * @returns Object mapping directory names to whether they contain views
+     */
+    async findViewDirectories() {
+        const commonDirs = [
+            "views",
+            "src/views",
+            "templates",
+            "src/templates",
+            "app/views",
+        ];
+        const result = {};
+        for (const dir of commonDirs) {
+            const fullPath = path.join(process.cwd(), dir);
+            if (fs.existsSync(fullPath)) {
+                const views = await this.scanDirectory(fullPath, false);
+                result[dir] = views.length > 0;
+            }
+            else {
+                result[dir] = false;
+            }
+        }
+        return result;
+    }
+    /**
+     * Get extensions found in a directory.
+     *
+     * @param viewsDir - Directory to scan
+     * @returns Array of unique extensions
+     */
+    async getExtensions(viewsDir) {
+        const files = await this.scanDirectory(viewsDir);
+        const extensions = new Set();
+        for (const file of files) {
+            extensions.add(path.extname(file).toLowerCase());
+        }
+        return Array.from(extensions);
+    }
+}
+exports.ViewScanner = ViewScanner;
+/** Singleton instance */
+let scannerInstance = null;
+/**
+ * Get the view scanner singleton.
+ *
+ * @returns View scanner instance
+ */
+function getViewScanner() {
+    if (!scannerInstance) {
+        scannerInstance = new ViewScanner();
+    }
+    return scannerInstance;
+}

package/lib/cjs/testing/create-test-app.js

@@ -0,0 +1,366 @@
+"use strict";
+/**
+ * Zero-Config Test Application Setup
+ *
+ * @module testing
+ *
+ * Creates a fully functional test application with DI container,
+ * fluent request builder, and automatic cleanup.
+ *
+ * @example
+ * ```typescript
+ * describe("UserController", () => {
+ *   const { app, container, request } = await createTestApp(App);
+ *
+ *   test("GET /users returns user list", async () => {
+ *     const response = await request.get("/users");
+ *     expect(response.status).toBe(200);
+ *   });
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTestApp = createTestApp;
+exports.cleanupAllTestApps = cleanupAllTestApps;
+exports.getActiveTestAppCount = getActiveTestAppCount;
+const inversify_js_1 = require("../di/inversify.js");
+const application_factory_js_1 = require("../application/application-factory.js");
+const fluent_request_js_1 = require("./fluent-request.js");
+/**
+ * Internal test app wrapper that implements ITestApp interface.
+ */
+class TestApp {
+    constructor(appInstance, container) {
+        this.appInstance = appInstance;
+        this.overrides = new Map();
+        this._container = container;
+    }
+    /**
+     * Get the underlying HTTP server.
+     */
+    getHttpServer() {
+        return this.server;
+    }
+    /**
+     * Set the HTTP server reference.
+     */
+    setHttpServer(server) {
+        this.server = server;
+    }
+    /**
+     * Close the test server.
+     * Handles cleanup of both the app instance and the underlying HTTP server.
+     */
+    async close() {
+        // First, try to close via app instance if it has close method
+        const app = this.appInstance;
+        if (app && typeof app.close === "function") {
+            await app.close();
+            return;
+        }
+        // Get the HTTP server from the app instance if available
+        let httpServer = null;
+        if (app && typeof app.getHttpServer === "function") {
+            try {
+                httpServer = (await app.getHttpServer());
+            }
+            catch {
+                // Server might not be initialized, try fallback
+            }
+        }
+        // Fallback: use stored server reference
+        if (!httpServer && this.server) {
+            httpServer = this.server;
+        }
+        // Close the HTTP server
+        if (httpServer && typeof httpServer.close === "function") {
+            // Close idle connections first for faster cleanup (like AppExpress does internally)
+            if (typeof httpServer.closeIdleConnections === "function") {
+                httpServer.closeIdleConnections();
+            }
+            // Close the server with proper error handling
+            await new Promise((resolve) => {
+                const timeout = setTimeout(() => {
+                    // Force destroy if close takes too long
+                    if (httpServer && typeof httpServer.destroy === "function") {
+                        httpServer.destroy();
+                    }
+                    resolve();
+                }, 5000); // 5 second timeout
+                httpServer.close((err) => {
+                    clearTimeout(timeout);
+                    if (err) {
+                        // Don't fail on close error - just log and resolve
+                        // This matches AppExpress graceful shutdown behavior
+                        console.log(`Note: Test server close returned: ${err?.message}`);
+                    }
+                    resolve();
+                });
+            });
+        }
+    }
+    /**
+     * Get a service from the container.
+     */
+    get(serviceIdentifier) {
+        // Check for overrides first
+        if (this.overrides.has(serviceIdentifier)) {
+            return this.overrides.get(serviceIdentifier);
+        }
+        return this._container.get(serviceIdentifier);
+    }
+    /**
+     * Check if a service is bound in the container.
+     */
+    isBound(serviceIdentifier) {
+        return this._container.isBound(serviceIdentifier);
+    }
+    /**
+     * Override a provider with a mock.
+     */
+    overrideProvider(serviceIdentifier, mock) {
+        this.overrides.set(serviceIdentifier, mock);
+        // Rebind in container if already bound
+        const id = serviceIdentifier;
+        if (this._container.isBound(id)) {
+            this._container.rebind(id).toConstantValue(mock);
+        }
+        else {
+            this._container.bind(id).toConstantValue(mock);
+        }
+    }
+    /**
+     * Get the DI container.
+     */
+    get container() {
+        return this._container;
+    }
+    /**
+     * Get the app instance.
+     */
+    getAppInstance() {
+        return this.appInstance;
+    }
+}
+/**
+ * Internal state for managing test apps.
+ */
+const activeTestApps = [];
+/**
+ * Create a fully functional test application with zero configuration.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept testing
+ *
+ * This function provides:
+ * - One-line test app creation
+ * - Full DI container access
+ * - Fluent HTTP request builder
+ * - Automatic cleanup
+ *
+ * @param AppClass - The application class to test
+ * @param options - Optional configuration
+ * @returns Test app result with app, container, and request builder
+ *
+ * @example
+ * ```typescript
+ * // Simplest usage - zero config
+ * const { app, container, request } = await createTestApp(App);
+ *
+ * // With mock providers
+ * const { app, request } = await createTestApp(App, {
+ *   mockProviders: [
+ *     { provide: UserService, useValue: mockUserService }
+ *   ]
+ * });
+ *
+ * // With custom environment
+ * const { app, request } = await createTestApp(App, {
+ *   env: {
+ *     DATABASE_URL: "memory://test",
+ *     JWT_SECRET: "test-secret"
+ *   }
+ * });
+ * ```
+ */
+async function createTestApp(AppClass, options = {}) {
+    // Set up test environment variables
+    const originalEnv = { ...process.env };
+    if (options.env) {
+        Object.assign(process.env, options.env);
+    }
+    process.env.NODE_ENV = "test";
+    try {
+        // Create the app instance using AppFactory
+        const appInstance = await application_factory_js_1.AppFactory.create(AppClass);
+        const appWithContainer = appInstance;
+        const container = appWithContainer.container?.Container ||
+            appWithContainer._container ||
+            getContainerFromApp(appInstance);
+        // Create test app wrapper
+        const testApp = new TestApp(appInstance, container);
+        // Apply mock providers
+        if (options.mockProviders && options.mockProviders.length > 0) {
+            applyMockProviders(testApp, options.mockProviders);
+        }
+        // Start the server on a random port
+        const port = options.port ?? 0;
+        await appInstance.listen(port, {
+            appName: "Test App",
+            appVersion: "1.0.0",
+        });
+        const appWithServer = appInstance;
+        let httpServer = null;
+        let actualPort = port;
+        if (typeof appWithServer.getHttpServer === "function") {
+            try {
+                httpServer = (await appWithServer.getHttpServer());
+                // Get the actual port from the server
+                const address = httpServer.address();
+                if (address &&
+                    typeof address === "object" &&
+                    address !== null &&
+                    "port" in address) {
+                    actualPort = address.port;
+                }
+            }
+            catch (error) {
+                // If getHttpServer fails, try to get port from app instance
+                const appWithPort = appInstance;
+                if (appWithPort.port !== undefined) {
+                    actualPort = appWithPort.port;
+                }
+            }
+        }
+        else {
+            // Fallback: try to get port from app instance directly
+            const appWithPort = appInstance;
+            if (appWithPort.port !== undefined) {
+                actualPort = appWithPort.port;
+            }
+        }
+        // Store HTTP server reference for cleanup
+        if (httpServer) {
+            testApp.setHttpServer(httpServer);
+        }
+        // Track active test apps for cleanup
+        activeTestApps.push(testApp);
+        const baseUrl = `http://localhost:${actualPort}`;
+        // Create cleanup function
+        const cleanup = async () => {
+            // Restore environment
+            Object.keys(options.env || {}).forEach((key) => {
+                if (originalEnv[key] !== undefined) {
+                    process.env[key] = originalEnv[key];
+                }
+                else {
+                    delete process.env[key];
+                }
+            });
+            // Close the app
+            await testApp.close();
+            // Remove from active apps
+            const index = activeTestApps.indexOf(testApp);
+            if (index > -1) {
+                activeTestApps.splice(index, 1);
+            }
+        };
+        // Set up auto-cleanup if enabled
+        if (options.autoCleanup !== false) {
+            // Register cleanup with test framework
+            registerCleanupHook(cleanup);
+        }
+        // Create fluent request builder
+        const requestBuilder = (0, fluent_request_js_1.createFluentRequest)(baseUrl);
+        return {
+            app: testApp,
+            container,
+            request: requestBuilder,
+            port: actualPort,
+            baseUrl,
+            cleanup,
+        };
+    }
+    catch (error) {
+        // Restore environment on error
+        process.env = originalEnv;
+        throw error;
+    }
+}
+/**
+ * Apply mock providers to the test app.
+ */
+function applyMockProviders(testApp, providers) {
+    for (const provider of providers) {
+        let mockValue;
+        if (provider.useValue !== undefined) {
+            mockValue = provider.useValue;
+        }
+        else if (provider.useFactory) {
+            mockValue = provider.useFactory();
+        }
+        else if (provider.useClass) {
+            mockValue = new provider.useClass();
+        }
+        if (mockValue !== undefined) {
+            testApp.overrideProvider(provider.provide, mockValue);
+        }
+    }
+}
+/**
+ * Try to get container from app instance.
+ */
+function getContainerFromApp(appInstance) {
+    // Try different possible container locations
+    const possiblePaths = [
+        "container",
+        "_container",
+        "appContainer",
+        "Container",
+    ];
+    for (const path of possiblePaths) {
+        const appRecord = appInstance;
+        const containerOrWrapper = appRecord[path];
+        if (containerOrWrapper) {
+            // Could be the container wrapper or the container itself
+            if ("Container" in containerOrWrapper && containerOrWrapper.Container) {
+                return containerOrWrapper.Container;
+            }
+            if (containerOrWrapper instanceof inversify_js_1.Container) {
+                return containerOrWrapper;
+            }
+        }
+    }
+    // If we can't find the container, throw helpful error
+    throw new Error("Could not find DI container on app instance. " +
+        "Make sure your app extends AppExpress and initializes the container properly.");
+}
+/**
+ * Register cleanup hook with test framework (Jest/Vitest).
+ */
+function registerCleanupHook(cleanup) {
+    const globalWithHooks = globalThis;
+    if (typeof afterAll === "function") {
+        afterAll(cleanup);
+    }
+    else if (typeof globalWithHooks.afterAll === "function") {
+        globalWithHooks.afterAll(cleanup);
+    }
+}
+/**
+ * Cleanup all active test apps.
+ * Useful for cleanup in test teardown.
+ */
+async function cleanupAllTestApps() {
+    const cleanupPromises = activeTestApps.map((app) => app.close());
+    await Promise.all(cleanupPromises);
+    activeTestApps.length = 0;
+}
+/**
+ * Get the count of active test apps.
+ * Useful for debugging test cleanup issues.
+ */
+function getActiveTestAppCount() {
+    return activeTestApps.length;
+}