@koa/router 15.3.2 → 15.5.0

package/README.md

@@ -192,10 +192,15 @@ import {
   RouterOptions,
   RouterMiddleware,
   RouterParameterMiddleware,
-  RouterParamContext,
   AllowedMethodsOptions,
   UrlOptions,
-  HttpMethod
+  HttpMethod,
+  MatchResult,
+  LayerOptions,
+  Layer,
+  RouterEvent,
+  RouterEventSelector,
+  RouterEvents
 } from '@koa/router';
 import type { Next } from 'koa';
 
@@ -261,14 +266,14 @@ Create a new router instance.
 
 **Options:**
 
-| Option      | Type                           | Description                               |
-| ----------- | ------------------------------ | ----------------------------------------- |
-| `prefix`    | `string`                       | Prefix all routes with this path          |
-| `exclusive` | `boolean`                      | Only run the most specific matching route |
-| `host`      | `string \| string[] \| RegExp` | Match routes only for this hostname(s)    |
-| `methods`   | `string[]`                     | Custom HTTP methods to support            |
-| `sensitive` | `boolean`                      | Enable case-sensitive routing             |
-| `strict`    | `boolean`                      | Require trailing slashes                  |
+| Option      | Type                           | Description                                                                                                                                                                    |
+| ----------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `prefix`    | `string`                       | Prefix all routes with this path                                                                                                                                               |
+| `exclusive` | `boolean \| 'specificity'`     | `true`: only run the last-registered matching route. `'specificity'`: only run the route with the fewest path parameters (OpenAPI-compliant). Omit to run all matching routes. |
+| `host`      | `string \| string[] \| RegExp` | Match routes only for this hostname(s)                                                                                                                                         |
+| `methods`   | `string[]`                     | Custom HTTP methods to support                                                                                                                                                 |
+| `sensitive` | `boolean`                      | Enable case-sensitive routing                                                                                                                                                  |
+| `strict`    | `boolean`                      | Require trailing slashes                                                                                                                                                       |
 
 **Example:**
 
@@ -740,6 +745,56 @@ const url = Router.url('/users/:id', { id: 1, name: 'John' });
 // => "/users/1"
 ```
 
+### router.on() (experimental)
+
+Register an event handler on the router for lifecycle events.
+
+**Signature:**
+
+```typescript
+router.on(event: RouterEventSelector, handler: RouterMiddleware): Router
+```
+
+**Parameters:**
+
+| Parameter | Type                  | Description                                                      |
+| --------- | --------------------- | ---------------------------------------------------------------- |
+| `event`   | `RouterEventSelector` | Event name string, `RouterEvents` constant, or selector function |
+| `handler` | `RouterMiddleware`    | Middleware function `(ctx, next) => {}`                          |
+
+**Returns:** Router instance for chaining.
+
+**Active events:**
+
+| Event         | Constant                | Description                               |
+| ------------- | ----------------------- | ----------------------------------------- |
+| `'not-found'` | `RouterEvents.NotFound` | Fires when no route matched path + method |
+
+**Example:**
+
+```javascript
+import { RouterEvents } from '@koa/router';
+
+// All three forms are equivalent:
+router.on(RouterEvents.NotFound, handler); // constant (recommended)
+router.on((events) => events.NotFound, handler); // selector function
+router.on('not-found', handler); // raw string
+
+// Handlers can be chained:
+router
+  .on(RouterEvents.NotFound, async (ctx, next) => {
+    console.log('no route matched:', ctx.path);
+    await next();
+  })
+  .on(RouterEvents.NotFound, (ctx) => {
+    ctx.status = 404;
+    ctx.body = { error: 'Not Found' };
+  });
+```
+
+> **Note:** This API is experimental and may change in future versions. See the
+> [Not Found Event](#not-found-event-experimental) section in Advanced Features for details.
+
 ## Advanced Features
 
 ### Host Matching
@@ -842,7 +897,8 @@ router.get('/post/:id', handler);
 
 ### Catch-All Routes
 
-Create a catch-all route that only runs when no other routes match:
+Create a catch-all route that runs when no specific route handler has set a response.
+Check `!ctx.body` to determine whether a previous handler already responded:
 
 ```javascript
 router.get('/users', handler1);
@@ -850,13 +906,38 @@ router.get('/posts', handler2);
 
 // Catch-all for unmatched routes
 router.all('{/*rest}', (ctx) => {
-  if (!ctx.matched || ctx.matched.length === 0) {
+  if (!ctx.body) {
     ctx.status = 404;
     ctx.body = { error: 'Not Found' };
   }
 });
 ```
 
+> **Note:** `ctx.matched.length === 0` will never be true inside a catch-all handler.
+> The router populates `ctx.matched` **before** the handler body runs, so the catch-all
+> layer (`{/*rest}`) is already included in the array by the time your code executes.
+>
+> **Recommended:** Use `!ctx.body` as shown above — it is the simplest and most reliable
+> condition inside a catch-all route.
+>
+> **Workaround:** If you specifically need `ctx.matched`-based logic inside a catch-all,
+> filter out the catch-all layer first and check the remaining array:
+>
+> ```javascript
+> router.all('{/*rest}', (ctx) => {
+>   const realMatches = ctx.matched.filter(
+>     (layer) => layer.path !== '{/*rest}'
+>   );
+>   if (realMatches.length === 0) {
+>     ctx.status = 404;
+>     ctx.body = { error: 'Not Found' };
+>   }
+> });
+> ```
+>
+> For cleaner and more precise 404 detection, prefer app-level middleware with
+> `ctx.routeMatched` — see the [404 Handling](#404-handling) section.
+
 ### Array of Paths
 
 Register multiple paths with the same middleware:
@@ -868,12 +949,30 @@ router.get(['/users', '/people'], handler);
 
 ### 404 Handling
 
-Implement custom 404 handling:
+Implement custom 404 handling using app-level middleware after the router.
+
+**Using `ctx.routeMatched` (recommended):**
+
+```javascript
+app.use(router.routes());
+
+// ctx.routeMatched is set by the router before handlers run
+app.use((ctx) => {
+  if (!ctx.routeMatched) {
+    ctx.status = 404;
+    ctx.body = {
+      error: 'Not Found',
+      path: ctx.path
+    };
+  }
+});
+```
+
+**Using `ctx.matched`:**
 
 ```javascript
 app.use(router.routes());
 
-// 404 middleware - runs after router
 app.use((ctx) => {
   if (!ctx.matched || ctx.matched.length === 0) {
     ctx.status = 404;
@@ -885,6 +984,69 @@ app.use((ctx) => {
 });
 ```
 
+> For a router-scoped alternative that doesn't require app-level middleware,
+> see the [Not Found Event](#not-found-event-experimental) section below.
+
+### Not Found Event (Experimental)
+
+> **Note:** This API is experimental and may change in future versions.
+
+Use `router.on()` for a clean, dedicated 404 handler that runs only when no route
+matched — without needing a catch-all route. Three equivalent forms are supported:
+
+```javascript
+import { RouterEvents } from '@koa/router';
+
+// Named constant (recommended — autocomplete + refactor safe)
+router.on(RouterEvents.NotFound, handler);
+
+// Selector function (fluent style)
+router.on((events) => events.NotFound, handler);
+
+// Raw string (still accepted)
+router.on('not-found', handler);
+```
+
+Full example:
+
+```javascript
+import { RouterEvents } from '@koa/router';
+
+router.get('/users', handler1);
+router.get('/posts', handler2);
+
+router.on(RouterEvents.NotFound, (ctx) => {
+  ctx.status = 404;
+  ctx.body = {
+    error: 'Not Found',
+    path: ctx.path,
+    method: ctx.method
+  };
+});
+
+app.use(router.routes());
+```
+
+Multiple handlers are supported and compose in registration order:
+
+```javascript
+router.on(RouterEvents.NotFound, async (ctx, next) => {
+  console.log('no route matched:', ctx.path);
+  await next();
+});
+
+router.on(RouterEvents.NotFound, (ctx) => {
+  ctx.status = 404;
+  ctx.body = { error: 'Not Found' };
+});
+```
+
+Benefits over catch-all routes:
+
+- Does not appear in `ctx.matched`
+- Only fires when no route matched — no need to check `ctx.routeMatched` or `ctx.body`
+- Handlers compose naturally with `next()`
+
 ## Best Practices
 
 ### 1. Use Middleware Composition
@@ -983,6 +1145,9 @@ router.get('/users/:id', (ctx: RouterContext) => {
   // All matched layers
   const matched = ctx.matched; // Array of Layer objects
 
+  // Whether any route (with HTTP methods) was matched
+  const wasMatched = ctx.routeMatched; // boolean | undefined
+
   // Captured values from RegExp routes
   const captures = ctx.captures; // string[] | undefined
 
@@ -1043,11 +1208,13 @@ See the [recipes directory](./recipes/) for complete TypeScript examples:
 - **[Authentication & Authorization](./recipes/authentication-authorization/)** - JWT-based authentication with middleware
 - **[Request Validation](./recipes/request-validation/)** - Validate request data with middleware
 - **[Parameter Validation](./recipes/parameter-validation/)** - Validate and transform parameters using router.param()
+- **[Regex Parameter Validation](./recipes/regex-parameter-validation/)** - Validate URL parameters with regex (replacement for `:param(regex)` in v14+)
 - **[API Versioning](./recipes/api-versioning/)** - Implement API versioning with multiple routers
 - **[Error Handling](./recipes/error-handling/)** - Centralized error handling with custom error classes
 - **[Pagination](./recipes/pagination/)** - Implement pagination for list endpoints
 - **[Health Checks](./recipes/health-checks/)** - Add health check endpoints for monitoring
 - **[TypeScript Recipe](./recipes/typescript-recipe/)** - Full TypeScript example with types and type safety
+- **[Not Found Handling](./recipes/not-found-handling/)** - All approaches to handling unmatched routes: `ctx.routeMatched`, events, catch-all
 
 Each recipe file contains complete, runnable TypeScript code that you can copy and adapt to your needs.
 

package/dist/index.d.mts

@@ -172,6 +172,47 @@ declare class Layer<StateT = DefaultState, ContextT = DefaultContext, BodyT = un
     private _reconfigurePathMatching;
 }
 
+/**
+ * Named constants for active router lifecycle events.
+ *
+ * Only events that are fully implemented appear here. Planned events will be
+ * added as each one is implemented so the public API always reflects what
+ * actually works.
+ *
+ * @experimental
+ */
+declare const RouterEvents: {
+    /**
+     * Fires when no route matched the request path + HTTP method.
+     */
+    readonly NotFound: "not-found";
+};
+/**
+ * Union of all valid router event name strings.
+ * Derived from `RouterEvents` so the two are always in sync.
+ *
+ * @experimental
+ */
+type RouterEvent = (typeof RouterEvents)[keyof typeof RouterEvents];
+/**
+ * Accepts either a raw event name string or a selector function that receives
+ * the `RouterEvents` object and returns an event name.
+ *
+ * Both forms are equivalent — choose whichever reads better in context.
+ *
+ * @example
+ * ```typescript
+ * // string
+ * 'not-found'
+ *
+ * // selector function
+ * (events) => events.NotFound
+ * ```
+ *
+ * @experimental
+ */
+type RouterEventSelector = RouterEvent | ((events: typeof RouterEvents) => RouterEvent);
+
 type RouterInstance<StateT = koa.DefaultState, ContextT = koa.DefaultContext> = RouterImplementation<StateT, ContextT>;
 /**
  * Middleware with router property
@@ -189,6 +230,11 @@ declare class RouterImplementation<StateT = koa.DefaultState, ContextT = koa.Def
     params: Record<string, RouterParameterMiddleware<StateT, ContextT> | RouterParameterMiddleware<StateT, ContextT>[]>;
     stack: Layer<StateT, ContextT>[];
     host?: string | string[] | RegExp;
+    /**
+     * Event emitter for router lifecycle events (experimental)
+     * @internal
+     */
+    private _events;
     /**
      * Create a new router.
      *
@@ -356,6 +402,52 @@ declare class RouterImplementation<StateT = koa.DefaultState, ContextT = koa.Def
      */
     private _buildMiddlewareChain;
     routes(): RouterComposedMiddleware<StateT, ContextT>;
+    /**
+     * Register an event handler on the router.
+     *
+     * @experimental This API is experimental and may change in future versions.
+     *
+     * **Active events:**
+     * - `'not-found'` — fires when no route matched path + method. Handlers are
+     *   composed and called instead of `next()`, so they are responsible for
+     *   calling `next()` themselves if they want to pass control downstream.
+     *
+     * @example
+     *
+     * All three forms are equivalent:
+     *
+     * ```javascript
+     * import { RouterEvents } from '@koa/router';
+     *
+     * // Named constant (recommended — autocomplete + refactor safe)
+     * router.on(RouterEvents.NotFound, handler);
+     *
+     * // Selector function (fluent style)
+     * router.on((events) => events.NotFound, handler);
+     *
+     * // Raw string (still accepted)
+     * router.on('not-found', handler);
+     * ```
+     *
+     * Multiple handlers compose in registration order:
+     *
+     * ```javascript
+     * router.on(RouterEvents.NotFound, async (ctx, next) => {
+     *   console.log('no route matched', ctx.path);
+     *   await next();
+     * });
+     * router.on(RouterEvents.NotFound, (ctx) => {
+     *   ctx.status = 404;
+     *   ctx.body = { error: 'Not Found' };
+     * });
+     * ```
+     *
+     * @param event - Event name string, `RouterEvents` constant, or selector
+     *   function `(events) => events.NotFound` (see `RouterEventSelector`)
+     * @param handler - Middleware to run when the event fires
+     * @returns This router instance for chaining
+     */
+    on(event: RouterEventSelector, handler: RouterMiddleware<StateT, ContextT>): Router<StateT, ContextT>;
     /**
      * Returns separate middleware for responding to `OPTIONS` requests with
      * an `Allow` header containing the allowed methods, as well as responding
@@ -656,9 +748,18 @@ declare const Router: RouterConstructor;
 
 type RouterOptions = {
     /**
-     * Only run last matched route's controller when there are multiple matches
+     * Control which route is executed when multiple routes match a request.
+     *
+     * - `true` — run only the last registered matching route (legacy behaviour)
+     * - `'specificity'` — run only the most specific matching route, defined as
+     *   the one with the fewest path parameters. This is OpenAPI-compliant
+     *   (see https://spec.openapis.org/oas/v3.0.3#path-templating-matching) and
+     *   is the recommended mode for code generated from OpenAPI specifications.
+     *   When two routes have an equal number of parameters the last registered
+     *   one wins, preserving deterministic behaviour.
+     * - `false` / omitted — all matching routes run in registration order
      */
-    exclusive?: boolean;
+    exclusive?: boolean | 'specificity';
     /**
      * Prefix for all routes
      */
@@ -806,6 +907,25 @@ type RouterContext<StateT = DefaultState, ContextT = DefaultContext, BodyT = unk
      * Array of matched layers
      */
     matched?: Layer<StateT, ContextT, BodyT>[];
+    /**
+     * Whether a route (with HTTP methods) was matched for this request.
+     * Set by the router before any handlers run.
+     *
+     * Use this in app-level middleware after `router.routes()` to detect
+     * requests that the router did not handle.
+     *
+     * @example
+     * ```javascript
+     * app.use(router.routes());
+     * app.use((ctx) => {
+     *   if (!ctx.routeMatched) {
+     *     ctx.status = 404;
+     *     ctx.body = { error: 'Not Found' };
+     *   }
+     * });
+     * ```
+     */
+    routeMatched?: boolean;
     /**
      * Captured values from path
      */
@@ -889,4 +1009,4 @@ type ParameterValidationOptions = {
  */
 declare function createParameterValidationMiddleware(parameterName: string, pattern: RegExp, options?: ParameterValidationOptions): RouterMiddleware<any, any, any> & RouterParameterMiddleware<any, any, any>;
 
-export { type AllowedMethodsOptions, type HttpMethod, Layer, type LayerOptions, type MatchResult, type ParameterValidationOptions, Router, type RouterContext, type RouterInstance, type RouterMethodFunction, type RouterMiddleware, type RouterOptions, type RouterOptionsWithMethods, type RouterParameterMiddleware, type RouterWithMethods, type UrlOptions, createParameterValidationMiddleware, Router as default };
+export { type AllowedMethodsOptions, type HttpMethod, Layer, type LayerOptions, type MatchResult, type ParameterValidationOptions, Router, type RouterContext, type RouterEvent, type RouterEventSelector, RouterEvents, type RouterInstance, type RouterMethodFunction, type RouterMiddleware, type RouterOptions, type RouterOptionsWithMethods, type RouterParameterMiddleware, type RouterWithMethods, type UrlOptions, createParameterValidationMiddleware, Router as default };

package/dist/index.d.ts

@@ -172,6 +172,47 @@ declare class Layer<StateT = DefaultState, ContextT = DefaultContext, BodyT = un
     private _reconfigurePathMatching;
 }
 
+/**
+ * Named constants for active router lifecycle events.
+ *
+ * Only events that are fully implemented appear here. Planned events will be
+ * added as each one is implemented so the public API always reflects what
+ * actually works.
+ *
+ * @experimental
+ */
+declare const RouterEvents: {
+    /**
+     * Fires when no route matched the request path + HTTP method.
+     */
+    readonly NotFound: "not-found";
+};
+/**
+ * Union of all valid router event name strings.
+ * Derived from `RouterEvents` so the two are always in sync.
+ *
+ * @experimental
+ */
+type RouterEvent = (typeof RouterEvents)[keyof typeof RouterEvents];
+/**
+ * Accepts either a raw event name string or a selector function that receives
+ * the `RouterEvents` object and returns an event name.
+ *
+ * Both forms are equivalent — choose whichever reads better in context.
+ *
+ * @example
+ * ```typescript
+ * // string
+ * 'not-found'
+ *
+ * // selector function
+ * (events) => events.NotFound
+ * ```
+ *
+ * @experimental
+ */
+type RouterEventSelector = RouterEvent | ((events: typeof RouterEvents) => RouterEvent);
+
 type RouterInstance<StateT = koa.DefaultState, ContextT = koa.DefaultContext> = RouterImplementation<StateT, ContextT>;
 /**
  * Middleware with router property
@@ -189,6 +230,11 @@ declare class RouterImplementation<StateT = koa.DefaultState, ContextT = koa.Def
     params: Record<string, RouterParameterMiddleware<StateT, ContextT> | RouterParameterMiddleware<StateT, ContextT>[]>;
     stack: Layer<StateT, ContextT>[];
     host?: string | string[] | RegExp;
+    /**
+     * Event emitter for router lifecycle events (experimental)
+     * @internal
+     */
+    private _events;
     /**
      * Create a new router.
      *
@@ -356,6 +402,52 @@ declare class RouterImplementation<StateT = koa.DefaultState, ContextT = koa.Def
      */
     private _buildMiddlewareChain;
     routes(): RouterComposedMiddleware<StateT, ContextT>;
+    /**
+     * Register an event handler on the router.
+     *
+     * @experimental This API is experimental and may change in future versions.
+     *
+     * **Active events:**
+     * - `'not-found'` — fires when no route matched path + method. Handlers are
+     *   composed and called instead of `next()`, so they are responsible for
+     *   calling `next()` themselves if they want to pass control downstream.
+     *
+     * @example
+     *
+     * All three forms are equivalent:
+     *
+     * ```javascript
+     * import { RouterEvents } from '@koa/router';
+     *
+     * // Named constant (recommended — autocomplete + refactor safe)
+     * router.on(RouterEvents.NotFound, handler);
+     *
+     * // Selector function (fluent style)
+     * router.on((events) => events.NotFound, handler);
+     *
+     * // Raw string (still accepted)
+     * router.on('not-found', handler);
+     * ```
+     *
+     * Multiple handlers compose in registration order:
+     *
+     * ```javascript
+     * router.on(RouterEvents.NotFound, async (ctx, next) => {
+     *   console.log('no route matched', ctx.path);
+     *   await next();
+     * });
+     * router.on(RouterEvents.NotFound, (ctx) => {
+     *   ctx.status = 404;
+     *   ctx.body = { error: 'Not Found' };
+     * });
+     * ```
+     *
+     * @param event - Event name string, `RouterEvents` constant, or selector
+     *   function `(events) => events.NotFound` (see `RouterEventSelector`)
+     * @param handler - Middleware to run when the event fires
+     * @returns This router instance for chaining
+     */
+    on(event: RouterEventSelector, handler: RouterMiddleware<StateT, ContextT>): Router<StateT, ContextT>;
     /**
      * Returns separate middleware for responding to `OPTIONS` requests with
      * an `Allow` header containing the allowed methods, as well as responding
@@ -656,9 +748,18 @@ declare const Router: RouterConstructor;
 
 type RouterOptions = {
     /**
-     * Only run last matched route's controller when there are multiple matches
+     * Control which route is executed when multiple routes match a request.
+     *
+     * - `true` — run only the last registered matching route (legacy behaviour)
+     * - `'specificity'` — run only the most specific matching route, defined as
+     *   the one with the fewest path parameters. This is OpenAPI-compliant
+     *   (see https://spec.openapis.org/oas/v3.0.3#path-templating-matching) and
+     *   is the recommended mode for code generated from OpenAPI specifications.
+     *   When two routes have an equal number of parameters the last registered
+     *   one wins, preserving deterministic behaviour.
+     * - `false` / omitted — all matching routes run in registration order
      */
-    exclusive?: boolean;
+    exclusive?: boolean | 'specificity';
     /**
      * Prefix for all routes
      */
@@ -806,6 +907,25 @@ type RouterContext<StateT = DefaultState, ContextT = DefaultContext, BodyT = unk
      * Array of matched layers
      */
     matched?: Layer<StateT, ContextT, BodyT>[];
+    /**
+     * Whether a route (with HTTP methods) was matched for this request.
+     * Set by the router before any handlers run.
+     *
+     * Use this in app-level middleware after `router.routes()` to detect
+     * requests that the router did not handle.
+     *
+     * @example
+     * ```javascript
+     * app.use(router.routes());
+     * app.use((ctx) => {
+     *   if (!ctx.routeMatched) {
+     *     ctx.status = 404;
+     *     ctx.body = { error: 'Not Found' };
+     *   }
+     * });
+     * ```
+     */
+    routeMatched?: boolean;
     /**
      * Captured values from path
      */
@@ -889,4 +1009,4 @@ type ParameterValidationOptions = {
  */
 declare function createParameterValidationMiddleware(parameterName: string, pattern: RegExp, options?: ParameterValidationOptions): RouterMiddleware<any, any, any> & RouterParameterMiddleware<any, any, any>;
 
-export { type AllowedMethodsOptions, type HttpMethod, Layer, type LayerOptions, type MatchResult, type ParameterValidationOptions, Router, type RouterContext, type RouterInstance, type RouterMethodFunction, type RouterMiddleware, type RouterOptions, type RouterOptionsWithMethods, type RouterParameterMiddleware, type RouterWithMethods, type UrlOptions, createParameterValidationMiddleware, Router as default };
+export { type AllowedMethodsOptions, type HttpMethod, Layer, type LayerOptions, type MatchResult, type ParameterValidationOptions, Router, type RouterContext, type RouterEvent, type RouterEventSelector, RouterEvents, type RouterInstance, type RouterMethodFunction, type RouterMiddleware, type RouterOptions, type RouterOptionsWithMethods, type RouterParameterMiddleware, type RouterWithMethods, type UrlOptions, createParameterValidationMiddleware, Router as default };

package/dist/index.js

@@ -31,11 +31,72 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   Router: () => Router,
+  RouterEvents: () => RouterEvents,
   createParameterValidationMiddleware: () => createParameterValidationMiddleware,
   default: () => router_default
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/utils/router-events.ts
+var import_koa_compose = __toESM(require("koa-compose"));
+var RouterEvents = {
+  /**
+   * Fires when no route matched the request path + HTTP method.
+   */
+  NotFound: "not-found"
+  // /**
+  //  * Fires when the request path matched a registered route but the HTTP
+  //  * method did not match any of its allowed methods.
+  //  *
+  //  * @planned Not yet active — handlers are stored but not called.
+  //  */
+  // MethodNotAllowed: 'method-not-allowed',
+  // /**
+  //  * Fires after a route is matched and before its handlers run.
+  //  * Useful for tracing and logging the matched route.
+  //  *
+  //  * @planned Not yet active — handlers are stored but not called.
+  //  */
+  // Match: 'match',
+  // /**
+  //  * Fires on every request that enters the router, before route matching.
+  //  * Useful for per-router metrics and request logging.
+  //  *
+  //  * @planned Not yet active — handlers are stored but not called.
+  //  */
+  // Dispatch: 'dispatch'
+};
+function resolveEvent(selector) {
+  return typeof selector === "function" ? selector(RouterEvents) : selector;
+}
+var RouterEventEmitter = class {
+  _handlers = /* @__PURE__ */ new Map();
+  /**
+   * Register a handler for the given event.
+   * Multiple handlers for the same event are composed in registration order.
+   */
+  register(event, handler) {
+    const existing = this._handlers.get(event) ?? [];
+    existing.push(handler);
+    this._handlers.set(event, existing);
+  }
+  /**
+   * Emit an event by composing and running all registered handlers.
+   * If no handlers are registered for the event, calls `next()` directly.
+   *
+   * @param event   - The event to emit
+   * @param context - The router context
+   * @param next    - The downstream next function
+   */
+  emit(event, context, next) {
+    const handlers = this._handlers.get(event);
+    if (handlers && handlers.length > 0) {
+      return (0, import_koa_compose.default)(handlers)(context, next);
+    }
+    return next();
+  }
+};
+
 // src/utils/parameter-match.ts
 var import_http_errors = __toESM(require("http-errors"));
 function createParameterValidationMiddleware(parameterName, pattern, options = {}) {
@@ -86,7 +147,7 @@ function createParameterValidationMiddleware(parameterName, pattern, options = {
 }
 
 // src/router.ts
-var import_koa_compose = __toESM(require("koa-compose"));
+var import_koa_compose2 = __toESM(require("koa-compose"));
 var import_http_errors2 = __toESM(require("http-errors"));
 
 // src/layer.ts
@@ -651,6 +712,11 @@ var RouterImplementation = class {
   params;
   stack;
   host;
+  /**
+   * Event emitter for router lifecycle events (experimental)
+   * @internal
+   */
+  _events = new RouterEventEmitter();
   /**
    * Create a new router.
    *
@@ -900,8 +966,11 @@ var RouterImplementation = class {
     const previousPrefix = this.opts.prefix || "";
     this.opts.prefix = normalizedPrefix;
     for (const route of this.stack) {
-      if (previousPrefix && typeof route.path === "string" && route.path.startsWith(previousPrefix)) {
-        route.path = route.path.slice(previousPrefix.length) || "/";
+      if (typeof route.path === "string" && previousPrefix) {
+        const stripBoundary = previousPrefix + "/";
+        if (route.path === previousPrefix || route.path.startsWith(stripBoundary)) {
+          route.path = route.path.slice(previousPrefix.length) || "/";
+        }
       }
       route.setPrefix(normalizedPrefix);
     }
@@ -922,8 +991,13 @@ var RouterImplementation = class {
       const matchResult = this.match(requestPath, context.method);
       this._storeMatchedRoutes(context, matchResult);
       context.router = this;
+      context.routeMatched = matchResult.route;
       if (!matchResult.route) {
-        return next();
+        return this._events.emit(
+          RouterEvents.NotFound,
+          context,
+          next
+        );
       }
       const matchedLayers = matchResult.pathAndMethod;
       this._setMatchedRouteInfo(context, matchedLayers);
@@ -931,7 +1005,7 @@ var RouterImplementation = class {
         matchedLayers,
         requestPath
       );
-      return (0, import_koa_compose.default)(middlewareChain)(
+      return (0, import_koa_compose2.default)(middlewareChain)(
         context,
         next
       );
@@ -978,9 +1052,22 @@ var RouterImplementation = class {
    * @private
    */
   _buildMiddlewareChain(matchedLayers, requestPath) {
-    const layersToExecute = this.opts.exclusive ? [matchedLayers.at(-1)].filter(
-      (layer) => layer !== void 0
-    ) : matchedLayers;
+    let layersToExecute;
+    if (this.exclusive) {
+      let chosenLayer;
+      if (this.opts.exclusive === "specificity") {
+        for (const layer of matchedLayers) {
+          if (!chosenLayer || layer.paramNames.length < chosenLayer.paramNames.length) {
+            chosenLayer = layer;
+          }
+        }
+      } else {
+        chosenLayer = matchedLayers.at(-1);
+      }
+      layersToExecute = chosenLayer ? [chosenLayer] : [];
+    } else {
+      layersToExecute = matchedLayers;
+    }
     const middlewareChain = [];
     for (const layer of layersToExecute) {
       middlewareChain.push(
@@ -1009,6 +1096,55 @@ var RouterImplementation = class {
   routes() {
     return this.middleware();
   }
+  /**
+   * Register an event handler on the router.
+   *
+   * @experimental This API is experimental and may change in future versions.
+   *
+   * **Active events:**
+   * - `'not-found'` — fires when no route matched path + method. Handlers are
+   *   composed and called instead of `next()`, so they are responsible for
+   *   calling `next()` themselves if they want to pass control downstream.
+   *
+   * @example
+   *
+   * All three forms are equivalent:
+   *
+   * ```javascript
+   * import { RouterEvents } from '@koa/router';
+   *
+   * // Named constant (recommended — autocomplete + refactor safe)
+   * router.on(RouterEvents.NotFound, handler);
+   *
+   * // Selector function (fluent style)
+   * router.on((events) => events.NotFound, handler);
+   *
+   * // Raw string (still accepted)
+   * router.on('not-found', handler);
+   * ```
+   *
+   * Multiple handlers compose in registration order:
+   *
+   * ```javascript
+   * router.on(RouterEvents.NotFound, async (ctx, next) => {
+   *   console.log('no route matched', ctx.path);
+   *   await next();
+   * });
+   * router.on(RouterEvents.NotFound, (ctx) => {
+   *   ctx.status = 404;
+   *   ctx.body = { error: 'Not Found' };
+   * });
+   * ```
+   *
+   * @param event - Event name string, `RouterEvents` constant, or selector
+   *   function `(events) => events.NotFound` (see `RouterEventSelector`)
+   * @param handler - Middleware to run when the event fires
+   * @returns This router instance for chaining
+   */
+  on(event, handler) {
+    this._events.register(resolveEvent(event), handler);
+    return this;
+  }
   /**
    * Returns separate middleware for responding to `OPTIONS` requests with
    * an `Allow` header containing the allowed methods, as well as responding
@@ -1487,6 +1623,7 @@ for (const httpMethod of httpMethods) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Router,
+  RouterEvents,
   createParameterValidationMiddleware
 });
 if (module.exports.default) {

package/dist/index.mjs

@@ -1,3 +1,63 @@
+// src/utils/router-events.ts
+import compose from "koa-compose";
+var RouterEvents = {
+  /**
+   * Fires when no route matched the request path + HTTP method.
+   */
+  NotFound: "not-found"
+  // /**
+  //  * Fires when the request path matched a registered route but the HTTP
+  //  * method did not match any of its allowed methods.
+  //  *
+  //  * @planned Not yet active — handlers are stored but not called.
+  //  */
+  // MethodNotAllowed: 'method-not-allowed',
+  // /**
+  //  * Fires after a route is matched and before its handlers run.
+  //  * Useful for tracing and logging the matched route.
+  //  *
+  //  * @planned Not yet active — handlers are stored but not called.
+  //  */
+  // Match: 'match',
+  // /**
+  //  * Fires on every request that enters the router, before route matching.
+  //  * Useful for per-router metrics and request logging.
+  //  *
+  //  * @planned Not yet active — handlers are stored but not called.
+  //  */
+  // Dispatch: 'dispatch'
+};
+function resolveEvent(selector) {
+  return typeof selector === "function" ? selector(RouterEvents) : selector;
+}
+var RouterEventEmitter = class {
+  _handlers = /* @__PURE__ */ new Map();
+  /**
+   * Register a handler for the given event.
+   * Multiple handlers for the same event are composed in registration order.
+   */
+  register(event, handler) {
+    const existing = this._handlers.get(event) ?? [];
+    existing.push(handler);
+    this._handlers.set(event, existing);
+  }
+  /**
+   * Emit an event by composing and running all registered handlers.
+   * If no handlers are registered for the event, calls `next()` directly.
+   *
+   * @param event   - The event to emit
+   * @param context - The router context
+   * @param next    - The downstream next function
+   */
+  emit(event, context, next) {
+    const handlers = this._handlers.get(event);
+    if (handlers && handlers.length > 0) {
+      return compose(handlers)(context, next);
+    }
+    return next();
+  }
+};
+
 // src/utils/parameter-match.ts
 import createHttpError from "http-errors";
 function createParameterValidationMiddleware(parameterName, pattern, options = {}) {
@@ -48,7 +108,7 @@ function createParameterValidationMiddleware(parameterName, pattern, options = {
 }
 
 // src/router.ts
-import compose from "koa-compose";
+import compose2 from "koa-compose";
 import HttpError from "http-errors";
 
 // src/layer.ts
@@ -613,6 +673,11 @@ var RouterImplementation = class {
   params;
   stack;
   host;
+  /**
+   * Event emitter for router lifecycle events (experimental)
+   * @internal
+   */
+  _events = new RouterEventEmitter();
   /**
    * Create a new router.
    *
@@ -862,8 +927,11 @@ var RouterImplementation = class {
     const previousPrefix = this.opts.prefix || "";
     this.opts.prefix = normalizedPrefix;
     for (const route of this.stack) {
-      if (previousPrefix && typeof route.path === "string" && route.path.startsWith(previousPrefix)) {
-        route.path = route.path.slice(previousPrefix.length) || "/";
+      if (typeof route.path === "string" && previousPrefix) {
+        const stripBoundary = previousPrefix + "/";
+        if (route.path === previousPrefix || route.path.startsWith(stripBoundary)) {
+          route.path = route.path.slice(previousPrefix.length) || "/";
+        }
       }
       route.setPrefix(normalizedPrefix);
     }
@@ -884,8 +952,13 @@ var RouterImplementation = class {
       const matchResult = this.match(requestPath, context.method);
       this._storeMatchedRoutes(context, matchResult);
       context.router = this;
+      context.routeMatched = matchResult.route;
       if (!matchResult.route) {
-        return next();
+        return this._events.emit(
+          RouterEvents.NotFound,
+          context,
+          next
+        );
       }
       const matchedLayers = matchResult.pathAndMethod;
       this._setMatchedRouteInfo(context, matchedLayers);
@@ -893,7 +966,7 @@ var RouterImplementation = class {
         matchedLayers,
         requestPath
       );
-      return compose(middlewareChain)(
+      return compose2(middlewareChain)(
         context,
         next
       );
@@ -940,9 +1013,22 @@ var RouterImplementation = class {
    * @private
    */
   _buildMiddlewareChain(matchedLayers, requestPath) {
-    const layersToExecute = this.opts.exclusive ? [matchedLayers.at(-1)].filter(
-      (layer) => layer !== void 0
-    ) : matchedLayers;
+    let layersToExecute;
+    if (this.exclusive) {
+      let chosenLayer;
+      if (this.opts.exclusive === "specificity") {
+        for (const layer of matchedLayers) {
+          if (!chosenLayer || layer.paramNames.length < chosenLayer.paramNames.length) {
+            chosenLayer = layer;
+          }
+        }
+      } else {
+        chosenLayer = matchedLayers.at(-1);
+      }
+      layersToExecute = chosenLayer ? [chosenLayer] : [];
+    } else {
+      layersToExecute = matchedLayers;
+    }
     const middlewareChain = [];
     for (const layer of layersToExecute) {
       middlewareChain.push(
@@ -971,6 +1057,55 @@ var RouterImplementation = class {
   routes() {
     return this.middleware();
   }
+  /**
+   * Register an event handler on the router.
+   *
+   * @experimental This API is experimental and may change in future versions.
+   *
+   * **Active events:**
+   * - `'not-found'` — fires when no route matched path + method. Handlers are
+   *   composed and called instead of `next()`, so they are responsible for
+   *   calling `next()` themselves if they want to pass control downstream.
+   *
+   * @example
+   *
+   * All three forms are equivalent:
+   *
+   * ```javascript
+   * import { RouterEvents } from '@koa/router';
+   *
+   * // Named constant (recommended — autocomplete + refactor safe)
+   * router.on(RouterEvents.NotFound, handler);
+   *
+   * // Selector function (fluent style)
+   * router.on((events) => events.NotFound, handler);
+   *
+   * // Raw string (still accepted)
+   * router.on('not-found', handler);
+   * ```
+   *
+   * Multiple handlers compose in registration order:
+   *
+   * ```javascript
+   * router.on(RouterEvents.NotFound, async (ctx, next) => {
+   *   console.log('no route matched', ctx.path);
+   *   await next();
+   * });
+   * router.on(RouterEvents.NotFound, (ctx) => {
+   *   ctx.status = 404;
+   *   ctx.body = { error: 'Not Found' };
+   * });
+   * ```
+   *
+   * @param event - Event name string, `RouterEvents` constant, or selector
+   *   function `(events) => events.NotFound` (see `RouterEventSelector`)
+   * @param handler - Middleware to run when the event fires
+   * @returns This router instance for chaining
+   */
+  on(event, handler) {
+    this._events.register(resolveEvent(event), handler);
+    return this;
+  }
   /**
    * Returns separate middleware for responding to `OPTIONS` requests with
    * an `Allow` header containing the allowed methods, as well as responding
@@ -1448,6 +1583,7 @@ for (const httpMethod of httpMethods) {
 }
 export {
   Router,
+  RouterEvents,
   createParameterValidationMiddleware,
   router_default as default
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@koa/router",
   "description": "Router middleware for Koa.",
-  "version": "15.3.2",
+  "version": "15.5.0",
   "author": "Koa.js",
   "bugs": {
     "url": "https://github.com/koajs/router/issues",
@@ -28,31 +28,31 @@
     "debug": "^4.4.3",
     "http-errors": "^2.0.1",
     "koa-compose": "^4.1.0",
-    "path-to-regexp": "^8.3.0"
+    "path-to-regexp": "^8.4.2"
   },
   "devDependencies": {
-    "@commitlint/cli": "^20.4.4",
-    "@commitlint/config-conventional": "^20.4.4",
+    "@commitlint/cli": "^20.5.3",
+    "@commitlint/config-conventional": "^20.5.3",
     "@eslint/js": "^10.0.1",
     "@koa/bodyparser": "^6.1.0",
-    "@types/debug": "^4.1.12",
+    "@types/debug": "^4.1.13",
     "@types/jsonwebtoken": "^9.0.10",
-    "@types/koa": "^3.0.1",
-    "@types/node": "^25.5.0",
+    "@types/koa": "^3.0.2",
+    "@types/node": "^25.6.0",
     "@types/supertest": "^7.2.0",
-    "@typescript-eslint/eslint-plugin": "^8.57.0",
-    "@typescript-eslint/parser": "^8.57.0",
+    "@typescript-eslint/eslint-plugin": "^8.59.1",
+    "@typescript-eslint/parser": "^8.59.1",
     "c8": "^11.0.0",
     "chalk": "^5.6.2",
-    "eslint": "^10.0.3",
-    "eslint-plugin-unicorn": "^63.0.0",
+    "eslint": "^10.3.0",
+    "eslint-plugin-unicorn": "^64.0.0",
     "husky": "^9.1.7",
-    "joi": "^18.0.2",
+    "joi": "^18.1.2",
     "jsonwebtoken": "^9.0.3",
-    "koa": "^3.1.2",
+    "koa": "^3.2.0",
     "lint-staged": "^16.4.0",
-    "np": "^11.0.2",
-    "prettier": "^3.8.1",
+    "np": "^11.2.0",
+    "prettier": "^3.8.3",
     "rimraf": "^6.1.3",
     "supertest": "^7.2.2",
     "ts-node": "^10.9.2",