@koa/router 15.4.0 → 15.6.0

package/README.md

@@ -40,6 +40,7 @@
 - ✅ **405 Method Not Allowed** - Automatic method validation
 - ✅ **501 Not Implemented** - Proper HTTP status codes
 - ✅ **Async/Await** - Full promise-based middleware support
+- ✅ **Clean ctx.params** - Only URL parameters you define are present in `ctx.params`; no internal routing keys leak out
 
 ## Installation
 
@@ -266,14 +267,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:**
 
@@ -457,7 +458,26 @@ router.get('/users', (ctx) => {
 // Responds to /api/v1/users, /api/v2/users, etc.
 ```
 
-**Note:** Middleware now correctly executes when the prefix contains parameters.
+**Middleware on a parameterized prefix:**
+
+When `router.use()` is attached to a router whose prefix contains URL parameters, `ctx.params` inside the middleware will contain **only** the parameters defined by the prefix — no internal routing keys are ever added.
+
+```javascript
+const router = new Router({ prefix: '/:tenantId' });
+
+// Auth / authz middleware — receives only the defined prefix param
+router.use(async (ctx, next) => {
+  console.log(ctx.params); // => { tenantId: 'acme' }  (no extraneous keys)
+  await next();
+});
+
+router.get('/users', (ctx) => {
+  console.log(ctx.params); // => { tenantId: 'acme' }
+  ctx.body = ctx.params;
+});
+```
+
+This is particularly useful when running **strict parameter validation** inside a `router.use()` middleware — the shape of `ctx.params` is predictable and contains only what you defined.
 
 ### URL Parameters
 
@@ -565,6 +585,8 @@ router.use('/nested', nestedRouter.routes());
 
 **Note:** Middleware path boundaries are correctly enforced. Middleware scoped to `/api` will only run for routes matching `/api/*`, not for unrelated routes.
 
+**Note:** When `router.use()` is used on a router with a parameterized prefix (e.g. `prefix: '/:id'`), `ctx.params` inside that middleware will contain **only** the parameters defined by the prefix and route path — no internal wildcard keys are exposed. See [Router Prefixes](#router-prefixes) for a full example.
+
 ### router.prefix()
 
 Set the path prefix for a Router instance after initialization.

package/dist/index.d.mts

@@ -748,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
      */
@@ -812,6 +821,12 @@ type LayerOptions = {
      * Ignore captures in route matching
      */
     ignoreCaptures?: boolean;
+    /**
+     * Ignore a generated wildcard route parameter when populating ctx.params
+     *
+     * @internal
+     */
+    ignoreWildcardParameter?: string | number;
     /**
      * Treat path as a regular expression
      */

package/dist/index.d.ts

@@ -748,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
      */
@@ -812,6 +821,12 @@ type LayerOptions = {
      * Ignore captures in route matching
      */
     ignoreCaptures?: boolean;
+    /**
+     * Ignore a generated wildcard route parameter when populating ctx.params
+     *
+     * @internal
+     */
+    ignoreWildcardParameter?: string | number;
     /**
      * Treat path as a regular expression
      */

package/dist/index.js

@@ -310,6 +310,9 @@ var Layer = class {
       const parameterDefinition = this.paramNames[captureIndex];
       if (parameterDefinition && capturedValue && capturedValue.length > 0) {
         const parameterName = parameterDefinition.name;
+        if (this.opts.ignoreWildcardParameter === parameterName && parameterDefinition.type === "wildcard") {
+          continue;
+        }
         parameterValues[parameterName] = safeDecodeURIComponent(capturedValue);
       }
     }
@@ -942,9 +945,11 @@ var RouterImplementation = class {
       finalPath = middlewarePath;
       usePathToRegexp = false;
     }
+    const ignoreWildcardParameter = effectiveExplicitPath === "" && middlewarePath === "{/*rest}" ? "rest" : void 0;
     this.register(finalPath, [], middleware, {
       end: isRootPath,
       ignoreCaptures: !effectiveHasExplicitPath && !prefixHasParameters,
+      ignoreWildcardParameter,
       pathAsRegExp: usePathToRegexp
     });
   }
@@ -966,8 +971,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);
     }
@@ -1049,9 +1057,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(
@@ -1381,6 +1402,7 @@ var RouterImplementation = class {
       strict: options.strict || false,
       prefix: options.prefix || "",
       ignoreCaptures: options.ignoreCaptures,
+      ignoreWildcardParameter: options.ignoreWildcardParameter,
       pathAsRegExp: options.pathAsRegExp
     });
   }

package/dist/index.mjs

@@ -271,6 +271,9 @@ var Layer = class {
       const parameterDefinition = this.paramNames[captureIndex];
       if (parameterDefinition && capturedValue && capturedValue.length > 0) {
         const parameterName = parameterDefinition.name;
+        if (this.opts.ignoreWildcardParameter === parameterName && parameterDefinition.type === "wildcard") {
+          continue;
+        }
         parameterValues[parameterName] = safeDecodeURIComponent(capturedValue);
       }
     }
@@ -903,9 +906,11 @@ var RouterImplementation = class {
       finalPath = middlewarePath;
       usePathToRegexp = false;
     }
+    const ignoreWildcardParameter = effectiveExplicitPath === "" && middlewarePath === "{/*rest}" ? "rest" : void 0;
     this.register(finalPath, [], middleware, {
       end: isRootPath,
       ignoreCaptures: !effectiveHasExplicitPath && !prefixHasParameters,
+      ignoreWildcardParameter,
       pathAsRegExp: usePathToRegexp
     });
   }
@@ -927,8 +932,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);
     }
@@ -1010,9 +1018,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(
@@ -1342,6 +1363,7 @@ var RouterImplementation = class {
       strict: options.strict || false,
       prefix: options.prefix || "",
       ignoreCaptures: options.ignoreCaptures,
+      ignoreWildcardParameter: options.ignoreWildcardParameter,
       pathAsRegExp: options.pathAsRegExp
     });
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@koa/router",
   "description": "Router middleware for Koa.",
-  "version": "15.4.0",
+  "version": "15.6.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": "^21.0.2",
+    "@commitlint/config-conventional": "^21.0.2",
     "@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.3",
+    "@types/node": "^25.9.1",
     "@types/supertest": "^7.2.0",
-    "@typescript-eslint/eslint-plugin": "^8.57.0",
-    "@typescript-eslint/parser": "^8.57.0",
+    "@typescript-eslint/eslint-plugin": "^8.60.0",
+    "@typescript-eslint/parser": "^8.60.0",
     "c8": "^11.0.0",
     "chalk": "^5.6.2",
-    "eslint": "^10.0.3",
-    "eslint-plugin-unicorn": "^63.0.0",
+    "eslint": "^10.4.1",
+    "eslint-plugin-unicorn": "^64.0.0",
     "husky": "^9.1.7",
-    "joi": "^18.0.2",
+    "joi": "^18.2.1",
     "jsonwebtoken": "^9.0.3",
-    "koa": "^3.1.2",
-    "lint-staged": "^16.4.0",
-    "np": "^11.0.2",
-    "prettier": "^3.8.1",
+    "koa": "^3.2.1",
+    "lint-staged": "^17.0.6",
+    "np": "^11.2.1",
+    "prettier": "^3.8.3",
     "rimraf": "^6.1.3",
     "supertest": "^7.2.2",
     "ts-node": "^10.9.2",