@coherent.js/api 1.0.0-beta.2

package/dist/api/router.d.ts

@@ -0,0 +1,368 @@
+/**
+ * Creates an object-based router from nested route definitions
+ *
+ * @param {Object} routes - Nested route definition object
+ * @param {Object} options - Router options (corsOrigin, rateLimit, maxBodySize)
+ * @returns {Object} Configured router instance
+ *
+ * @example
+ * const routes = {
+ *   api: {
+ *     users: {
+ *       get: { handler: () => ({ users: [] }) },
+ *       post: {
+ *         validation: userSchema,
+ *         handler: (req) => ({ user: req.body })
+ *       }
+ *     }
+ *   }
+ * };
+ *
+ * const router = createObjectRouter(routes, {
+ *   corsOrigin: 'https://myapp.com',
+ *   rateLimit: { windowMs: 60000, maxRequests: 50 }
+ * });
+ * const server = router.createServer();
+ * server.listen(3000);
+ */
+/**
+ * Factory function to create a SimpleRouter instance
+ *
+ * @param {Object} options - Router options
+ * @returns {SimpleRouter} Router instance
+ */
+export function createSimpleRouter(options?: Object): SimpleRouter;
+export function createObjectRouter(routeConfig: any, options?: {}): SimpleRouter;
+export default createObjectRouter;
+/**
+ * Simple router implementation for object-based routing with WebSocket support
+ *
+ * @class SimpleRouter
+ * @description Provides HTTP and WebSocket routing with middleware support, caching,
+ * versioning, content negotiation, and performance metrics.
+ *
+ * @param {Object} [options={}] - Router configuration options
+ * @param {number} [options.maxCacheSize=1000] - Maximum cache size for route lookups
+ * @param {boolean} [options.enableCompilation=true] - Enable route pattern compilation
+ * @param {boolean} [options.enableVersioning=false] - Enable API versioning
+ * @param {string} [options.defaultVersion='v1'] - Default API version
+ * @param {string} [options.versionHeader='api-version'] - Header for version detection
+ * @param {boolean} [options.enableContentNegotiation=true] - Enable content type negotiation
+ * @param {string} [options.defaultContentType='application/json'] - Default response content type
+ * @param {boolean} [options.enableWebSockets=false] - Enable WebSocket routing
+ * @param {boolean} [options.enableMetrics=false] - Enable performance metrics collection
+ *
+ * @example
+ * const router = new SimpleRouter({
+ *   enableWebSockets: true,
+ *   enableMetrics: true,
+ *   maxCacheSize: 2000
+ * });
+ */
+export class SimpleRouter {
+    constructor(options?: {});
+    routes: any[];
+    routeCache: Map<any, any>;
+    namedRoutes: Map<any, any>;
+    maxCacheSize: any;
+    routeGroups: any[];
+    globalMiddleware: any[];
+    enableCompilation: boolean;
+    compiledRoutes: Map<any, any>;
+    routeCompilationCache: Map<any, any>;
+    enableVersioning: any;
+    defaultVersion: any;
+    versionHeader: any;
+    versionedRoutes: Map<any, any>;
+    enableContentNegotiation: boolean;
+    defaultContentType: any;
+    enableWebSockets: any;
+    wsRoutes: any[];
+    wsConnections: Map<any, any>;
+    enableMetrics: any;
+    metrics: {
+        requests: number;
+        cacheHits: number;
+        compilationHits: number;
+        routeMatches: Map<any, any>;
+        responseTime: never[];
+        errors: number;
+        versionRequests: Map<any, any>;
+        contentTypeRequests: Map<any, any>;
+        wsConnections: number;
+        wsMessages: number;
+    } | undefined;
+    /**
+     * Add an HTTP route to the router
+     *
+     * @param {string} method - HTTP method (GET, POST, PUT, DELETE, PATCH)
+     * @param {string} path - Route path pattern (supports :param and wildcards)
+     * @param {Function} handler - Route handler function
+     * @param {Object} [options={}] - Route options
+     * @param {Array} [options.middleware] - Route-specific middleware
+     * @param {string} [options.name] - Named route for URL generation
+     * @param {string} [options.version] - API version for this route
+     *
+     * @example
+     * router.addRoute('GET', '/users/:id', (req, res) => {
+     *   return { user: { id: req.params.id } };
+     * }, { name: 'getUser', version: 'v2' });
+     */
+    addRoute(method: string, path: string, handler: Function, options?: {
+        middleware?: any[] | undefined;
+        name?: string | undefined;
+        version?: string | undefined;
+    }): void;
+    /**
+     * Add a versioned route
+     * @param {string} version - API version (e.g., 'v1', 'v2')
+     * @param {string} method - HTTP method
+     * @param {string} path - Route path
+     * @param {Function} handler - Route handler
+     * @param {Object} options - Route options
+     */
+    addVersionedRoute(version: string, method: string, path: string, handler: Function, options?: Object): void;
+    /**
+     * Add route with content negotiation support
+     * @param {string} method - HTTP method
+     * @param {string} path - Route path
+     * @param {Object} handlers - Content type handlers { 'application/json': handler, 'text/xml': handler }
+     * @param {Object} options - Route options
+     */
+    addContentNegotiatedRoute(method: string, path: string, handlers: Object, options?: Object): void;
+    /**
+     * Negotiate content type based on Accept header
+     * @param {Object} req - Request object
+     * @param {Array} supportedTypes - Array of supported content types
+     * @returns {string} Best matching content type
+     * @private
+     */
+    private negotiateContentType;
+    /**
+     * Convert object to XML string
+     * @param {Object} obj - Object to convert
+     * @param {string} rootName - Root element name
+     * @returns {string} XML string
+     * @private
+     */
+    private objectToXml;
+    /**
+     * Add WebSocket route
+     * @param {string} path - WebSocket path
+     * @param {Function} handler - WebSocket handler function
+     * @param {Object} options - Route options
+     */
+    addWebSocketRoute(path: string, handler: Function, options?: Object): void;
+    /**
+     * Handle WebSocket upgrade request
+     * @param {Object} request - HTTP request object
+     * @param {Object} socket - Socket object
+     * @param {Buffer} head - First packet of the upgraded stream
+     */
+    handleWebSocketUpgrade(request: Object, socket: Object, head: Buffer): void;
+    /**
+     * Create WebSocket connection
+     * @param {Object} request - HTTP request object
+     * @param {Object} socket - Socket object
+     * @param {Buffer} head - First packet of the upgraded stream
+     * @param {Object} matchedRoute - Matched WebSocket route
+     * @private
+     */
+    private createWebSocketConnection;
+    /**
+     * Create WebSocket wrapper with message handling
+     * @param {Object} socket - Raw socket
+     * @param {Object} matchedRoute - Matched route info
+     * @returns {Object} WebSocket wrapper
+     * @private
+     */
+    private createWebSocketWrapper;
+    /**
+     * Parse WebSocket frame
+     * @param {Buffer} buffer - Raw frame data
+     * @returns {string|null} Parsed message
+     * @private
+     */
+    private parseWebSocketFrame;
+    /**
+     * Broadcast message to all WebSocket connections on a path
+     * @param {string} path - WebSocket path pattern
+     * @param {*} message - Message to broadcast
+     * @param {string} [excludeId=null] - Connection ID to exclude from broadcast
+     */
+    broadcast(path: string, message: any, excludeId?: string): void;
+    /**
+     * Get active WebSocket connections
+     * @returns {Array} Array of connection info
+     */
+    getWebSocketConnections(): any[];
+    /**
+     * Get version from request
+     * @param {Object} req - Request object
+     * @returns {string} API version
+     * @private
+     */
+    private getRequestVersion;
+    /**
+     * Generate URL for named route with parameter substitution
+     *
+     * @param {string} name - Route name (set during route registration)
+     * @param {Object} [params={}] - Parameters to substitute in the URL pattern
+     * @returns {string} Generated URL with parameters substituted
+     * @throws {Error} If named route is not found
+     *
+     * @example
+     * // Route registered as: router.addRoute('GET', '/users/:id', handler, { name: 'getUser' })
+     * const url = router.url('getUser', { id: 123 }); // '/users/123'
+     *
+     * // With constrained parameters
+     * const url = router.url('getUserPosts', { userId: 123, postId: 456 }); // '/users/123/posts/456'
+     */
+    generateUrl(name: string, params?: Object): string;
+    /**
+     * Add routes from configuration object
+     *
+     * @param {Object} routeConfig - Route configuration object with nested structure
+     * @description Processes nested route objects and registers HTTP and WebSocket routes.
+     * Supports declarative route definition with automatic method detection.
+     *
+     * @example
+     * router.addRoutes({
+     *   'api': {
+     *     'users': {
+     *       GET: (req, res) => ({ users: [] }),
+     *       POST: (req, res) => ({ created: true })
+     *     }
+     *   }
+     * });
+     */
+    addRoutes(routeConfig: Object): void;
+    /**
+     * Add global middleware to the router
+     *
+     * @param {Function|Object} middleware - Middleware function or conditional middleware object
+     * @description Adds middleware that runs before all route handlers. Supports both
+     * simple functions and conditional middleware objects.
+     *
+     * @example
+     * // Simple middleware
+     * router.use((req, res) => {
+     *   console.log(`${req.method} ${req.url}`);
+     * });
+     *
+     * // Conditional middleware
+     * router.use({
+     *   condition: (req) => req.url.startsWith('/api'),
+     *   middleware: authMiddleware,
+     *   name: 'apiAuth'
+     * });
+     */
+    use(middleware: Function | Object): void;
+    /**
+     * Create conditional middleware wrapper
+     * @param {Object} config - Conditional middleware configuration
+     * @returns {Function} Wrapped middleware function
+     * @private
+     */
+    private createConditionalMiddleware;
+    /**
+     * Evaluate condition object
+     * @param {Object} condition - Condition object
+     * @param {Object} req - Request object
+     * @param {Object} res - Response object
+     * @returns {boolean} Whether condition is met
+     * @private
+     */
+    private evaluateConditionObject;
+    /**
+     * Match condition value
+     * @param {*} actual - Actual value
+     * @param {*} expected - Expected value or condition
+     * @returns {boolean} Whether condition matches
+     * @private
+     */
+    private matchCondition;
+    /**
+     * Create a route group with shared middleware and prefix
+     * @param {string} prefix - Path prefix for the group
+     * @param {Function|Array} middleware - Shared middleware
+     * @param {Function} callback - Function to define routes in the group
+     */
+    group(prefix: string, middleware: Function | any[], callback: Function): this;
+    /**
+     * Get current route prefix from active groups
+     * @private
+     */
+    private getCurrentPrefix;
+    /**
+     * Get current group middleware
+     * @private
+     */
+    private getCurrentGroupMiddleware;
+    /**
+     * Compile route pattern into optimized regex
+     * @param {string} pattern - Route pattern to compile
+     * @returns {Object} Compiled route object with regex and parameter names
+     * @private
+     */
+    private compileRoute;
+    /**
+     * Match path using compiled route
+     * @param {Object} compiledRoute - Compiled route object
+     * @param {string} path - Path to match
+     * @returns {Object|null} Parameters object or null if no match
+     * @private
+     */
+    private matchCompiledRoute;
+    /**
+     * Get performance metrics
+     * @returns {Object} Performance metrics object
+     */
+    getMetrics(): Object;
+    /**
+     * Get compilation statistics
+     * @returns {Object} Compilation statistics
+     */
+    getCompilationStats(): Object;
+    /**
+     * Clear route cache (useful for development)
+     */
+    clearCache(): void;
+    /**
+     * Clear compilation cache
+     */
+    clearCompilationCache(): void;
+    /**
+     * Get all registered routes with detailed information
+     * @returns {Array} Array of route information objects
+     */
+    getRoutes(): any[];
+    /**
+     * Find routes matching a pattern or method
+     * @param {Object} criteria - Search criteria
+     * @returns {Array} Matching routes
+     */
+    findRoutes(criteria?: Object): any[];
+    /**
+     * Test route matching without executing handlers
+     * @param {string} method - HTTP method
+     * @param {string} path - Path to test
+     * @returns {Object} Match result with route info and extracted parameters
+     */
+    testRoute(method: string, path: string): Object;
+    /**
+     * Get router debug information
+     * @returns {Object} Comprehensive debug information
+     */
+    getDebugInfo(): Object;
+    handle(req: any, res: any, options?: {}): Promise<void>;
+    createServer(options?: {}): import("http").Server<typeof import("http").IncomingMessage, typeof import("http").ServerResponse>;
+    get(path: any, handler: any, options?: {}): void;
+    post(path: any, handler: any, options?: {}): void;
+    put(path: any, handler: any, options?: {}): void;
+    patch(path: any, handler: any, options?: {}): void;
+    delete(path: any, handler: any, options?: {}): void;
+    options(path: any, handler: any, options?: {}): void;
+    head(path: any, handler: any, options?: {}): void;
+}
+//# sourceMappingURL=router.d.ts.map

package/dist/api/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../../../src/api/router.js"],"names":[],"mappings":"AAqmDA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;;;;;GAKG;AACH,6CAHW,MAAM,GACJ,YAAY,CAIxB;AAED,iFASC;;AAx0CD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH;IACE,0BA4CC;IA3CC,cAAgB;IAChB,0BAA2B;IAC3B,2BAA4B;IAC5B,kBAAgD;IAChD,mBAAqB;IACrB,wBAA0B;IAG1B,2BAA4D;IAC5D,8BAA+B;IAC/B,qCAAsC;IAGtC,sBAAyD;IACzD,oBAAoD;IACpD,mBAA2D;IAC3D,+BAAgC;IAGhC,kCAA0E;IAC1E,wBAA0E;IAG1E,sBAAyD;IACzD,gBAAkB;IAClB,6BAA8B;IAG9B,mBAAmD;IAEjD;;;;;;;;;;;kBAWC;IAIL;;;;;;;;;;;;;;;OAeG;IACH,iBAbW,MAAM,QACN,MAAM,+BAGd;QAAwB,UAAU;QACT,IAAI;QACJ,OAAO;KAEhC,QA2CF;IAED;;;;;;;OAOG;IACH,2BANW,MAAM,UACN,MAAM,QACN,MAAM,+BAEN,MAAM,QAIhB;IAED;;;;;;OAMG;IACH,kCALW,MAAM,QACN,MAAM,YACN,MAAM,YACN,MAAM,QAwChB;IAED;;;;;;OAMG;IACH,6BAiCC;IAED;;;;;;OAMG;IACH,oBA6BC;IAED;;;;;OAKG;IACH,wBAJW,MAAM,+BAEN,MAAM,QAuBhB;IAED;;;;;OAKG;IACH,gCAJW,MAAM,UACN,MAAM,QACN,MAAM,QAmChB;IAED;;;;;;;OAOG;IACH,kCAuEC;IAED;;;;;;OAMG;IACH,+BAoGC;IAED;;;;;OAKG;IACH,4BA+CC;IAED;;;;;OAKG;IACH,gBAJW,MAAM,WACN,GAAC,cACD,MAAM,QAahB;IAED;;;OAGG;IACH,iCAOC;IAED;;;;;OAKG;IACH,0BAkBC;IAED;;;;;;;;;;;;;;OAcG;IACH,kBAZW,MAAM,WACN,MAAM,GACJ,MAAM,CA0BlB;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,uBAdW,MAAM,QAgBhB;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,gBAjBW,WAAS,MAAM,QAwBzB;IAED;;;;;OAKG;IACH,oCAsBC;IAED;;;;;;;OAOG;IACH,gCAsCC;IAED;;;;;;OAMG;IACH,uBAcC;IAED;;;;;OAKG;IACH,cAJW,MAAM,cACN,gBAAc,4BAcxB;IAED;;;OAGG;IACH,yBAEC;IAED;;;OAGG;IACH,kCAEC;IAED;;;;;OAKG;IACH,qBAuDC;IAED;;;;;;OAMG;IACH,2BAcC;IAED;;;OAGG;IACH,cAFa,MAAM,CAiBlB;IAED;;;OAGG;IACH,uBAFa,MAAM,CAclB;IAED;;OAEG;IACH,mBAEC;IAED;;OAEG;IACH,8BAEC;IAED;;;OAGG;IACH,mBAWC;IAED;;;;OAIG;IACH,sBAHW,MAAM,SAkBhB;IAED;;;;;OAKG;IACH,kBAJW,MAAM,QACN,MAAM,GACJ,MAAM,CAiClB;IAED;;;OAGG;IACH,gBAFa,MAAM,CAoClB;IAED,wDAyJC;IAED,+HAGC;IAGD,iDAEC;IAED,kDAEC;IAED,iDAEC;IAED,mDAEC;IAED,oDAEC;IAED,qDAEC;IAED,kDAEC;CACF"}