feat(routing): add route groups (#147)

* chore: extract reusable modern routing internals

* feat: add route group contract

* feat: normalize grouped route sources

* feat: apply route group overlays

* feat: support route groups in app config

* chore: cover grouped route boot paths

* chore: add grouped route e2e coverage

* fix: normalize root route group prefixes

Author: imdhemy

src/Config/types.ts

@@ -1,7 +1,7 @@
 import { type HttpMiddleware } from '@/Http';
 import { type StaticFilesOptions } from '@/Http/Files';
 import { type EventSubscriber } from '@/Kernel';
-import type { RouteDefinition } from '@/routing/route-definition';
+import type { RouteSource } from '@/routing/route-source';
 
 /**
  * @deprecated Use function-first routes from `@koala-ts/framework/routing` with `KoalaConfig.routes` instead.
@@ -13,7 +13,7 @@ export interface KoalaConfig {
    * @deprecated Use `routes` with `Route` from `@koala-ts/framework/routing` instead.
    */
   controllers: Controller[];
-  routes?: RouteDefinition[];
+  routes?: RouteSource[];
   globalMiddleware?: HttpMiddleware[];
   staticFiles?: StaticFilesOptions;
   eventSubscribers?: Record<string, EventSubscriber | EventSubscriber[]>;

src/application/create-application.test.ts

@@ -1,6 +1,6 @@
 import { create } from '@/application/create-application';
 import { koalaDefaultConfig } from '@/Config';
-import { Route } from '@/routing';
+import { Get, Route, RouteGroup } from '@/routing';
 import { exclusiveRoutingModeError } from '@/routing/verify-routing-mode';
 import { expect, test } from 'vitest';
 
@@ -27,6 +27,26 @@ test('create app with explicit routes', () => {
   expect(app).toBeDefined();
 });
 
+test('create app with grouped routes', () => {
+  const app = create({
+    ...koalaDefaultConfig,
+    routes: [
+      RouteGroup(
+        {
+          prefix: '/api',
+        },
+        () => [
+          Get('/users', async scope => {
+            scope.response.body = [];
+          }),
+        ],
+      ),
+    ],
+  });
+
+  expect(app).toBeDefined();
+});
+
 test('it rejects mixing legacy controllers and explicit routes', () => {
   class LegacyController {}
 

src/routing/create-route-definition.ts

@@ -1,6 +1,7 @@
 import type { HttpMiddleware } from '@/Http';
 import type { HttpMethod } from '@/routing/http-method';
 import type { RouteOptions } from '@/routing/route-options';
+import { resolveRouteOptions } from '@/routing/resolve-route-options';
 import type { RouterMethod } from '@/routing/router-method';
 import type { RouteDefinition } from './route-definition';
 
@@ -21,14 +22,15 @@ export function createRouteDefinition({
   middleware = [],
   options = {},
 }: RouteDefinitionInput): RouteDefinition {
+  const routeOptions = resolveRouteOptions(options);
+
   return {
     name,
     path,
     methods: qualifyMethods(method),
     handler,
-    parseBody: options.parseBody ?? true,
     middleware,
-    bodyOptions: extractBodyOptions(options),
+    ...routeOptions,
   };
 }
 
@@ -42,9 +44,3 @@ function qualifyMethods(method: HttpMethod | HttpMethod[]): RouterMethod[] {
 
   return qualifiedMethods.includes('all') ? ['all'] : [...new Set<RouterMethod>(qualifiedMethods)];
 }
-
-function extractBodyOptions(options: RouteOptions): RouteDefinition['bodyOptions'] {
-  const { parseBody: _parseBody, ...bodyOptions } = options;
-
-  return bodyOptions as RouteDefinition['bodyOptions'];
-}

src/routing/expand-route-definitions.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test, vi } from 'vitest';
+import { expandRouteDefinitions } from './expand-route-definitions';
+
+describe('expand route definitions', () => {
+  test('it expands route definitions into route registrations', () => {
+    const handler = vi.fn(async () => undefined);
+
+    const registrations = expandRouteDefinitions([
+      {
+        path: '/users',
+        methods: ['get', 'post'],
+        handler,
+        middleware: [],
+        parseBody: false,
+        bodyOptions: {},
+      },
+    ]);
+
+    expect(registrations).toEqual([
+      {
+        method: 'get',
+        path: '/users',
+        middleware: [handler],
+      },
+      {
+        method: 'post',
+        path: '/users',
+        middleware: [handler],
+      },
+    ]);
+  });
+
+  test('it prepends koa body middleware when body parsing is enabled', () => {
+    const handler = vi.fn(async () => undefined);
+
+    const registrations = expandRouteDefinitions([
+      {
+        path: '/users',
+        methods: ['post'],
+        handler,
+        middleware: [],
+        parseBody: true,
+        bodyOptions: { multipart: true },
+      },
+    ]);
+
+    expect(registrations).toHaveLength(1);
+
+    const registration = registrations[0];
+    expect(registration).toBeDefined();
+    expect(registration?.middleware).toHaveLength(2);
+    expect(registration?.middleware[1]).toBe(handler);
+  });
+});

src/routing/expand-route-definitions.ts

@@ -0,0 +1,29 @@
+import { koaBody } from 'koa-body';
+import type { RouteDefinition } from '@/routing/route-definition';
+import type { RouteRegistration } from '@/routing/route-registration';
+
+export function expandRouteDefinitions(routes: RouteDefinition[]): RouteRegistration[] {
+  const registrations: RouteRegistration[] = [];
+
+  for (const route of routes) {
+    registrations.push(...expandRouteDefinition(route));
+  }
+
+  return registrations;
+}
+
+function expandRouteDefinition(route: RouteDefinition): RouteRegistration[] {
+  const middleware = resolveRouteMiddleware(route);
+
+  return route.methods.map(method => ({
+    method,
+    path: route.path,
+    middleware,
+  }));
+}
+
+function resolveRouteMiddleware(route: RouteDefinition): RouteRegistration['middleware'] {
+  const middlewareStack = [...route.middleware, route.handler];
+
+  return route.parseBody ? [koaBody(route.bodyOptions), ...middlewareStack] : middlewareStack;
+}

src/routing/index.ts

@@ -1,5 +1,8 @@
 export { Route } from './route';
+export { RouteGroup } from './route-group';
 export { Any, Delete, Get, Head, Options, Patch, Post, Put } from './http-verb-helpers';
 export type { RouteDeclaration } from './route';
+export type { RouteConfigOverlay, RouteGroupDefinition, RouteGroupOptions } from './route-group';
+export type { RouteSource } from './route-source';
 export type { HttpMethod } from './http-method';
 export type { RouteOptions } from './route-options';