@engjts/nexus 0.1.7 → 0.1.9

package/src/core/router/file-router.ts

@@ -1,594 +0,0 @@
-/**
- * File-Based Router for Nexus Framework
- * 
- * Automatically scans a directory and registers routes based on file/folder structure.
- * Designed for class-based routing: 1 file = 1 class = 1 route.
- * 
- * Smart filename conventions:
- * - `index.ts`  → GET (default), maps to parent path
- * - `create.ts` → POST, maps to parent path (not /create)
- * - `update.ts` → PUT, maps to parent path (not /update)
- * - `delete.ts` → DELETE, maps to parent path (not /delete)
- * - `patch.ts`  → PATCH, maps to parent path (not /patch)
- * - Other files → GET (or specify `method` in class)
- * 
- * @example
- * ```
- * routes/
- *   api/
- *     auth/
- *       register.ts       → POST /api/auth/register (method = 'POST' in class)
- *       login.ts          → POST /api/auth/login
- *     users/
- *       index.ts          → GET /api/users
- *       create.ts         → POST /api/users (auto!)
- *       [id]/
- *         index.ts        → GET /api/users/:id
- *         update.ts       → PUT /api/users/:id (auto!)
- *         delete.ts       → DELETE /api/users/:id (auto!)
- * ```
- * 
- * Each file exports a class:
- * ```typescript
- * export default class RegisterRoute {
- *   method = 'POST'  // Optional if filename is create/update/delete
- *   
- *   schema() { ... }
- *   meta() { ... }
- *   async handler(ctx: Context) { ... }
- * }
- * ```
- */
-
-import { readdir, stat } from 'fs/promises';
-import { join, parse, extname } from 'path';
-import { pathToFileURL } from 'url';
-import { Application } from '../application';
-import { 
-    HTTPMethod, 
-    Handler, 
-    Context, 
-    SchemaConfig, 
-    RouteMeta, 
-    Middleware,
-    RouteBase,
-    Route
-} from '../types';
-
-/**
- * Supported HTTP methods for file-based routing
- */
-const HTTP_METHODS: HTTPMethod[] = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS'];
-
-/**
- * Default HTTP method when not specified
- */
-const DEFAULT_METHOD: HTTPMethod = 'GET';
-
-/**
- * Smart filename to HTTP method mapping
- * These filenames auto-set the method AND don't become part of the route path
- */
-const SMART_FILENAME_METHODS: Record<string, HTTPMethod> = {
-    'create': 'POST',
-    'update': 'PUT', 
-    'delete': 'DELETE',
-    'patch': 'PATCH',
-    'index': 'GET'
-};
-
-/**
- * Check if filename is a "smart" filename that implies method
- */
-function isSmartFilename(filename: string): boolean {
-    return filename in SMART_FILENAME_METHODS;
-}
-
-/**
- * Get implied method from smart filename
- */
-function getSmartMethod(filename: string): HTTPMethod {
-    return SMART_FILENAME_METHODS[filename] || DEFAULT_METHOD;
-}
-
-/**
- * Options for file-based routing
- */
-export interface FileRouterOptions {
-    /** Root directory for routes (relative to project root or absolute) */
-    dir: string;
-    /** Optional prefix for all routes (e.g., '/api/v1') */
-    prefix?: string;
-    /** File extensions to scan (default: ['.ts', '.js']) */
-    extensions?: string[];
-    /** Enable debug logging */
-    debug?: boolean;
-    /** Custom middleware file name (default: '_middleware') */
-    middlewareFileName?: string;
-    /** Custom error handler file name (default: '_error') */
-    errorFileName?: string;
-}
-
-/**
- * Class-based route export (1 file = 1 class = 1 route)
- */
-export interface FileRouteClass {
-    /** HTTP method for this route (default: 'GET') */
-    method?: HTTPMethod;
-    /** Optional schema validation */
-    schema?: () => SchemaConfig;
-    /** Optional route metadata for documentation */
-    meta?: () => RouteMeta;
-    /** Optional route-specific middlewares */
-    middlewares?: () => Middleware[];
-    /** The route handler */
-    handler: Handler;
-}
-
-/**
- * Route file module export
- */
-export interface RouteModule {
-    /** Default export: the route class */
-    default?: FileRouteClass | (new () => FileRouteClass);
-}
-
-/**
- * Parsed route information
- */
-interface ParsedRoute {
-    path: string;
-    method: HTTPMethod;
-    handler: Handler;
-    middlewares: Middleware[];
-    schema?: SchemaConfig;
-    meta?: RouteMeta;
-    filePath: string;
-}
-
-/**
- * Middleware stack for directory hierarchy
- */
-interface MiddlewareStack {
-    path: string;
-    middleware: Middleware;
-}
-
-/**
- * File-based router implementation
- * 
- * Philosophy:
- * - 1 file = 1 class = 1 route
- * - Folder structure determines the path (pathName in class is IGNORED)
- * - HTTP method is defined via `method` property (default: GET)
- * - Clean, scalable, easy to navigate
- */
-export class FileRouter {
-    private options: Required<FileRouterOptions>;
-    private routes: ParsedRoute[] = [];
-    private middlewareStack: MiddlewareStack[] = [];
-
-    constructor(options: FileRouterOptions) {
-        this.options = {
-            dir: options.dir,
-            prefix: options.prefix || '',
-            extensions: options.extensions || ['.ts', '.js'],
-            debug: options.debug || false,
-            middlewareFileName: options.middlewareFileName || '_middleware',
-            errorFileName: options.errorFileName || '_error'
-        };
-    }
-
-    /**
-     * Scan directory and collect all routes
-     */
-    async scan(): Promise<ParsedRoute[]> {
-        this.routes = [];
-        this.middlewareStack = [];
-        
-        await this.scanDirectory(this.options.dir, '');
-        
-        if (this.options.debug) {
-            console.log('\n📁 File-Based Routes Discovered:');
-            console.log('─'.repeat(60));
-            for (const route of this.routes) {
-                console.log(`  ${route.method.padEnd(7)} ${route.path}`);
-                console.log(`          └─ ${route.filePath}`);
-            }
-            console.log('─'.repeat(60));
-            console.log(`  Total: ${this.routes.length} routes\n`);
-        }
-        
-        return this.routes;
-    }
-
-    /**
-     * Register all discovered routes to the application
-     */
-    async register(app: Application): Promise<void> {
-        const routes = await this.scan();
-        
-        // Get dependencies from app for injection
-        const deps = (app as any).getDeps?.() || {};
-        
-        // Get router directly to avoid double-wrapping
-        const router = (app as any).router;
-        
-        for (const route of routes) {
-            // Wrap handler to inject dependencies
-            const originalHandler = route.handler;
-            const wrappedHandler: Handler = async (ctx) => originalHandler(ctx, deps);
-            
-            // Register directly to router to avoid double-wrapping by app methods
-            router.addRoute({
-                method: route.method,
-                path: route.path,
-                handler: wrappedHandler,
-                middlewares: route.middlewares,
-                schema: route.schema,
-                meta: route.meta
-            });
-            
-            if (this.options.debug) {
-                console.log(`✅ Registered: ${route.method} ${route.path}`);
-            }
-        }
-    }
-
-    /**
-     * Recursively scan a directory for route files
-     */
-    private async scanDirectory(dirPath: string, routePath: string): Promise<void> {
-        let entries;
-        
-        try {
-            entries = await readdir(dirPath, { withFileTypes: true });
-        } catch (error) {
-            if (this.options.debug) {
-                console.warn(`⚠️  Cannot read directory: ${dirPath}`);
-            }
-            return;
-        }
-
-        // Sort entries: directories first, then files
-        entries.sort((a, b) => {
-            if (a.isDirectory() && !b.isDirectory()) return -1;
-            if (!a.isDirectory() && b.isDirectory()) return 1;
-            return a.name.localeCompare(b.name);
-        });
-
-        // First, check for _middleware file
-        const middlewareFile = entries.find(e => 
-            e.isFile() && this.isMiddlewareFile(e.name)
-        );
-        
-        if (middlewareFile) {
-            await this.loadMiddleware(join(dirPath, middlewareFile.name), routePath);
-        }
-
-        // Process all entries
-        for (const entry of entries) {
-            const fullPath = join(dirPath, entry.name);
-            
-            if (entry.isDirectory()) {
-                // Handle directory (potential route segment or dynamic param)
-                const segment = this.parseSegment(entry.name);
-                const newRoutePath = routePath + segment;
-                await this.scanDirectory(fullPath, newRoutePath);
-            } else if (entry.isFile() && this.isRouteFile(entry.name)) {
-                // Handle route file
-                await this.loadRouteFile(fullPath, routePath, entry.name);
-            }
-        }
-    }
-
-    /**
-     * Check if file is a route file (has valid extension and not special file)
-     */
-    private isRouteFile(fileName: string): boolean {
-        const ext = extname(fileName);
-        if (!this.options.extensions.includes(ext)) return false;
-        
-        const nameWithoutExt = parse(fileName).name;
-        
-        // Skip special files
-        if (nameWithoutExt.startsWith('_')) return false;
-        
-        return true;
-    }
-
-    /**
-     * Check if file is a middleware file
-     */
-    private isMiddlewareFile(fileName: string): boolean {
-        const ext = extname(fileName);
-        if (!this.options.extensions.includes(ext)) return false;
-        
-        const nameWithoutExt = parse(fileName).name;
-        return nameWithoutExt === this.options.middlewareFileName;
-    }
-
-    /**
-     * Parse directory/file name to route segment
-     */
-    private parseSegment(name: string): string {
-        // Remove file extension if present
-        const nameWithoutExt = parse(name).name;
-        
-        // Catch-all parameter: [...slug] → /*slug
-        if (nameWithoutExt.startsWith('[...') && nameWithoutExt.endsWith(']')) {
-            const paramName = nameWithoutExt.slice(4, -1);
-            return `/*${paramName}`;
-        }
-        
-        // Optional catch-all: [[...slug]] → /*slug?
-        if (nameWithoutExt.startsWith('[[...') && nameWithoutExt.endsWith(']]')) {
-            const paramName = nameWithoutExt.slice(5, -2);
-            return `/*${paramName}?`;
-        }
-        
-        // Dynamic parameter: [id] → /:id
-        if (nameWithoutExt.startsWith('[') && nameWithoutExt.endsWith(']')) {
-            const paramName = nameWithoutExt.slice(1, -1);
-            return `/:${paramName}`;
-        }
-        
-        // Optional parameter: [[id]] → /:id?
-        if (nameWithoutExt.startsWith('[[') && nameWithoutExt.endsWith(']]')) {
-            const paramName = nameWithoutExt.slice(2, -2);
-            return `/:${paramName}?`;
-        }
-        
-        // Regular segment
-        return `/${nameWithoutExt}`;
-    }
-
-    /**
-     * Build the final route path from folder structure
-     */
-    private buildRoutePath(basePath: string, fileName: string): string {
-        const nameWithoutExt = parse(fileName).name;
-        
-        // Build final route path
-        // Smart filenames (index, create, update, delete, patch) don't add to path
-        let routePath = basePath;
-        if (!isSmartFilename(nameWithoutExt)) {
-            routePath += this.parseSegment(fileName);
-        }
-        
-        // Apply prefix
-        if (this.options.prefix) {
-            routePath = this.options.prefix + routePath;
-        }
-        
-        // Ensure path starts with /
-        if (!routePath.startsWith('/')) {
-            routePath = '/' + routePath;
-        }
-        
-        // Normalize double slashes
-        routePath = routePath.replace(/\/+/g, '/');
-        
-        // Remove trailing slash (except for root)
-        if (routePath.length > 1 && routePath.endsWith('/')) {
-            routePath = routePath.slice(0, -1);
-        }
-        
-        return routePath;
-    }
-
-    /**
-     * Load a route file and extract the route class
-     */
-    private async loadRouteFile(filePath: string, basePath: string, fileName: string): Promise<void> {
-        // Build route path from folder structure (this is the ONLY source of truth)
-        const routePath = this.buildRoutePath(basePath, fileName);
-        const nameWithoutExt = parse(fileName).name;
-
-        try {
-            // Import the file
-            const fileUrl = pathToFileURL(filePath).href;
-            const module = await import(fileUrl) as RouteModule;
-            
-            // Must have a default export
-            if (!module.default) {
-                if (this.options.debug) {
-                    console.warn(`⚠️  No default export in: ${filePath}`);
-                }
-                return;
-            }
-            
-            // Instantiate if it's a class constructor
-            let route: Route | FileRouteClass;
-            if (typeof module.default === 'function' && module.default.prototype) {
-                route = new (module.default as new () => Route)();
-            } else {
-                route = module.default as Route;
-            }
-            
-            // ⚠️ ENFORCE: Route class MUST extend Route abstract class
-            if (!(route instanceof Route)) {
-                const className = (route as any).constructor?.name || 'Unknown';
-                throw new Error(
-                    `Route class "${className}" in ${filePath} must extend the Route abstract class.\n` +
-                    `Example:\n` +
-                    `  import { Route } from 'nexus';\n` +
-                    `  export default class ${className} extends Route {\n` +
-                    `    async handler(ctx) { ... }\n` +
-                    `  }`
-                );
-            }
-            
-            // Must have a handler (guaranteed by Route abstract class, but double-check)
-            if (typeof route.handler !== 'function') {
-                if (this.options.debug) {
-                    console.warn(`⚠️  No handler method in: ${filePath}`);
-                }
-                return;
-            }
-            
-            // Determine HTTP method:
-            // 1. If class explicitly defines method → use it
-            // 2. If filename is smart (create/update/delete/patch/index) → auto-detect
-            // 3. Otherwise → default GET
-            let method: HTTPMethod;
-            if (route.method) {
-                // Handle both single method and array of methods (use first one for file-based routing)
-                method = Array.isArray(route.method) ? route.method[0] : route.method;
-            } else if (isSmartFilename(nameWithoutExt)) {
-                method = getSmartMethod(nameWithoutExt);
-            } else {
-                method = DEFAULT_METHOD;
-            }
-            
-            // Validate method
-            if (!HTTP_METHODS.includes(method)) {
-                if (this.options.debug) {
-                    console.warn(`⚠️  Invalid method "${method}" in: ${filePath}`);
-                }
-                return;
-            }
-            
-            // Get middlewares that apply to this route
-            const applicableMiddlewares = this.getApplicableMiddlewares(basePath);
-            
-            // Add route-specific middlewares
-            const routeMiddlewares = route.middlewares?.() || [];
-            const allMiddlewares = [...applicableMiddlewares, ...routeMiddlewares];
-            
-            // Wrap handler with lifecycle hooks support
-            // Note: Dependencies will be injected in register() method
-            const routeInstance = route as Route;
-            const hasHooks = typeof routeInstance.onBefore === 'function' || 
-                             typeof routeInstance.onAfter === 'function' || 
-                             typeof routeInstance.onError === 'function';
-
-            let finalHandler: Handler;
-
-            if (hasHooks) {
-                const boundOriginalHandler = route.handler.bind(route);
-                const onBefore = routeInstance.onBefore?.bind(route);
-                const onAfter = routeInstance.onAfter?.bind(route);
-                const onError = routeInstance.onError?.bind(route);
-
-                // Handler receives (ctx, deps) - deps passed from register()
-                finalHandler = async (ctx: Context, deps: any) => {
-                    try {
-                        // Run onBefore hook with deps
-                        if (onBefore) {
-                            const beforeResult = await onBefore(ctx, deps);
-                            // If onBefore returns a value (not undefined), skip handler
-                            if (beforeResult !== undefined) {
-                                return beforeResult;
-                            }
-                        }
-
-                        // Run the main handler with deps
-                        let result = await boundOriginalHandler(ctx, deps);
-
-                        // Run onAfter hook with deps
-                        if (onAfter) {
-                            result = await onAfter(ctx, result, deps);
-                        }
-
-                        return result;
-                    } catch (error) {
-                        // Run onError hook if defined with deps
-                        if (onError) {
-                            return await onError(ctx, error as Error, deps);
-                        }
-                        // Re-throw if no onError handler
-                        throw error;
-                    }
-                };
-            } else {
-                // No hooks - just bind handler (deps will be passed in register())
-                finalHandler = route.handler.bind(route);
-            }
-            
-            // Register the route
-            this.routes.push({
-                path: routePath,
-                method,
-                handler: finalHandler,
-                middlewares: allMiddlewares,
-                schema: route.schema?.(),
-                meta: route.meta?.(),
-                filePath
-            });
-            
-        } catch (error) {
-            if (this.options.debug) {
-                console.error(`❌ Failed to load route: ${filePath}`, error);
-            }
-        }
-    }
-
-    /**
-     * Load middleware from a _middleware file
-     */
-    private async loadMiddleware(filePath: string, routePath: string): Promise<void> {
-        try {
-            const fileUrl = pathToFileURL(filePath).href;
-            const module = await import(fileUrl);
-            
-            const middleware = module.default || module.middleware;
-            
-            if (typeof middleware === 'function') {
-                this.middlewareStack.push({
-                    path: routePath,
-                    middleware
-                });
-                
-                if (this.options.debug) {
-                    console.log(`📦 Loaded middleware for: ${routePath || '/'}`);
-                }
-            }
-        } catch (error) {
-            if (this.options.debug) {
-                console.error(`❌ Failed to load middleware: ${filePath}`, error);
-            }
-        }
-    }
-
-    /**
-     * Get middlewares that apply to a given route path
-     */
-    private getApplicableMiddlewares(routePath: string): Middleware[] {
-        return this.middlewareStack
-            .filter(m => routePath.startsWith(m.path))
-            .map(m => m.middleware);
-    }
-}
-
-/**
- * Create a file router instance
- */
-export function createFileRouter(options: FileRouterOptions): FileRouter {
-    return new FileRouter(options);
-}
-
-/**
- * Extension method for Application to use file-based routing
- * This will be called to register routes from a directory
- * 
- * @example
- * ```typescript
- * const app = createApp();
- * 
- * await app.useFileRoutes({
- *   dir: './src/routes',
- *   prefix: '',
- *   debug: true
- * });
- * 
- * app.listen(3000);
- * ```
- */
-export async function useFileRoutes(
-    app: Application,
-    options: FileRouterOptions
-): Promise<void> {
-    const router = new FileRouter(options);
-    await router.register(app);
-}