feat: make overriding router parameter types easier (#513)

Closes #433

Author: bodograumann

README.md

@@ -675,6 +675,12 @@ Check out the
 [documentation for that library](https://github.com/pillarjs/path-to-regexp#parameters)
 if you have advanced use cases.
 
+In most cases, the type of `context.params` is automatically inferred from the
+path template string through typescript magic. In more complex scenarios this
+might not yield the correct result however. In that case you can override the
+type with `router.get<RouteParams>`, where `RouteParams` is the explicit type
+for `context.params`.
+
 ### Nested routers
 
 Nesting routers is supported. The following example responds to

router.ts

@@ -630,6 +630,17 @@ export class Router<
     middleware: RouterMiddleware<R, P, S>,
     ...middlewares: RouterMiddleware<R, P, S>[]
   ): Router<S extends RS ? S : (S & RS)>;
+  /** Register middleware for the specified routes when the `DELETE`,
+   * `GET`, `POST`, or `PUT` method is requested with explicit path parameters.
+   */
+  all<
+    P extends RouteParams<string>,
+    S extends State = RS,
+  >(
+    nameOrPath: string,
+    pathOrMiddleware: string | RouterMiddleware<string, P, S>,
+    ...middleware: RouterMiddleware<string, S>[]
+  ): Router<S extends RS ? S : (S & RS)>;
   all<
     P extends RouteParams<string> = RouteParams<string>,
     S extends State = RS,
@@ -734,6 +745,16 @@ export class Router<
     middleware: RouterMiddleware<R, P, S>,
     ...middlewares: RouterMiddleware<R, P, S>[]
   ): Router<S extends RS ? S : (S & RS)>;
+  /** Register middleware for the specified routes when the `DELETE`,
+   * method is requested with explicit path parameters. */
+  delete<
+    P extends RouteParams<string>,
+    S extends State = RS,
+  >(
+    nameOrPath: string,
+    pathOrMiddleware: string | RouterMiddleware<string, P, S>,
+    ...middleware: RouterMiddleware<string, P, S>[]
+  ): Router<S extends RS ? S : (S & RS)>;
   delete<
     P extends RouteParams<string> = RouteParams<string>,
     S extends State = RS,
@@ -801,6 +822,16 @@ export class Router<
     middleware: RouterMiddleware<R, P, S>,
     ...middlewares: RouterMiddleware<R, P, S>[]
   ): Router<S extends RS ? S : (S & RS)>;
+  /** Register middleware for the specified routes when the `GET`,
+   * method is requested with explicit path parameters. */
+  get<
+    P extends RouteParams<string>,
+    S extends State = RS,
+  >(
+    nameOrPath: string,
+    pathOrMiddleware: string | RouterMiddleware<string, P, S>,
+    ...middleware: RouterMiddleware<string, P, S>[]
+  ): Router<S extends RS ? S : (S & RS)>;
   get<
     P extends RouteParams<string> = RouteParams<string>,
     S extends State = RS,
@@ -841,6 +872,16 @@ export class Router<
     middleware: RouterMiddleware<R, P, S>,
     ...middlewares: RouterMiddleware<R, P, S>[]
   ): Router<S extends RS ? S : (S & RS)>;
+  /** Register middleware for the specified routes when the `HEAD`,
+   * method is requested with explicit path parameters. */
+  head<
+    P extends RouteParams<string>,
+    S extends State = RS,
+  >(
+    nameOrPath: string,
+    pathOrMiddleware: string | RouterMiddleware<string, P, S>,
+    ...middleware: RouterMiddleware<string, P, S>[]
+  ): Router<S extends RS ? S : (S & RS)>;
   head<
     P extends RouteParams<string> = RouteParams<string>,
     S extends State = RS,
@@ -889,6 +930,16 @@ export class Router<
     middleware: RouterMiddleware<R, P, S>,
     ...middlewares: RouterMiddleware<R, P, S>[]
   ): Router<S extends RS ? S : (S & RS)>;
+  /** Register middleware for the specified routes when the `OPTIONS`,
+   * method is requested with explicit path parameters. */
+  options<
+    P extends RouteParams<string>,
+    S extends State = RS,
+  >(
+    nameOrPath: string,
+    pathOrMiddleware: string | RouterMiddleware<string, P, S>,
+    ...middleware: RouterMiddleware<string, P, S>[]
+  ): Router<S extends RS ? S : (S & RS)>;
   options<
     P extends RouteParams<string> = RouteParams<string>,
     S extends State = RS,
@@ -942,6 +993,16 @@ export class Router<
     middleware: RouterMiddleware<R, P, S>,
     ...middlewares: RouterMiddleware<R, P, S>[]
   ): Router<S extends RS ? S : (S & RS)>;
+  /** Register middleware for the specified routes when the `PATCH`,
+   * method is requested with explicit path parameters. */
+  patch<
+    P extends RouteParams<string>,
+    S extends State = RS,
+  >(
+    nameOrPath: string,
+    pathOrMiddleware: string | RouterMiddleware<string, P, S>,
+    ...middleware: RouterMiddleware<string, S>[]
+  ): Router<S extends RS ? S : (S & RS)>;
   patch<
     P extends RouteParams<string> = RouteParams<string>,
     S extends State = RS,
@@ -982,6 +1043,16 @@ export class Router<
     middleware: RouterMiddleware<R, P, S>,
     ...middlewares: RouterMiddleware<R, P, S>[]
   ): Router<S extends RS ? S : (S & RS)>;
+  /** Register middleware for the specified routes when the `POST`,
+   * method is requested with explicit path parameters. */
+  post<
+    P extends RouteParams<string>,
+    S extends State = RS,
+  >(
+    nameOrPath: string,
+    pathOrMiddleware: string | RouterMiddleware<string, P, S>,
+    ...middleware: RouterMiddleware<string, P, S>[]
+  ): Router<S extends RS ? S : (S & RS)>;
   post<
     P extends RouteParams<string> = RouteParams<string>,
     S extends State = RS,
@@ -1032,6 +1103,16 @@ export class Router<
     middleware: RouterMiddleware<R, P, S>,
     ...middlewares: RouterMiddleware<R, P, S>[]
   ): Router<S extends RS ? S : (S & RS)>;
+  /** Register middleware for the specified routes when the `PUT`
+   * method is requested with explicit path parameters. */
+  put<
+    P extends RouteParams<string>,
+    S extends State = RS,
+  >(
+    nameOrPath: string,
+    pathOrMiddleware: string | RouterMiddleware<string, P, S>,
+    ...middleware: RouterMiddleware<string, P, S>[]
+  ): Router<S extends RS ? S : (S & RS)>;
   put<
     P extends RouteParams<string> = RouteParams<string>,
     S extends State = RS,
@@ -1190,6 +1271,16 @@ export class Router<
     middleware: RouterMiddleware<R, P, S>,
     ...middlewares: RouterMiddleware<R, P, S>[]
   ): Router<S extends RS ? S : (S & RS)>;
+  /** Register middleware to be used on every route that matches the supplied
+   * `path` with explicit path parameters. */
+  use<
+    P extends RouteParams<string>,
+    S extends State = RS,
+  >(
+    path: string,
+    middleware: RouterMiddleware<string, P, S>,
+    ...middlewares: RouterMiddleware<string, P, S>[]
+  ): Router<S extends RS ? S : (S & RS)>;
   use<
     P extends RouteParams<string> = RouteParams<string>,
     S extends State = RS,

router_test.ts

@@ -711,6 +711,12 @@ test({
         ctx.params.id;
         ctx.params.page;
         ctx.state.session;
+      }).post<{ id: string }>("/:id\\:archive", (ctx) => {
+        ctx.params.id;
+        // @ts-expect-error
+        ctx.params["id:archive"];
+        // @ts-expect-error
+        ctx.params["id\\:archive"];
       }).routes(),
     ).use((ctx) => {
       ctx.state.id;