feat(router): expose event.context.matchedRoute (#500)

Co-authored-by: Pooya Parsa <pooya@pi0.io>

src/router.ts

@@ -33,8 +33,9 @@ export interface Router extends AddRouteShortcuts {
   handler: EventHandler;
 }
 
-interface RouteNode {
+export interface RouteNode {
   handlers: Partial<Record<RouterMethod | "all", EventHandler>>;
+  path: string;
 }
 
 export interface CreateRouterOptions {
@@ -59,7 +60,7 @@ export function createRouter(opts: CreateRouterOptions = {}): Router {
   ) => {
     let route = routes[path];
     if (!route) {
-      routes[path] = route = { handlers: {} };
+      routes[path] = route = { path, handlers: {} };
       _router.insert(path, route);
     }
     if (Array.isArray(method)) {
@@ -143,7 +144,8 @@ export function createRouter(opts: CreateRouterOptions = {}): Router {
       }
     }
 
-    // Add params
+    // Add matched route and params to the context
+    event.context.matchedRoute = matched;
     const params = matched.params || {};
     event.context.params = params;
 

src/types.ts

@@ -1,6 +1,7 @@
 import type { QueryObject } from "ufo";
 import type { H3Event } from "./event";
 import type { Session } from "./utils/session";
+import type { RouteNode } from "./router";
 
 export type {
   ValidateFunction,
@@ -35,6 +36,12 @@ export type Encoding =
 export interface H3EventContext extends Record<string, any> {
   /* Matched router parameters */
   params?: Record<string, string>;
+  /**
+   * Matched router Node
+   *
+   * @experimental The object structure may change in non-major version.
+   */
+  matchedRoute?: RouteNode;
   /* Cached session data */
   sessions?: Record<string, Session>;
 }

test/router.test.ts

@@ -247,3 +247,46 @@ describe("getRouterParam", () => {
     });
   });
 });
+
+describe("event.context.matchedRoute", () => {
+  let app: App;
+  let request: SuperTest<Test>;
+
+  beforeEach(() => {
+    app = createApp({ debug: false });
+    request = supertest(toNodeListener(app));
+  });
+
+  describe("with router", () => {
+    it("can return the matched path", async () => {
+      const router = createRouter().get(
+        "/test/:template",
+        eventHandler((event) => {
+          expect(event.context.matchedRoute).toMatchObject({
+            path: "/test/:template",
+          });
+          return "200";
+        }),
+      );
+      app.use(router);
+      const result = await request.get("/test/path");
+
+      expect(result.text).toBe("200");
+    });
+  });
+
+  describe("without router", () => {
+    it("can return `undefined` for matched path", async () => {
+      app.use(
+        "/",
+        eventHandler((event) => {
+          expect(event.context.matchedRoute).toEqual(undefined);
+          return "200";
+        }),
+      );
+      const result = await request.get("/test/path");
+
+      expect(result.text).toBe("200");
+    });
+  });
+});