feat(router): enhance route handling with named routes and parameter support

- Updated Router methods to return Route<HttpContext, Middleware, Handler> instead of void for better type safety.
- Introduced support for named routes, allowing routes to be registered with a name and accessed via Router.route(name).
- Enhanced parameter handling to support curly wrapped required and optional parameters in route definitions.
- Updated all route retrieval methods to include support for named routes.
- Added tests to validate the new functionality for named routes and parameter handling in the Express router.

Author: 3m1n3nc3

README.md

@@ -50,6 +50,8 @@ yarn add clear-router express
 - Controller handlers receive hydrated `this.body`, `this.query`, `this.params`, and `this.clearRequest`
 - `clearRequest` is passed as second handler argument for controller handlers
 - Route handlers can return response values directly across Express, Fastify, Hono, H3, and Koa
+- Laravel-style route parameters like `/books/{book}`, `/books/{book?}`, and `/books/{book:profile}`
+- Named routes with path generation via `Router.get(...).name(...)` and `Router.url(...)`
 - Optional decorated container binding for controller method arguments
 - Plugin API for registering container bindings from external packages
 - Supports TS 5.2+ standard decorators with explicit `@Bind(...)` tokens

docs/api.md

@@ -421,6 +421,22 @@ console.log(routes);
 // ]
 ```
 
+### Named Routes and Curly Wrapped Parameters
+
+Routes can be named by chaining `.name(...)` from a route registration call. Clear Router also accepts curly wrapped route parameters and converts them for each adapter:
+
+```javascript
+Router.get('/books/{book}', handler).name('books.show');
+Router.get('/books/{book?}', handler).name('books.optional');
+Router.get('/books/{book:profile}', handler).name('books.profile');
+
+Router.url('books.show', { book: 123 }); // /books/123
+Router.url('books.optional'); // /books
+Router.url('books.profile', { book: { profile: 'ada' } }); // /books/ada
+```
+
+Named routes are available through `Router.route(name)` and `Router.allRoutes('name')`.
+
 ### apply(router)
 
 Apply all registered routes to an Express Router instance.

src/Route.ts

@@ -4,6 +4,12 @@ import { ClearRequest } from './ClearRequest'
 import { Middleware as EMiddleware } from 'types/express'
 import { Middleware as HMiddleware } from 'types/h3'
 
+export interface RouteParameter {
+    name: string
+    field?: string
+    optional: boolean
+}
+
 export class Route<X = any, M = HMiddleware | EMiddleware, H = any> {
     ctx!: X
     body: RequestData = {}
@@ -13,6 +19,9 @@ export class Route<X = any, M = HMiddleware | EMiddleware, H = any> {
 
     methods: HttpMethod[]
     path: string
+    registrationPaths: string[]
+    parameters: RouteParameter[]
+    routeName?: string
     handler: H
     middlewares: M[]
     controllerName?: string
@@ -24,15 +33,59 @@ export class Route<X = any, M = HMiddleware | EMiddleware, H = any> {
         methods: HttpMethod[],
         path: string,
         handler: H,
-        middlewares: M[] = []
+        middlewares: M[] = [],
+        options: {
+            registrationPaths?: string[]
+            parameters?: RouteParameter[]
+            onName?: (name: string, route: Route<X, M, H>, previousName?: string) => void
+        } = {}
     ) {
         this.methods = methods
         this.path = path
+        this.registrationPaths = options.registrationPaths || [path]
+        this.parameters = options.parameters || []
         this.handler = handler
         this.middlewares = middlewares
         this.handlerType = Array.isArray(handler) ? 'controller' : 'function'
         this.middlewareCount = middlewares.length
         this.controllerName = Array.isArray(handler) ? handler[0]?.name : undefined
         this.actionName = Array.isArray(handler) ? handler[1] : typeof handler === 'function' ? handler.constructor.name ?? handler.name : undefined
+        this.onName = options.onName
+    }
+
+    private onName?: (name: string, route: Route<X, M, H>, previousName?: string) => void
+
+    name (name: string): this {
+        const previousName = this.routeName
+        this.routeName = name
+        this.onName?.(name, this, previousName)
+
+        return this
+    }
+
+    toPath (params: RequestData = {}): string {
+        const path = this.path.replace(/\/?\{([^{}]+)\}/g, (segment, raw: string) => {
+            const optional = raw.endsWith('?')
+            const withoutOptional = optional ? raw.slice(0, -1) : raw
+            const [rawName, rawField] = withoutOptional.split(':', 2)
+            const name = rawName.trim()
+            const field = rawField?.trim()
+            const value = params[name]
+            const resolved = field && value && typeof value === 'object'
+                ? value[field]
+                : value
+
+            if (typeof resolved === 'undefined' || resolved === null || resolved === '') {
+                if (optional) return ''
+
+                throw new Error(`Missing required route parameter: ${name}`)
+            }
+
+            const prefix = segment.startsWith('/') ? '/' : ''
+
+            return `${prefix}${encodeURIComponent(String(resolved))}`
+        })
+
+        return path || '/'
     }
-}
+}

src/core/router.ts

@@ -132,6 +132,7 @@ export abstract class CoreRouter {
             routes: [] as Array<Route<any, any, any>>,
             routesByPathMethod: {} as Record<string, Route<any, any, any>>,
             routesByMethod: {} as { [method in Uppercase<HttpMethod>]?: Array<Route<any, any, any>> },
+            routesByName: {} as Record<string, Route<any, any, any>>,
             prefix: '',
             groupMiddlewares: [] as any[],
             globalMiddlewares: [] as any[],
@@ -156,6 +157,7 @@ export abstract class CoreRouter {
             'routes',
             'routesByPathMethod',
             'routesByMethod',
+            'routesByName',
             'prefix',
             'groupMiddlewares',
             'globalMiddlewares',
@@ -341,6 +343,7 @@ export abstract class CoreRouter {
     static routes: Array<Route<any, any, any>> = []
     static routesByPathMethod: Record<string, Route<any, any, any>> = {}
     static routesByMethod: { [method in Uppercase<HttpMethod>]?: Array<Route<any, any, any>> } = {}
+    static routesByName: Record<string, Route<any, any, any>> = {}
 
     static prefix = ''
     static groupMiddlewares: any[] = []
@@ -432,6 +435,10 @@ export abstract class CoreRouter {
             this.routesByMethod = {}
         }
 
+        if (!this.routesByName || typeof this.routesByName !== 'object') {
+            this.routesByName = {}
+        }
+
         if (typeof this.prefix !== 'string') {
             this.prefix = ''
         }
@@ -459,6 +466,68 @@ export abstract class CoreRouter {
             .join('/')
     }
 
+    protected static parseRouteParameters (path: string): Array<{
+        name: string
+        field?: string
+        optional: boolean
+    }> {
+        const parameters: Array<{ name: string; field?: string; optional: boolean }> = []
+        const seen = new Set<string>()
+        const pattern = /\{([^{}]+)\}/g
+        let match: RegExpExecArray | null
+
+        while ((match = pattern.exec(path)) !== null) {
+            const raw = match[1].trim()
+            const optional = raw.endsWith('?')
+            const withoutOptional = optional ? raw.slice(0, -1) : raw
+            const [name, field] = withoutOptional.split(':', 2).map(part => part.trim())
+
+            if (!name || seen.has(name)) continue
+
+            seen.add(name)
+            parameters.push({
+                name,
+                field: field || undefined,
+                optional,
+            })
+        }
+
+        return parameters
+    }
+
+    protected static expandRoutePath (path: string): string[] {
+        let paths = ['']
+        const segments = this.normalizePath(path).split('/').filter(Boolean)
+
+        for (const segment of segments) {
+            const match = segment.match(/^\{([^{}]+)\}$/)
+
+            if (!match) {
+                paths = paths.map(current => `${current}/${segment}`)
+                continue
+            }
+
+            const raw = match[1].trim()
+            const optional = raw.endsWith('?')
+            const withoutOptional = optional ? raw.slice(0, -1) : raw
+            const [rawName] = withoutOptional.split(':', 2)
+            const name = rawName.trim()
+
+            if (!name) continue
+
+            const parameterSegment = `/:${name}`
+            paths = optional
+                ? paths.flatMap(current => [current, `${current}${parameterSegment}`])
+                : paths.map(current => `${current}${parameterSegment}`)
+        }
+
+        return paths.map(path => path || '/')
+    }
+
+    protected static routeRegistrationPaths (path: string): string[] {
+        return this.expandRoutePath(path)
+    }
+
     /**
      * Configures the router with the given options, such as method override settings.
      * 
@@ -573,7 +642,7 @@ export abstract class CoreRouter {
         path: string,
         handler: any,
         middlewares?: any[] | any
-    ): void {
+    ): Route<any, any, any> {
         this.ensureState()
 
         const context = this.groupContext.getStore()
@@ -586,12 +655,25 @@ export abstract class CoreRouter {
             : undefined
 
         const fullPath = this.normalizePath(`${activePrefix}/${path}`)
+        const registrationPaths = this.routeRegistrationPaths(fullPath)
+        const parameters = this.parseRouteParameters(fullPath)
 
         const route = new Route(
             methods.includes('options') ? methods : methods.concat('options'),
             fullPath,
             handler,
-            [...this.globalMiddlewares, ...activeGroupMiddlewares, ...(middlewares || [])]
+            [...this.globalMiddlewares, ...activeGroupMiddlewares, ...(middlewares || [])],
+            {
+                registrationPaths,
+                parameters,
+                onName: (name, route, previousName) => {
+                    if (previousName && this.routesByName[previousName] === route) {
+                        delete this.routesByName[previousName]
+                    }
+
+                    this.routesByName[name] = route
+                },
+            }
         )
 
         if (
@@ -610,6 +692,8 @@ export abstract class CoreRouter {
             }
             this.routesByMethod[method].push(route)
         }
+
+        return route
     }
 
     /**
@@ -670,8 +754,8 @@ export abstract class CoreRouter {
      * @param handler       The handler function for the GET route.
      * @param middlewares   Optional middlewares to apply to the GET route.
      */
-    static get (path: string, handler: any, middlewares?: any[] | any): void {
-        this.add('get', path, handler, middlewares)
+    static get (path: string, handler: any, middlewares?: any[] | any): Route<any, any, any> {
+        return this.add('get', path, handler, middlewares)
     }
 
     /**
@@ -682,8 +766,8 @@ export abstract class CoreRouter {
      * @param handler 
      * @param middlewares 
      */
-    static post (path: string, handler: any, middlewares?: any[] | any): void {
-        this.add('post', path, handler, middlewares)
+    static post (path: string, handler: any, middlewares?: any[] | any): Route<any, any, any> {
+        return this.add('post', path, handler, middlewares)
     }
 
     /**
@@ -694,8 +778,8 @@ export abstract class CoreRouter {
      * @param handler 
      * @param middlewares 
      */
-    static put (path: string, handler: any, middlewares?: any[] | any): void {
-        this.add('put', path, handler, middlewares)
+    static put (path: string, handler: any, middlewares?: any[] | any): Route<any, any, any> {
+        return this.add('put', path, handler, middlewares)
     }
 
     /**
@@ -706,8 +790,8 @@ export abstract class CoreRouter {
      * @param handler 
      * @param middlewares 
      */
-    static delete (path: string, handler: any, middlewares?: any[] | any): void {
-        this.add('delete', path, handler, middlewares)
+    static delete (path: string, handler: any, middlewares?: any[] | any): Route<any, any, any> {
+        return this.add('delete', path, handler, middlewares)
     }
 
     /**
@@ -718,8 +802,8 @@ export abstract class CoreRouter {
      * @param handler 
      * @param middlewares 
      */
-    static patch (path: string, handler: any, middlewares?: any[] | any): void {
-        this.add('patch', path, handler, middlewares)
+    static patch (path: string, handler: any, middlewares?: any[] | any): Route<any, any, any> {
+        return this.add('patch', path, handler, middlewares)
     }
 
     /**
@@ -730,8 +814,8 @@ export abstract class CoreRouter {
      * @param handler 
      * @param middlewares 
      */
-    static options (path: string, handler: any, middlewares?: any[] | any): void {
-        this.add('options', path, handler, middlewares)
+    static options (path: string, handler: any, middlewares?: any[] | any): Route<any, any, any> {
+        return this.add('options', path, handler, middlewares)
     }
 
     /**
@@ -742,8 +826,8 @@ export abstract class CoreRouter {
      * @param handler 
      * @param middlewares 
      */
-    static head (path: string, handler: any, middlewares?: any[] | any): void {
-        this.add('head', path, handler, middlewares)
+    static head (path: string, handler: any, middlewares?: any[] | any): Route<any, any, any> {
+        return this.add('head', path, handler, middlewares)
     }
 
     /**
@@ -814,7 +898,8 @@ export abstract class CoreRouter {
      * @param type  - 'method' to get routes organized by method
      */
     static allRoutes (type: 'method'): { [method in Uppercase<HttpMethod>]?: Array<Route<any, any, any>> }
-    static allRoutes (type?: 'method' | 'path'):
+    static allRoutes (type: 'name'): Record<string, Route<any, any, any>>
+    static allRoutes (type?: 'method' | 'path' | 'name'):
         Array<Route<any, any, any>> |
         Record<string, Route<any, any, any>> |
         Record<string, Array<Route<any, any, any>>> {
@@ -828,9 +913,23 @@ export abstract class CoreRouter {
             return this.routesByPathMethod
         }
 
+        if (type === 'name') {
+            return this.routesByName
+        }
+
         return this.routes.filter((e: Route<any, any, any>) => e.methods.length > 1 || e.methods[0] !== 'options')
     }
 
+    static route (name: string): Route<any, any, any> | undefined {
+        this.ensureState()
+
+        return this.routesByName[name]
+    }
+
+    static url (name: string, params?: Record<string, any>): string | undefined {
+        return this.route(name)?.toPath(params)
+    }
+
     protected static resolveHandler (route: Route<any, any, any>): {
         handlerFunction: ((ctx: any, req: CoreRequest) => any | Promise<any>) | null
         instance: Controller<any> | null