@koa/router 15.5.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
 
@@ -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

@@ -821,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

@@ -821,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
     });
   }
@@ -1397,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
     });
   }
@@ -1358,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.5.0",
+  "version": "15.6.0",
   "author": "Koa.js",
   "bugs": {
     "url": "https://github.com/koajs/router/issues",
@@ -31,27 +31,27 @@
     "path-to-regexp": "^8.4.2"
   },
   "devDependencies": {
-    "@commitlint/cli": "^20.5.3",
-    "@commitlint/config-conventional": "^20.5.3",
+    "@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.13",
     "@types/jsonwebtoken": "^9.0.10",
-    "@types/koa": "^3.0.2",
-    "@types/node": "^25.6.0",
+    "@types/koa": "^3.0.3",
+    "@types/node": "^25.9.1",
     "@types/supertest": "^7.2.0",
-    "@typescript-eslint/eslint-plugin": "^8.59.1",
-    "@typescript-eslint/parser": "^8.59.1",
+    "@typescript-eslint/eslint-plugin": "^8.60.0",
+    "@typescript-eslint/parser": "^8.60.0",
     "c8": "^11.0.0",
     "chalk": "^5.6.2",
-    "eslint": "^10.3.0",
+    "eslint": "^10.4.1",
     "eslint-plugin-unicorn": "^64.0.0",
     "husky": "^9.1.7",
-    "joi": "^18.1.2",
+    "joi": "^18.2.1",
     "jsonwebtoken": "^9.0.3",
-    "koa": "^3.2.0",
-    "lint-staged": "^16.4.0",
-    "np": "^11.2.0",
+    "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",