feat: support async callbacks in Router.group method and add tests for async grouped routes

Author: 3m1n3nc3

CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.1.2] - [2.1.5] - 2026-03-03
+
+### Added
+
+- Added support for async group callbacks in Express and H3 routers (`await Router.group(...)`).
+
 ## [2.1.1] - 2026-03-03
 
 ### Added
@@ -231,7 +237,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Optimized route registration performance
 
-## [1.0.0] - 2024-11-01
+## [1.0.0] (New API) - 2024-11-01
 
 ### Added
 

docs/API.md

@@ -207,9 +207,11 @@ Group routes under a common prefix with optional middlewares.
 **Parameters:**
 
 - `prefix` (string): URL prefix for all routes in the group
-- `callback` (Function): Function containing route definitions
+- `callback` (Function): Sync or async function containing route definitions
 - `middlewares` (Function[]): Optional middleware functions
 
+**Returns:** Promise<void>
+
 **Example:**
 
 ```javascript
@@ -222,6 +224,12 @@ Router.group(
   [apiMiddleware],
 );
 
+// Async group callback
+await Router.group('/api', async () => {
+  await loadRoutes();
+  Router.get('/status', handler); // Becomes: /api/status
+});
+
 // Nested groups
 Router.group('/api', () => {
   Router.group('/v1', () => {

docs/EXPRESS.md

@@ -182,6 +182,15 @@ Router.group('/admin', () => {
 });
 ```
 
+Async group callbacks are also supported:
+
+```javascript
+await Router.group('/api', async () => {
+  await loadRoutes();
+  Router.get('/status', ({ res }) => res.json({ ok: true }));
+});
+```
+
 With middleware:
 
 ```javascript

docs/H3.md

@@ -177,6 +177,15 @@ Router.group('/admin', () => {
 });
 ```
 
+Async group callbacks are also supported:
+
+```javascript
+await Router.group('/api', async () => {
+  await loadRoutes();
+  Router.get('/status', () => ({ ok: true }));
+});
+```
+
 With middleware:
 
 ```javascript

package.json

@@ -1,6 +1,6 @@
 {
     "name": "clear-router",
-    "version": "2.1.4",
+    "version": "2.1.5",
     "description": "Laravel-style routing system for Express.js and H3, with CommonJS, ESM, and TypeScript support",
     "keywords": [
         "h3",

src/express/router.ts

@@ -180,7 +180,11 @@ export class Router {
      * @param callback - Function containing route definitions
      * @param middlewares - Middleware functions applied to all routes in group
      */
-    static group (prefix: string, callback: () => void, middlewares?: Middleware[]): void {
+    static async group (
+        prefix: string,
+        callback: () => void | Promise<void>,
+        middlewares?: Middleware[]
+    ): Promise<void> {
         const previousPrefix = this.prefix
         const previousMiddlewares = this.groupMiddlewares
 
@@ -191,10 +195,12 @@ export class Router {
         this.prefix = this.normalizePath(fullPrefix)
         this.groupMiddlewares = [...previousMiddlewares, ...(middlewares || [])]
 
-        callback()
-
-        this.prefix = previousPrefix
-        this.groupMiddlewares = previousMiddlewares
+        try {
+            await Promise.resolve(callback())
+        } finally {
+            this.prefix = previousPrefix
+            this.groupMiddlewares = previousMiddlewares
+        }
     }
 
     /**

src/h3/router.ts

@@ -179,7 +179,11 @@ export class Router {
      * @param callback - Function containing route definitions
      * @param middlewares - Middleware functions applied to all routes in group
      */
-    static group (prefix: string, callback: () => void, middlewares?: Middleware[]): void {
+    static async group (
+        prefix: string,
+        callback: () => void | Promise<void>,
+        middlewares?: Middleware[]
+    ): Promise<void> {
         const previousPrefix = this.prefix
         const previousMiddlewares = this.groupMiddlewares
 
@@ -190,10 +194,12 @@ export class Router {
         this.prefix = this.normalizePath(fullPrefix)
         this.groupMiddlewares = [...previousMiddlewares, ...(middlewares || [])]
 
-        callback()
-
-        this.prefix = previousPrefix
-        this.groupMiddlewares = previousMiddlewares
+        try {
+            await Promise.resolve(callback())
+        } finally {
+            this.prefix = previousPrefix
+            this.groupMiddlewares = previousMiddlewares
+        }
     }
 
     /**

tests/typescript.test.ts

@@ -202,6 +202,21 @@ describe('Express Routing - TypeScript', () => {
         expect(response.body.status).toBe('operational')
     })
 
+    test('should support async grouped routes', async () => {
+        await Router.group('/api', async () => {
+            await new Promise<void>(resolve => setTimeout(resolve, 5))
+            Router.get('/async-group', ({ res }: HttpContext) => {
+                res.json({ grouped: true })
+            })
+        })
+
+        await setupApp()
+
+        const response = await request(app).get('/api/async-group')
+        expect(response.status).toBe(200)
+        expect(response.body.grouped).toBe(true)
+    })
+
     test('should handle typed error in middleware', async () => {
         const errorMiddleware = (
             req: Request,
@@ -436,6 +451,22 @@ describe('H3 Routing - TypeScript', () => {
         expect(response.status).toBe('operational')
     })
 
+    test('should support async grouped routes', async () => {
+        await H3Router.group('/api', async () => {
+            await new Promise<void>(resolve => setTimeout(resolve, 5))
+            H3Router.get('/async-group', () => {
+                return { grouped: true }
+            })
+        })
+
+        setupApp()
+
+        const response = await router
+            .fetch(new global.Request(new URL('http://localhost/api/async-group'), { method: 'GET' }))
+            .then(res => res.json())
+        expect(response.grouped).toBe(true)
+    })
+
     test('should handle typed error in middleware', async () => {
         const errorMiddleware = (): void => {
             throw new HTTPError('Middleware error', { status: 500 })