chore(routing): routing code refactoring

package.json

@@ -59,7 +59,9 @@
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "format": "prettier --write .",
-    "format:check": "prettier --check ."
+    "format:check": "prettier --check .",
+    "watch:test": "vitest watch",
+    "watch:build": "tsc --noEmit --watch"
   },
   "dependencies": {
     "@koa/router": "^15.1.1",

src/Http/Request/types.ts

@@ -4,8 +4,9 @@ import type { JsonValue } from 'type-fest';
 
 export type UploadedFile = File;
 export type UploadedFilesMap = Record<string, UploadedFile | UploadedFile[]>;
+export type HttpRequestBase = Request;
 
-export interface HttpRequest extends Request {
+export interface HttpRequest extends HttpRequestBase {
   body?: Record<string, unknown> & JsonValue;
   files?: UploadedFilesMap;
   params: Record<string, unknown>;

src/Http/Scope/types.ts

@@ -1,17 +1,17 @@
-import type { Context, DefaultState, Next, Request } from 'koa';
-import { type HttpRequest } from '../Request';
+import type { Context, DefaultState, Next } from 'koa';
+import { type HttpRequest, type HttpRequestBase } from '../Request';
 import { type HttpResponse } from '../Response';
 import { type User } from '@/Security/types';
 
-export interface HttpScope<TRequest extends Request = HttpRequest, TUser extends User = User> extends Context {
+export interface HttpScope<TRequest extends HttpRequestBase = HttpRequest, TUser extends User = User> extends Context {
   request: TRequest;
   response: HttpResponse;
   user?: TUser;
 }
 
 export type NextMiddleware = Next;
 
-export type HttpMiddleware<TRequest extends Request = HttpRequest> = (
+export type HttpMiddleware<TRequest extends HttpRequestBase = HttpRequest> = (
   scope: HttpScope<TRequest>,
   next: NextMiddleware,
 ) => Promise<unknown>;

src/Testing/TestAgentFactory.ts

@@ -2,10 +2,14 @@ import { create } from '@/application/create-application';
 import { type KoalaConfig } from '@/config/koala-config';
 import { type HttpMiddleware, type HttpScope, type NextMiddleware } from '@/Http';
 import { type User } from '@/Security/types';
+import type { Request } from 'koa';
 import supertest from 'supertest';
 import { type TestAgent } from './types';
 
-export function createTestAgent(config: KoalaConfig, agentConfig?: { actAs?: User }): TestAgent {
+export function createTestAgent<TRequest extends Request>(
+  config: KoalaConfig<TRequest>,
+  agentConfig?: { actAs?: User },
+): TestAgent {
   const globalMiddleware = config.globalMiddleware ?? [];
   const testConfig = { ...config };
 

src/application/create-application.test.ts

@@ -1,7 +1,7 @@
 import { create } from '@/application/create-application';
 import { koalaDefaultConfig } from '@/config/default-config';
 import { Get, Route, RouteGroup } from '@/routing';
-import { exclusiveRoutingModeError } from '@/routing/verify-routing-mode';
+import { exclusiveRoutingModeError } from '@/routing/deprecated-decorator/verify-routing-mode';
 import { expect, test } from 'vitest';
 
 test('create app with default config', () => {

src/application/create-application.ts

@@ -4,13 +4,14 @@ import { serveStaticFiles } from '@/Http/Files';
 import { applyConfiguredGlobalMiddleware } from '@/Http/middleware/apply-configured-global-middleware';
 import { initializeRequestScopeStorage } from '@/Http/Scope/request-scope-storage';
 import { registerEventSubscribers } from '@/Kernel';
-import { registerLegacyRoutes } from '@/routing/decorator/legacy-router';
+import { registerLegacyRoutes } from '@/routing/deprecated-decorator/legacy-router';
+import { verifyRoutingMode } from '@/routing/deprecated-decorator/verify-routing-mode';
 import { registerRoutes } from '@/routing/registration/register-routes';
-import { verifyRoutingMode } from '@/routing/verify-routing-mode';
+import type { Request } from 'koa';
 import Koa from 'koa';
 import { type Application } from './application';
 
-export function create(config: KoalaConfig): Application {
+export function create<TRequest extends Request>(config: KoalaConfig<TRequest>): Application {
   const app = new Koa() as Application;
   const controllers = config.controllers ?? [];
 

src/config/koala-config.ts

@@ -3,8 +3,7 @@ import { type StaticFilesOptions } from '@/Http/Files';
 import { type EventSubscriber } from '@/Kernel';
 import type { RouteSource } from '@/routing';
 import type { DotenvConfigOptions } from 'dotenv';
-import type { HttpRequest } from '@/Http';
-import type { Request } from 'koa';
+import type { HttpRequest, HttpRequestBase } from '@/Http';
 
 /**
  * @deprecated Use function-first routes from `@koala-ts/framework/routing` with `KoalaConfig.routes` instead.
@@ -13,7 +12,7 @@ export type Controller = new (...args: unknown[]) => unknown;
 
 export type KoalaDotenvOptions = Pick<DotenvConfigOptions, 'debug' | 'encoding' | 'override' | 'quiet'>;
 
-export interface KoalaConfig<TRequest extends Request = HttpRequest> {
+export interface KoalaConfig<TRequest extends HttpRequestBase = HttpRequest> {
   /**
    * @deprecated Use `routes` with `Route` from `@koala-ts/framework/routing` instead.
    */

src/index.ts

@@ -1,8 +1,8 @@
 // Application
 export { create } from '@/application/create-application';
 export type { Application } from '@/application/application';
-import { getLegacyRoutes, registerLegacyRoutes } from '@/routing/decorator/legacy-router';
-import type { RouteMetadata as LegacyRouteMetadata } from '@/routing/decorator/route-metadata';
+import { getLegacyRoutes, registerLegacyRoutes } from '@/routing/deprecated-decorator/legacy-router';
+import type { RouteMetadata as LegacyRouteMetadata } from '@/routing/deprecated-decorator/route-metadata';
 
 // Core modules
 export type * from '@/config/koala-config';
@@ -12,10 +12,10 @@ export * from '@/Http';
 export * from '@/Kernel';
 
 // Routing
-export * from '@/routing/decorator/route';
-export type { HttpMethod } from '@/routing/http-method';
-export type { RouteOptions } from '@/routing/route-options';
-export type { RouterMethod } from '@/routing/router-method';
+export * from '@/routing/deprecated-decorator/route';
+export type { HttpMethod } from '@/routing/http-method.type';
+export type { RouteOptions } from '@/routing/declaration/route-options.type';
+export type { RouterMethod } from '@/routing/declaration/router-method.type';
 /**
  * @deprecated Use `Route` from `@koala-ts/framework/routing` instead.
  */

src/routing/helpers/http-verb-helpers.ts → src/routing/declaration/http-verb-helpers.ts

@@ -1,47 +1,46 @@
-import type { HttpMiddleware, HttpRequest } from '@/Http';
-import type { HttpMethod } from '@/routing/http-method';
-import type { RouteDefinition } from '@/routing/definition/route-definition';
-import { Route } from '@/routing/route';
-import type { Request } from 'koa';
+import type { HttpMiddleware, HttpRequest, HttpRequestBase } from '@/Http';
+import type { NormalizedRouteProps } from '@/routing/declaration/normalized-route-props.type';
+import { Route } from '@/routing/declaration/route';
+import type { HttpMethod } from '@/routing/http-method.type';
 
-type RouteHandler<TRequest extends Request = HttpRequest> = HttpMiddleware<TRequest>;
-type MiddlewareAndHandler<TRequest extends Request = HttpRequest> = [
+type RouteHandler<TRequest extends HttpRequestBase = HttpRequest> = HttpMiddleware<TRequest>;
+type MiddlewareAndHandler<TRequest extends HttpRequestBase = HttpRequest> = [
   ...middleware: HttpMiddleware<TRequest>[],
   handler: RouteHandler<TRequest>,
 ];
-type NamedMiddlewareAndHandler<TRequest extends Request = HttpRequest> = [
+type NamedMiddlewareAndHandler<TRequest extends HttpRequestBase = HttpRequest> = [
   name: string,
   ...middlewareAndHandler: MiddlewareAndHandler<TRequest>,
 ];
-type VerbHelperRouteArguments<TRequest extends Request = HttpRequest> =
+type VerbHelperRouteArguments<TRequest extends HttpRequestBase = HttpRequest> =
   | MiddlewareAndHandler<TRequest>
   | NamedMiddlewareAndHandler<TRequest>;
-type UnsafeVerbHelperRouteArguments<TRequest extends Request = HttpRequest> =
+type UnsafeVerbHelperRouteArguments<TRequest extends HttpRequestBase = HttpRequest> =
   | VerbHelperRouteArguments<TRequest>
   | [name: string]
   | [];
 
-interface VerbHelperArguments<TRequest extends Request = HttpRequest> {
+interface VerbHelperArguments<TRequest extends HttpRequestBase = HttpRequest> {
   path: string;
   name?: string;
   middleware: HttpMiddleware<TRequest>[];
   handler: RouteHandler<TRequest>;
 }
 
 type NamedVerbHelper = {
-  <TRequest extends Request = HttpRequest>(
+  <TRequest extends HttpRequestBase = HttpRequest>(
     path: string,
     ...middlewareAndHandler: MiddlewareAndHandler<TRequest>
-  ): RouteDefinition<TRequest>;
-  <TRequest extends Request = HttpRequest>(
+  ): NormalizedRouteProps<TRequest>;
+  <TRequest extends HttpRequestBase = HttpRequest>(
     path: string,
     name: string,
     ...middlewareAndHandler: MiddlewareAndHandler<TRequest>
-  ): RouteDefinition<TRequest>;
+  ): NormalizedRouteProps<TRequest>;
 };
 
 function createVerbHelper(method: HttpMethod): NamedVerbHelper {
-  return <TRequest extends Request = HttpRequest>(
+  return <TRequest extends HttpRequestBase = HttpRequest>(
     path: string,
     ...routeArguments: UnsafeVerbHelperRouteArguments<TRequest>
   ) =>
@@ -51,7 +50,7 @@ function createVerbHelper(method: HttpMethod): NamedVerbHelper {
     });
 }
 
-function resolveVerbHelperArguments<TRequest extends Request = HttpRequest>(
+function resolveVerbHelperArguments<TRequest extends HttpRequestBase = HttpRequest>(
   path: string,
   routeArguments: UnsafeVerbHelperRouteArguments<TRequest>,
 ): VerbHelperArguments<TRequest> {
@@ -71,13 +70,13 @@ function resolveVerbHelperArguments<TRequest extends Request = HttpRequest>(
   };
 }
 
-function isNamedVerbHelperRouteArguments<TRequest extends Request = HttpRequest>(
+function isNamedVerbHelperRouteArguments<TRequest extends HttpRequestBase = HttpRequest>(
   routeArguments: UnsafeVerbHelperRouteArguments<TRequest>,
 ): routeArguments is NamedMiddlewareAndHandler<TRequest> | [name: string] {
   return typeof routeArguments[0] === 'string';
 }
 
-function requireVerbHelperHandler<TRequest extends Request = HttpRequest>(
+function requireVerbHelperHandler<TRequest extends HttpRequestBase = HttpRequest>(
   middlewareAndHandler: MiddlewareAndHandler<TRequest> | [],
   isNamedRoute: boolean,
 ): RouteHandler<TRequest> {

src/routing/declaration/normalized-route-props.type.ts

@@ -0,0 +1,13 @@
+import type { HttpMiddleware, HttpRequest, HttpRequestBase } from '@/Http';
+import type { RouteBodyOptions } from '@/routing/declaration/route-body-options.type';
+import type { RouterMethod } from '@/routing/declaration/router-method.type';
+
+export interface NormalizedRouteProps<TRequest extends HttpRequestBase = HttpRequest> {
+  name?: string;
+  path: string;
+  methods: RouterMethod[];
+  handler: HttpMiddleware<TRequest>;
+  middleware: HttpMiddleware<TRequest>[];
+  parseBody: boolean;
+  bodyOptions: RouteBodyOptions;
+}

src/routing/declaration/route-body-options.type.ts

@@ -0,0 +1,4 @@
+export interface RouteBodyOptions {
+  multipart?: boolean;
+  [option: string]: unknown;
+}

src/routing/helpers/route-group.test.ts → src/routing/declaration/route-group.test.ts

@@ -1,5 +1,5 @@
+import { Get } from '@/routing/declaration/http-verb-helpers';
 import { describe, expect, test } from 'vitest';
-import { Get } from '@/routing/helpers/http-verb-helpers';
 import { RouteGroup } from './route-group';
 
 describe('route group', () => {

src/routing/declaration/route-group.ts

@@ -0,0 +1,33 @@
+import type { HttpMiddleware, HttpRequest, HttpRequestBase } from '@/Http';
+
+import { RouteProps } from '@/routing/declaration/route-props.type';
+import type { RouteSource } from '@/routing/declaration/route-source.type';
+
+export type RouteConfigOverlay<TRequest extends HttpRequestBase = HttpRequest> = Pick<
+  RouteProps<TRequest>,
+  'middleware' | 'options'
+>;
+
+export interface RouteGroupOptions<TRequest extends HttpRequestBase = HttpRequest> {
+  prefix?: string;
+  namePrefix?: string;
+  middleware?: HttpMiddleware<TRequest>[];
+  routeConfig?: Record<string, RouteConfigOverlay<TRequest>>;
+}
+
+export interface RouteGroupDefinition<TRequest extends HttpRequestBase = HttpRequest> {
+  kind: 'route-group';
+  options: RouteGroupOptions<TRequest>;
+  resolveRoutes: () => RouteSource<TRequest>[];
+}
+
+export function RouteGroup<TRequest extends HttpRequestBase = HttpRequest>(
+  options: RouteGroupOptions<TRequest>,
+  resolveRoutes: () => RouteSource<TRequest>[],
+): RouteGroupDefinition<TRequest> {
+  return {
+    kind: 'route-group',
+    options,
+    resolveRoutes,
+  };
+}

src/routing/declaration/route-options.type.ts

@@ -0,0 +1,7 @@
+import type { RouteBodyOptions } from '@/routing/declaration/route-body-options.type';
+
+export type RouteOptions = Partial<
+  RouteBodyOptions & {
+    parseBody?: boolean;
+  }
+>;

src/routing/declaration/route-props.type.ts

@@ -0,0 +1,12 @@
+import type { HttpMiddleware, HttpRequest, HttpRequestBase } from '@/Http';
+import type { RouteOptions } from '@/routing/declaration/route-options.type';
+import type { HttpMethod } from '@/routing/http-method.type';
+
+export interface RouteProps<TRequest extends HttpRequestBase = HttpRequest> {
+  name?: string;
+  path: string;
+  method: HttpMethod | HttpMethod[];
+  handler: HttpMiddleware<TRequest>;
+  middleware?: HttpMiddleware<TRequest>[];
+  options?: RouteOptions;
+}

src/routing/declaration/route-source.type.ts

@@ -0,0 +1,7 @@
+import type { HttpRequest, HttpRequestBase } from '@/Http';
+import type { NormalizedRouteProps } from '@/routing/declaration/normalized-route-props.type';
+import type { RouteGroupDefinition } from '@/routing/declaration/route-group';
+
+export type RouteSource<TRequest extends HttpRequestBase = HttpRequest> =
+  | NormalizedRouteProps<TRequest>
+  | RouteGroupDefinition<TRequest>;

src/routing/definition/create-route-definition.test.ts → src/routing/declaration/route.test.ts

@@ -1,15 +1,11 @@
 import { describe, expect, test, vi } from 'vitest';
-import { createRouteDefinition } from './create-route-definition';
+import { Route } from './route';
 
-describe('create route definition', () => {
+describe('routing route', () => {
   test('it creates a route definition for a single method', () => {
     const handler = vi.fn(async () => undefined);
 
-    const route = createRouteDefinition({
-      method: 'GET',
-      path: '/users',
-      handler,
-    });
+    const route = Route({ method: 'GET', path: '/users', handler });
 
     expect(route).toEqual({
       path: '/users',
@@ -25,7 +21,7 @@ describe('create route definition', () => {
     const handler = vi.fn(async () => undefined);
     const middleware = [vi.fn(async () => undefined)];
 
-    const route = createRouteDefinition({
+    const route = Route({
       name: 'users.create',
       method: 'POST',
       path: '/users',
@@ -53,47 +49,31 @@ describe('create route definition', () => {
   test('it qualifies multiple methods', () => {
     const handler = vi.fn(async () => undefined);
 
-    const route = createRouteDefinition({
-      method: ['GET', 'POST'],
-      path: '/users',
-      handler,
-    });
+    const route = Route({ method: ['GET', 'POST'], path: '/users', handler });
 
     expect(route.methods).toEqual(['get', 'post']);
   });
 
   test('it normalizes any and all to all', () => {
     const handler = vi.fn(async () => undefined);
 
-    const route = createRouteDefinition({
-      method: ['ANY', 'ALL'],
-      path: '/users',
-      handler,
-    });
+    const route = Route({ method: ['ANY', 'ALL'], path: '/users', handler });
 
     expect(route.methods).toEqual(['all']);
   });
 
   test('it normalizes any with specific methods to all', () => {
     const handler = vi.fn(async () => undefined);
 
-    const route = createRouteDefinition({
-      method: ['ANY', 'GET'],
-      path: '/users',
-      handler,
-    });
+    const route = Route({ method: ['ANY', 'GET'], path: '/users', handler });
 
     expect(route.methods).toEqual(['all']);
   });
 
-  test('it removes duplicate specific methods case-insensitively', () => {
+  test('it removes duplicate specific methods case insensitively', () => {
     const handler = vi.fn(async () => undefined);
 
-    const route = createRouteDefinition({
-      method: ['GET', 'get', 'POST'],
-      path: '/users',
-      handler,
-    });
+    const route = Route({ method: ['GET', 'get', 'POST'], path: '/users', handler });
 
     expect(route.methods).toEqual(['get', 'post']);
   });