@morojs/moro 1.6.0 → 1.6.2

package/dist/core/routing/unified-router.js

@@ -0,0 +1,684 @@
+// Unified Router - Consolidates Intelligent Router and Core Router
+// Combines best features from both systems with zero breaking changes
+import { PathMatcher } from './path-matcher.js';
+import { ObjectPoolManager } from '../pooling/object-pool-manager.js';
+import { createFrameworkLogger } from '../logger/index.js';
+const logger = createFrameworkLogger('UnifiedRouter');
+// ===== Route Builder (Chainable API) =====
+export class RouteBuilder {
+    schema;
+    router;
+    constructor(method, path, router) {
+        this.schema = {
+            method,
+            path,
+            middleware: {},
+        };
+        this.router = router;
+    }
+    // Validation methods
+    validate(config) {
+        this.schema.validation = { ...this.schema.validation, ...config };
+        return this;
+    }
+    body(schema) {
+        if (!this.schema.validation)
+            this.schema.validation = {};
+        this.schema.validation.body = schema;
+        return this;
+    }
+    query(schema) {
+        if (!this.schema.validation)
+            this.schema.validation = {};
+        this.schema.validation.query = schema;
+        return this;
+    }
+    params(schema) {
+        if (!this.schema.validation)
+            this.schema.validation = {};
+        this.schema.validation.params = schema;
+        return this;
+    }
+    headers(schema) {
+        if (!this.schema.validation)
+            this.schema.validation = {};
+        this.schema.validation.headers = schema;
+        return this;
+    }
+    // Security methods
+    auth(config) {
+        this.schema.auth = config;
+        return this;
+    }
+    rateLimit(config) {
+        this.schema.rateLimit = config;
+        return this;
+    }
+    // Caching
+    cache(config) {
+        this.schema.cache = config;
+        return this;
+    }
+    // Custom middleware
+    before(...middleware) {
+        if (!this.schema.middleware)
+            this.schema.middleware = {};
+        const phases = this.schema.middleware;
+        phases.before = [...(phases.before || []), ...middleware];
+        return this;
+    }
+    after(...middleware) {
+        if (!this.schema.middleware)
+            this.schema.middleware = {};
+        const phases = this.schema.middleware;
+        phases.after = [...(phases.after || []), ...middleware];
+        return this;
+    }
+    transform(...middleware) {
+        if (!this.schema.middleware)
+            this.schema.middleware = {};
+        const phases = this.schema.middleware;
+        phases.transform = [...(phases.transform || []), ...middleware];
+        return this;
+    }
+    use(...middleware) {
+        return this.after(...middleware);
+    }
+    // Metadata
+    describe(description) {
+        this.schema.description = description;
+        return this;
+    }
+    tag(...tags) {
+        this.schema.tags = [...(this.schema.tags || []), ...tags];
+        return this;
+    }
+    // Terminal method
+    handler(handler) {
+        if (!handler) {
+            throw new Error('Handler is required');
+        }
+        const completeSchema = {
+            ...this.schema,
+            handler,
+        };
+        this.router.registerRoute(completeSchema);
+    }
+}
+// ===== Unified Router =====
+export class UnifiedRouter {
+    static instance = null;
+    poolManager = ObjectPoolManager.getInstance();
+    // Route storage optimized for different access patterns
+    staticRoutes = new Map(); // O(1) lookup: "GET:/api/users"
+    dynamicRoutesBySegments = new Map(); // Grouped by segment count
+    fastPathRoutes = new Set(); // Routes with no middleware
+    allRoutes = []; // For iteration/inspection
+    // Statistics
+    stats = {
+        totalRoutes: 0,
+        staticRoutes: 0,
+        dynamicRoutes: 0,
+        fastPathRoutes: 0,
+        requestCount: 0,
+        fastPathHits: 0,
+        staticHits: 0,
+        dynamicHits: 0,
+        cacheHits: 0,
+    };
+    constructor() {
+        logger.debug('UnifiedRouter initialized', 'Initialization');
+    }
+    /**
+     * Get singleton instance (optional - can still create new instances)
+     */
+    static getInstance() {
+        if (!this.instance) {
+            this.instance = new UnifiedRouter();
+            logger.info(`UnifiedRouter initialized (PID: ${process.pid})`, 'Router');
+        }
+        return this.instance;
+    }
+    /**
+     * Reset singleton (useful for testing)
+     */
+    static reset() {
+        if (this.instance) {
+            this.instance.clearAllRoutes();
+        }
+        this.instance = null;
+    }
+    /**
+     * Clear all routes (useful for testing)
+     */
+    clearAllRoutes() {
+        this.staticRoutes.clear();
+        this.dynamicRoutesBySegments.clear();
+        this.fastPathRoutes.clear();
+        this.allRoutes = [];
+        this.stats = {
+            totalRoutes: 0,
+            staticRoutes: 0,
+            dynamicRoutes: 0,
+            fastPathRoutes: 0,
+            requestCount: 0,
+            fastPathHits: 0,
+            staticHits: 0,
+            dynamicHits: 0,
+            cacheHits: 0,
+        };
+        logger.debug('UnifiedRouter routes cleared', 'Reset');
+    }
+    // ===== Route Registration =====
+    /**
+     * Register a route (internal method)
+     */
+    registerRoute(schema) {
+        // Compile path pattern
+        const compiledPath = PathMatcher.compile(schema.path);
+        // Determine if this is a fast-path route
+        const isFastPath = this.isFastPathRoute(schema);
+        // Determine execution order
+        const executionOrder = this.buildExecutionOrder(schema);
+        const route = {
+            schema,
+            compiledPath,
+            isFastPath,
+            executionOrder,
+        };
+        // Store in appropriate structures
+        if (compiledPath.isStatic) {
+            const key = `${schema.method}:${schema.path}`;
+            this.staticRoutes.set(key, route);
+            this.stats.staticRoutes++;
+        }
+        else {
+            // Group by segment count for faster matching
+            const segmentCount = compiledPath.segments;
+            if (!this.dynamicRoutesBySegments.has(segmentCount)) {
+                this.dynamicRoutesBySegments.set(segmentCount, []);
+            }
+            this.dynamicRoutesBySegments.get(segmentCount).push(route);
+            this.stats.dynamicRoutes++;
+        }
+        if (isFastPath) {
+            this.fastPathRoutes.add(route);
+            this.stats.fastPathRoutes++;
+        }
+        this.allRoutes.push(route);
+        this.stats.totalRoutes++;
+        logger.info(`Registered route: ${schema.method} ${schema.path} (PID: ${process.pid}, total: ${this.stats.totalRoutes})`, 'Registration', {
+            isStatic: compiledPath.isStatic,
+            isFastPath,
+            segments: compiledPath.segments,
+        });
+    }
+    /**
+     * Chainable API methods
+     */
+    get(path) {
+        return new RouteBuilder('GET', path, this);
+    }
+    post(path) {
+        return new RouteBuilder('POST', path, this);
+    }
+    put(path) {
+        return new RouteBuilder('PUT', path, this);
+    }
+    delete(path) {
+        return new RouteBuilder('DELETE', path, this);
+    }
+    patch(path) {
+        return new RouteBuilder('PATCH', path, this);
+    }
+    head(path) {
+        return new RouteBuilder('HEAD', path, this);
+    }
+    options(path) {
+        return new RouteBuilder('OPTIONS', path, this);
+    }
+    /**
+     * Schema-first route registration
+     */
+    route(schema) {
+        this.registerRoute(schema);
+    }
+    /**
+     * Direct API (for backward compatibility)
+     */
+    addRoute(method, path, handler, middleware = []) {
+        this.registerRoute({
+            method,
+            path,
+            handler,
+            middleware,
+        });
+    }
+    // ===== Route Matching =====
+    /**
+     * Find a matching route for the request
+     * Returns boolean (sync) for fast-path routes, Promise<boolean> for others
+     */
+    handleRequest(req, res) {
+        // PERFORMANCE: Only increment stats counter, not individual metrics in hot path
+        this.stats.requestCount++;
+        const method = req.method?.toUpperCase();
+        const path = req.path;
+        // Phase 1: No middleware, auth, validation, or rate limiting
+        // Optimized for synchronous execution when possible
+        if (this.fastPathRoutes.size > 0) {
+            for (const route of this.fastPathRoutes) {
+                if (route.schema.method === method) {
+                    // Inline parameter extraction for speed (avoid function call overhead)
+                    if (route.compiledPath.isStatic) {
+                        if (route.compiledPath.path === path) {
+                            // Static route match
+                            req.params = {};
+                            try {
+                                const result = route.schema.handler(req, res);
+                                // Check if result is a promise (optimized check)
+                                if (result && typeof result.then === 'function') {
+                                    // Async handler - return promise
+                                    return result
+                                        .then(actualResult => {
+                                        if (actualResult !== undefined && !res.headersSent) {
+                                            res.json(actualResult);
+                                        }
+                                        return true;
+                                    })
+                                        .catch(() => {
+                                        if (!res.headersSent) {
+                                            res.status(500).json({ error: 'Internal server error' });
+                                        }
+                                        return true;
+                                    });
+                                }
+                                else {
+                                    // Sync handler - handle synchronously (fastest path!)
+                                    if (result !== undefined && !res.headersSent) {
+                                        res.json(result);
+                                    }
+                                    return true;
+                                }
+                            }
+                            catch (error) {
+                                if (!res.headersSent) {
+                                    res.status(500).json({ error: 'Internal server error' });
+                                }
+                                return true;
+                            }
+                        }
+                    }
+                    else {
+                        // Dynamic route - use regex matching
+                        const pattern = route.compiledPath.pattern;
+                        if (pattern) {
+                            const matches = path.match(pattern);
+                            if (matches) {
+                                // Extract params inline (avoid function call)
+                                const params = {};
+                                const paramNames = route.compiledPath.paramNames;
+                                for (let i = 0; i < paramNames.length; i++) {
+                                    params[paramNames[i]] = matches[i + 1];
+                                }
+                                req.params = params;
+                                try {
+                                    const result = route.schema.handler(req, res);
+                                    if (result && typeof result.then === 'function') {
+                                        return result
+                                            .then(actualResult => {
+                                            if (actualResult !== undefined && !res.headersSent) {
+                                                res.json(actualResult);
+                                            }
+                                            return true;
+                                        })
+                                            .catch(() => {
+                                            if (!res.headersSent) {
+                                                res.status(500).json({ error: 'Internal server error' });
+                                            }
+                                            return true;
+                                        });
+                                    }
+                                    else {
+                                        if (result !== undefined && !res.headersSent) {
+                                            res.json(result);
+                                        }
+                                        return true;
+                                    }
+                                }
+                                catch (error) {
+                                    if (!res.headersSent) {
+                                        res.status(500).json({ error: 'Internal server error' });
+                                    }
+                                    return true;
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        // Phase 2 & 3: Non-fast-path routes (async)
+        return (async () => {
+            // Phase 2: O(1) static route lookup
+            const staticKey = `${method}:${path}`;
+            // Check pool manager cache
+            const cachedRoute = this.poolManager.getCachedRoute(staticKey);
+            if (cachedRoute) {
+                await this.executeRoute(cachedRoute, req, res, { params: {} });
+                return true;
+            }
+            const staticRoute = this.staticRoutes.get(staticKey);
+            if (staticRoute) {
+                this.poolManager.cacheRoute(staticKey, staticRoute);
+                req.params = {};
+                await this.executeRoute(staticRoute, req, res, { params: {} });
+                return true;
+            }
+            // Phase 3: Segment-based dynamic route matching
+            const segments = path.split('/').filter(s => s.length > 0);
+            const segmentCount = segments.length;
+            const candidates = this.dynamicRoutesBySegments.get(segmentCount) || [];
+            for (const route of candidates) {
+                if (route.schema.method === method) {
+                    const matchResult = PathMatcher.match(route.compiledPath, path);
+                    if (matchResult) {
+                        this.poolManager.cacheRoute(staticKey, route);
+                        await this.executeRoute(route, req, res, matchResult);
+                        return true;
+                    }
+                }
+            }
+            // No route found
+            return false;
+        })();
+    }
+    // ===== Route Execution =====
+    async executeRoute(route, req, res, matchResult) {
+        // Set params from pool
+        req.params = this.poolManager.acquireParams();
+        Object.assign(req.params, matchResult.params);
+        try {
+            // Execute middleware phases in order
+            for (const phase of route.executionOrder) {
+                if (res.headersSent)
+                    break;
+                await this.executePhase(phase, route, req, res);
+            }
+            // Execute handler
+            if (!res.headersSent) {
+                const result = await route.schema.handler(req, res);
+                if (result !== undefined && !res.headersSent) {
+                    await res.json(result);
+                }
+            }
+        }
+        catch (error) {
+            logger.error('Route execution error', 'Execution', {
+                error: error instanceof Error ? error.message : String(error),
+                route: `${route.schema.method} ${route.schema.path}`,
+            });
+            if (!res.headersSent) {
+                res.status(500).json({
+                    success: false,
+                    error: 'Internal server error',
+                    requestId: req.requestId,
+                });
+            }
+        }
+        finally {
+            // Release params back to pool
+            if (req.params) {
+                this.poolManager.releaseParams(req.params);
+            }
+        }
+    }
+    async executePhase(phase, route, req, res) {
+        const schema = route.schema;
+        const middleware = schema.middleware;
+        switch (phase) {
+            case 'before':
+                if (middleware && 'before' in middleware && Array.isArray(middleware.before)) {
+                    for (const mw of middleware.before) {
+                        await this.executeMiddleware(mw, req, res);
+                        if (res.headersSent)
+                            return;
+                    }
+                }
+                break;
+            case 'rateLimit':
+                if (schema.rateLimit) {
+                    await this.executeRateLimit(req, res, schema.rateLimit);
+                }
+                break;
+            case 'auth':
+                if (schema.auth) {
+                    await this.executeAuth(req, res, schema.auth);
+                }
+                break;
+            case 'validation':
+                if (schema.validation) {
+                    await this.executeValidation(req, res, schema.validation);
+                }
+                break;
+            case 'transform':
+                if (middleware && 'transform' in middleware && Array.isArray(middleware.transform)) {
+                    for (const mw of middleware.transform) {
+                        await this.executeMiddleware(mw, req, res);
+                        if (res.headersSent)
+                            return;
+                    }
+                }
+                break;
+            case 'cache':
+                if (schema.cache) {
+                    await this.executeCache(req, res, schema.cache);
+                }
+                break;
+            case 'after':
+                if (middleware && 'after' in middleware && Array.isArray(middleware.after)) {
+                    for (const mw of middleware.after) {
+                        await this.executeMiddleware(mw, req, res);
+                        if (res.headersSent)
+                            return;
+                    }
+                }
+                break;
+            case 'middleware':
+                // Handle array-style middleware (backward compatibility)
+                if (middleware && Array.isArray(middleware)) {
+                    for (const mw of middleware) {
+                        await this.executeMiddleware(mw, req, res);
+                        if (res.headersSent)
+                            return;
+                    }
+                }
+                break;
+        }
+    }
+    async executeMiddleware(middleware, req, res) {
+        return new Promise((resolve, reject) => {
+            let resolved = false;
+            const next = () => {
+                if (!resolved) {
+                    resolved = true;
+                    resolve();
+                }
+            };
+            try {
+                const result = middleware(req, res, next);
+                if (result instanceof Promise) {
+                    result.then(() => !resolved && next()).catch(reject);
+                }
+                else if (!resolved) {
+                    next();
+                }
+            }
+            catch (error) {
+                if (!resolved) {
+                    resolved = true;
+                    reject(error);
+                }
+            }
+        });
+    }
+    async executeRateLimit(_req, _res, _config) {
+        // Rate limiting implementation placeholder
+        // TODO: Implement actual rate limiting logic
+    }
+    async executeAuth(req, res, config) {
+        const auth = req.auth;
+        if (!auth) {
+            res.status(500).json({
+                success: false,
+                error: 'Authentication middleware not configured',
+            });
+            return;
+        }
+        if (!config.optional && !auth.isAuthenticated) {
+            res.status(401).json({
+                success: false,
+                error: 'Authentication required',
+            });
+            return;
+        }
+        if (auth.isAuthenticated && config.roles) {
+            const userRoles = auth.user?.roles || [];
+            const hasRole = config.roles.some(role => userRoles.includes(role));
+            if (!hasRole) {
+                res.status(403).json({
+                    success: false,
+                    error: 'Insufficient permissions',
+                    message: `Required roles: ${config.roles.join(', ')}`,
+                });
+                return;
+            }
+        }
+        if (auth.isAuthenticated && config.permissions) {
+            const userPermissions = auth.user?.permissions || [];
+            const hasPermission = config.permissions.every(permission => userPermissions.includes(permission));
+            if (!hasPermission) {
+                res.status(403).json({
+                    success: false,
+                    error: 'Insufficient permissions',
+                    message: `Required permissions: ${config.permissions.join(', ')}`,
+                });
+                return;
+            }
+        }
+    }
+    async executeValidation(req, res, config) {
+        try {
+            if (config.body && req.body !== undefined) {
+                req.validatedBody = await config.body.parseAsync(req.body);
+                req.body = req.validatedBody;
+            }
+            if (config.query && req.query !== undefined) {
+                req.validatedQuery = await config.query.parseAsync(req.query);
+                req.query = req.validatedQuery;
+            }
+            if (config.params && req.params !== undefined) {
+                req.validatedParams = await config.params.parseAsync(req.params);
+                req.params = req.validatedParams;
+            }
+            if (config.headers && req.headers !== undefined) {
+                req.validatedHeaders = await config.headers.parseAsync(req.headers);
+            }
+        }
+        catch (error) {
+            const field = error.field || 'unknown';
+            if (error.issues) {
+                res.status(400).json({
+                    success: false,
+                    error: `Validation failed for ${field}`,
+                    details: error.issues.map((issue) => ({
+                        field: issue.path.length > 0 ? issue.path.join('.') : field,
+                        message: issue.message,
+                        code: issue.code,
+                    })),
+                    requestId: req.requestId,
+                });
+            }
+            else {
+                res.status(400).json({
+                    success: false,
+                    error: `Validation failed for ${field}`,
+                    requestId: req.requestId,
+                });
+            }
+        }
+    }
+    async executeCache(_req, _res, _config) {
+        // Cache implementation placeholder
+        // TODO: Implement actual caching logic
+    }
+    // ===== Helper Methods =====
+    isFastPathRoute(schema) {
+        const middleware = schema.middleware;
+        const hasMiddleware = (middleware && Array.isArray(middleware) && middleware.length > 0) ||
+            (middleware &&
+                typeof middleware === 'object' &&
+                (middleware.before?.length ||
+                    middleware.after?.length ||
+                    middleware.transform?.length));
+        return (!schema.auth && !schema.validation && !schema.rateLimit && !schema.cache && !hasMiddleware);
+    }
+    buildExecutionOrder(schema) {
+        const order = [];
+        const middleware = schema.middleware;
+        // Phase-based middleware
+        if (middleware && 'before' in middleware && middleware.before?.length) {
+            order.push('before');
+        }
+        if (schema.rateLimit)
+            order.push('rateLimit');
+        if (schema.auth)
+            order.push('auth');
+        if (schema.validation)
+            order.push('validation');
+        if (middleware && 'transform' in middleware && middleware.transform?.length) {
+            order.push('transform');
+        }
+        if (schema.cache)
+            order.push('cache');
+        if (middleware && 'after' in middleware && middleware.after?.length) {
+            order.push('after');
+        }
+        // Array-style middleware (backward compatibility)
+        if (middleware && Array.isArray(middleware) && middleware.length > 0) {
+            order.push('middleware');
+        }
+        return order;
+    }
+    // ===== Inspection Methods =====
+    getAllRoutes() {
+        return this.allRoutes.map(r => r.schema);
+    }
+    getRouteCount() {
+        return this.stats.totalRoutes;
+    }
+    getStats() {
+        return {
+            ...this.stats,
+            poolManager: this.poolManager.getPerformanceSummary(),
+            pathMatcher: PathMatcher.getStats(),
+        };
+    }
+    logPerformanceStats() {
+        const stats = this.getStats();
+        logger.info('UnifiedRouter Performance', 'Stats', {
+            totalRoutes: stats.totalRoutes,
+            staticRoutes: stats.staticRoutes,
+            dynamicRoutes: stats.dynamicRoutes,
+            fastPathRoutes: stats.fastPathRoutes,
+            requests: stats.requestCount,
+            poolManager: {
+                routeCacheHitRate: stats.poolManager.routeCacheHitRate.toFixed(1) + '%',
+                responseCacheHitRate: stats.poolManager.responseCacheHitRate.toFixed(1) + '%',
+                paramPoolUtilization: stats.poolManager.paramPoolUtilization.toFixed(1) + '%',
+                totalMemoryKB: stats.poolManager.totalMemoryKB.toFixed(1) + ' KB',
+            },
+        });
+    }
+}
+//# sourceMappingURL=unified-router.js.map