feat: improve param type inference

src/event.ts

@@ -56,7 +56,11 @@ export class H3Event<
   /**
    * Event context.
    */
-  readonly context: H3EventContext;
+  readonly context: H3EventContext<_RequestT["routerParams"]> & {
+    params: _RequestT["routerParams"] extends undefined
+      ? undefined
+      : _RequestT["routerParams"];
+  };
 
   /**
    * @internal

src/h3.ts

@@ -30,6 +30,7 @@ import type {
 
 import { toRequest } from "./utils/request.ts";
 import { toEventHandler } from "./handler.ts";
+import type { RouteParams } from "./types/_utils.ts";
 
 export const NoHandler: EventHandler = () => kNotFound;
 
@@ -167,18 +168,36 @@ export const H3 = /* @__PURE__ */ (() => {
       return this;
     }
 
+    on<Route extends string>(
+      method: HTTPMethod | Lowercase<HTTPMethod> | "",
+      route: Route,
+      handler: EventHandler<{
+        routerParams: RouteParams<Route>;
+      }>,
+      opts?: RouteOptions,
+    ): this;
     on(
       method: HTTPMethod | Lowercase<HTTPMethod> | "",
       route: string,
       handler: HTTPHandler,
       opts?: RouteOptions,
+    ): this;
+    on<Route extends string>(
+      method: HTTPMethod | Lowercase<HTTPMethod> | "",
+      route: Route | string,
+      handler:
+        | EventHandler<{
+            routerParams: RouteParams<Route>;
+          }>
+        | HTTPHandler,
+      opts?: RouteOptions,
     ): this {
       const _method = (method || "").toUpperCase();
       route = new URL(route, "http://_").pathname;
       this["~addRoute"]({
         method: _method as HTTPMethod,
         route,
-        handler: toEventHandler(handler)!,
+        handler: toEventHandler(handler as HTTPHandler)!,
         middleware: opts?.middleware,
         meta: { ...(handler as EventHandler).meta, ...opts?.meta },
       });

src/types/_utils.ts

@@ -1 +1,11 @@
+import type { InferRouteParams } from "rou3";
+
 export type MaybePromise<T = unknown> = T | Promise<T>;
+
+export type Simplify<T> = { [K in keyof T]: T[K] } & {};
+export type RouteParams<T extends string> =
+  Simplify<InferRouteParams<T>> extends infer _Simplified
+    ? keyof _Simplified extends never
+      ? undefined
+      : _Simplified
+    : never;

src/types/context.ts

@@ -2,9 +2,14 @@ import type { Session } from "../utils/session.ts";
 import type { H3Route } from "./h3.ts";
 import type { ServerRequestContext } from "srvx";
 
-export interface H3EventContext extends ServerRequestContext {
-  /* Matched router parameters */
-  params?: Record<string, string>;
+export interface H3EventContext<TParams = Record<string, string>>
+  extends ServerRequestContext {
+  /**
+   * Matched route parameters
+   *
+   * If there are no parameters, this will be `undefined`.
+   */
+  params?: TParams;
 
   /* Matched middleware parameters */
   middlewareParams?: Record<string, string>;

src/types/h3.ts

@@ -1,7 +1,7 @@
 import type { H3EventContext } from "./context.ts";
 import type { HTTPHandler, EventHandler, Middleware } from "./handler.ts";
 import type { HTTPError } from "../error.ts";
-import type { MaybePromise } from "./_utils.ts";
+import type { MaybePromise, RouteParams } from "./_utils.ts";
 import type { FetchHandler, ServerRequest } from "srvx";
 // import type { MatchedRoute, RouterContext } from "rou3";
 import type { H3Event } from "../event.ts";
@@ -21,8 +21,32 @@ export type MatchedRoute<T = any> = {
 
 // https://www.rfc-editor.org/rfc/rfc7231#section-4.1
 // prettier-ignore
-export type HTTPMethod =  "GET" | "HEAD" | "PATCH" | "POST" | "PUT" | "DELETE" | "CONNECT" | "OPTIONS" | "TRACE";
-
+export type HTTPMethod = "GET" | "HEAD" | "PATCH" | "POST" | "PUT" | "DELETE" | "CONNECT" | "OPTIONS" | "TRACE";
+
+/**
+ * Interface for HTTP method handlers (GET, POST, PUT, DELETE, etc.).
+ *
+ * Automatically infers route parameters from the route pattern and makes them
+ * available in the event handler context.
+ *
+ * @template {H3} This - Passed as `this` to resolve to the declared H3 class type
+ * rather than the runtime H3 class implementation. This ensures TypeScript uses
+ * the correct type signature from this declaration file.
+ *
+ * NOTE:
+ * If we used H3 directly in the return type, the bench implementation would
+ * fail, due to `app._rou3` not being defined on H3.
+ */
+interface H3HandlerInterface<This extends H3> {
+  <Route extends string>(
+    route: Route,
+    handler: EventHandler<{
+      routerParams: RouteParams<Route>;
+    }>,
+    opts?: RouteOptions,
+  ): This;
+  (route: string, handler: HTTPHandler, opts?: RouteOptions): This;
+}
 export interface H3Config {
   /**
    * When enabled, H3 displays debugging stack traces in HTTP responses (potentially dangerous for production!).
@@ -155,6 +179,14 @@ export declare class H3 extends H3Core {
   /**
    * Register a route handler for the specified HTTP method and route.
    */
+  on<Route extends string>(
+    method: HTTPMethod | Lowercase<HTTPMethod> | "",
+    route: Route,
+    handler: EventHandler<{
+      routerParams: RouteParams<Route>;
+    }>,
+    opts?: RouteOptions,
+  ): this;
   on(
     method: HTTPMethod | Lowercase<HTTPMethod> | "",
     route: string,
@@ -179,15 +211,22 @@ export declare class H3 extends H3Core {
   /**
    * Register a route handler for all HTTP methods.
    */
+  all<Route extends string>(
+    route: Route,
+    handler: EventHandler<{
+      routerParams: RouteParams<Route>;
+    }>,
+    opts?: RouteOptions,
+  ): this;
   all(route: string, handler: HTTPHandler, opts?: RouteOptions): this;
 
-  get(route: string, handler: HTTPHandler, opts?: RouteOptions): this;
-  post(route: string, handler: HTTPHandler, opts?: RouteOptions): this;
-  put(route: string, handler: HTTPHandler, opts?: RouteOptions): this;
-  delete(route: string, handler: HTTPHandler, opts?: RouteOptions): this;
-  patch(route: string, handler: HTTPHandler, opts?: RouteOptions): this;
-  head(route: string, handler: HTTPHandler, opts?: RouteOptions): this;
-  options(route: string, handler: HTTPHandler, opts?: RouteOptions): this;
-  connect(route: string, handler: HTTPHandler, opts?: RouteOptions): this;
-  trace(route: string, handler: HTTPHandler, opts?: RouteOptions): this;
+  get: H3HandlerInterface<this>;
+  post: H3HandlerInterface<this>;
+  put: H3HandlerInterface<this>;
+  delete: H3HandlerInterface<this>;
+  patch: H3HandlerInterface<this>;
+  head: H3HandlerInterface<this>;
+  options: H3HandlerInterface<this>;
+  connect: H3HandlerInterface<this>;
+  trace: H3HandlerInterface<this>;
 }

src/utils/request.ts

@@ -105,6 +105,14 @@ export function getValidatedQuery(
   return validateData(query, validate);
 }
 
+export function getRouterParams<Event extends H3Event>(
+  event: Event,
+  opts?: { decode?: boolean },
+): Event extends H3Event<infer R> ? R["routerParams"] : never;
+export function getRouterParams<Event extends HTTPEvent>(
+  event: Event,
+  opts?: { decode?: boolean },
+): NonNullable<H3Event["context"]["params"]>;
 /**
  * Get matched route params.
  *
@@ -115,21 +123,23 @@ export function getValidatedQuery(
  *   const params = getRouterParams(event); // { key: "value" }
  * });
  */
-export function getRouterParams(
-  event: HTTPEvent,
+export function getRouterParams<Event extends HTTPEvent>(
+  event: Event,
   opts: { decode?: boolean } = {},
 ): NonNullable<H3Event["context"]["params"]> {
   // Fallback object needs to be returned in case router is not used (#149)
   const context = getEventContext<H3EventContext>(event);
   let params = (context.params || {}) as NonNullable<
     H3Event["context"]["params"]
   >;
+
   if (opts.decode) {
     params = { ...params };
     for (const key in params) {
       params[key] = decodeURIComponent(params[key]);
     }
   }
+
   return params;
 }
 
@@ -186,6 +196,21 @@ export function getValidatedRouterParams(
   return validateData(routerParams, validate);
 }
 
+export function getRouterParam<
+  Event extends H3Event,
+  Key extends Event extends H3Event<infer R>
+    ? keyof R["routerParams"] & string
+    : never,
+>(
+  event: Event,
+  name: Key,
+  opts?: { decode?: boolean },
+): Event extends H3Event<infer R> ? R["routerParams"][Key] : never;
+export function getRouterParam<Event extends HTTPEvent>(
+  event: Event,
+  name: string,
+  opts?: { decode?: boolean },
+): string | undefined;
 /**
  * Get a matched route param by name.
  *
@@ -196,12 +221,13 @@ export function getValidatedRouterParams(
  *   const param = getRouterParam(event, "key");
  * });
  */
-export function getRouterParam(
-  event: HTTPEvent,
+export function getRouterParam<Event extends HTTPEvent>(
+  event: Event,
   name: string,
   opts: { decode?: boolean } = {},
 ): string | undefined {
   const params = getRouterParams(event, opts);
+
   return params[name];
 }