@koa/router 15.5.0 → 15.7.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);
       }
     }
@@ -516,12 +519,12 @@ var Layer = class {
    * @private
    */
   _insertParamMiddleware(middlewareStack, parameterMiddleware, parameterNamesList, currentParameterPosition) {
-    let inserted = false;
+    let isInserted = false;
     for (let stackIndex = 0; stackIndex < middlewareStack.length; stackIndex++) {
       const existingMiddleware = middlewareStack[stackIndex];
       if (!existingMiddleware.param) {
         middlewareStack.splice(stackIndex, 0, parameterMiddleware);
-        inserted = true;
+        isInserted = true;
         break;
       }
       const existingParameterPosition = parameterNamesList.indexOf(
@@ -529,11 +532,11 @@ var Layer = class {
       );
       if (existingParameterPosition > currentParameterPosition) {
         middlewareStack.splice(stackIndex, 0, parameterMiddleware);
-        inserted = true;
+        isInserted = true;
         break;
       }
     }
-    if (!inserted) {
+    if (!isInserted) {
       middlewareStack.push(parameterMiddleware);
     }
   }
@@ -562,9 +565,9 @@ var Layer = class {
   _applyPrefix(prefixPath) {
     const isRootPath = this.path === "/";
     const isStrictMode = this.opts.strict === true;
-    const prefixHasParameters = prefixPath.includes(":");
-    const pathIsRawRegex = this.opts.pathAsRegExp === true && typeof this.path === "string";
-    if (prefixHasParameters && pathIsRawRegex) {
+    const isPrefixHasParameters = prefixPath.includes(":");
+    const isPathIsRawRegex = this.opts.pathAsRegExp === true && typeof this.path === "string";
+    if (isPrefixHasParameters && isPathIsRawRegex) {
       const currentPath = this.path;
       if (currentPath === String.raw`(?:\/|$)` || currentPath === String.raw`(?:\\\/|$)`) {
         this.path = "{/*rest}";
@@ -581,9 +584,9 @@ var Layer = class {
    * @private
    */
   _reconfigurePathMatching(prefixPath) {
-    const treatAsRegExp = this.opts.pathAsRegExp === true;
+    const isTreatAsRegExp = this.opts.pathAsRegExp === true;
     const prefixHasParameters = prefixPath && prefixPath.includes(":");
-    if (prefixHasParameters && treatAsRegExp) {
+    if (prefixHasParameters && isTreatAsRegExp) {
       const options = normalizeLayerOptionsToPathToRegexp(this.opts);
       const { regexp, keys } = compilePathToRegexp(
         this.path,
@@ -592,7 +595,7 @@ var Layer = class {
       this.regexp = regexp;
       this.paramNames = keys;
       this.opts.pathAsRegExp = false;
-    } else if (treatAsRegExp) {
+    } else if (isTreatAsRegExp) {
       const pathString = this.path;
       const anchoredPattern = pathString.startsWith("^") ? pathString : `^${pathString}`;
       this.regexp = this.path instanceof RegExp ? this.path : new RegExp(anchoredPattern);
@@ -780,10 +783,10 @@ var RouterImplementation = class {
     return temporaryLayer.url(...arguments_);
   }
   use(...middleware) {
-    let explicitPath;
     if (this._isPathArray(middleware[0])) {
       return this._useWithPathArray(middleware);
     }
+    let explicitPath;
     const hasExplicitPath = this._hasExplicitPath(middleware[0]);
     if (hasExplicitPath) {
       explicitPath = middleware.shift();
@@ -921,31 +924,33 @@ var RouterImplementation = class {
    * @private
    */
   _registerMiddleware(middleware, explicitPath, hasExplicitPath) {
-    const prefixHasParameters = hasPathParameters(
+    const isPrefixHasParameters = hasPathParameters(
       this.opts.prefix || "",
       this.opts
     );
     const effectiveExplicitPath = (() => {
       if (explicitPath !== void 0) return explicitPath;
-      if (prefixHasParameters) return "";
+      if (isPrefixHasParameters) return "";
       return;
     })();
-    const effectiveHasExplicitPath = hasExplicitPath || explicitPath === void 0 && prefixHasParameters;
+    const isEffectiveHasExplicitPath = hasExplicitPath || explicitPath === void 0 && isPrefixHasParameters;
     const { path: middlewarePath, pathAsRegExp } = determineMiddlewarePath(
       effectiveExplicitPath,
-      prefixHasParameters
+      isPrefixHasParameters
     );
     let finalPath = middlewarePath;
-    let usePathToRegexp = pathAsRegExp;
-    const isRootPath = effectiveHasExplicitPath && middlewarePath === "/";
-    if (effectiveHasExplicitPath && typeof middlewarePath === "string") {
+    let isUsePathToRegexp = pathAsRegExp;
+    const isRootPath = isEffectiveHasExplicitPath && middlewarePath === "/";
+    if (isEffectiveHasExplicitPath && typeof middlewarePath === "string") {
       finalPath = middlewarePath;
-      usePathToRegexp = false;
+      isUsePathToRegexp = false;
     }
+    const ignoreWildcardParameter = effectiveExplicitPath === "" && middlewarePath === "{/*rest}" ? "rest" : void 0;
     this.register(finalPath, [], middleware, {
       end: isRootPath,
-      ignoreCaptures: !effectiveHasExplicitPath && !prefixHasParameters,
-      pathAsRegExp: usePathToRegexp
+      ignoreCaptures: !isEffectiveHasExplicitPath && !isPrefixHasParameters,
+      ignoreWildcardParameter,
+      pathAsRegExp: isUsePathToRegexp
     });
   }
   /**
@@ -1397,6 +1402,7 @@ var RouterImplementation = class {
       strict: options.strict || false,
       prefix: options.prefix || "",
       ignoreCaptures: options.ignoreCaptures,
+      ignoreWildcardParameter: options.ignoreWildcardParameter,
       pathAsRegExp: options.pathAsRegExp
     });
   }
@@ -1467,8 +1473,8 @@ var RouterImplementation = class {
       if (layer.match(path)) {
         matchResult.path.push(layer);
         const isMiddleware = layer.methods.length === 0;
-        const matchesMethod = layer.methods.includes(normalizedMethod);
-        if (isMiddleware || matchesMethod) {
+        const isMatchesMethod = layer.methods.includes(normalizedMethod);
+        if (isMiddleware || isMatchesMethod) {
           matchResult.pathAndMethod.push(layer);
           if (layer.methods.length > 0) {
             matchResult.route = true;

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);
       }
     }
@@ -477,12 +480,12 @@ var Layer = class {
    * @private
    */
   _insertParamMiddleware(middlewareStack, parameterMiddleware, parameterNamesList, currentParameterPosition) {
-    let inserted = false;
+    let isInserted = false;
     for (let stackIndex = 0; stackIndex < middlewareStack.length; stackIndex++) {
       const existingMiddleware = middlewareStack[stackIndex];
       if (!existingMiddleware.param) {
         middlewareStack.splice(stackIndex, 0, parameterMiddleware);
-        inserted = true;
+        isInserted = true;
         break;
       }
       const existingParameterPosition = parameterNamesList.indexOf(
@@ -490,11 +493,11 @@ var Layer = class {
       );
       if (existingParameterPosition > currentParameterPosition) {
         middlewareStack.splice(stackIndex, 0, parameterMiddleware);
-        inserted = true;
+        isInserted = true;
         break;
       }
     }
-    if (!inserted) {
+    if (!isInserted) {
       middlewareStack.push(parameterMiddleware);
     }
   }
@@ -523,9 +526,9 @@ var Layer = class {
   _applyPrefix(prefixPath) {
     const isRootPath = this.path === "/";
     const isStrictMode = this.opts.strict === true;
-    const prefixHasParameters = prefixPath.includes(":");
-    const pathIsRawRegex = this.opts.pathAsRegExp === true && typeof this.path === "string";
-    if (prefixHasParameters && pathIsRawRegex) {
+    const isPrefixHasParameters = prefixPath.includes(":");
+    const isPathIsRawRegex = this.opts.pathAsRegExp === true && typeof this.path === "string";
+    if (isPrefixHasParameters && isPathIsRawRegex) {
       const currentPath = this.path;
       if (currentPath === String.raw`(?:\/|$)` || currentPath === String.raw`(?:\\\/|$)`) {
         this.path = "{/*rest}";
@@ -542,9 +545,9 @@ var Layer = class {
    * @private
    */
   _reconfigurePathMatching(prefixPath) {
-    const treatAsRegExp = this.opts.pathAsRegExp === true;
+    const isTreatAsRegExp = this.opts.pathAsRegExp === true;
     const prefixHasParameters = prefixPath && prefixPath.includes(":");
-    if (prefixHasParameters && treatAsRegExp) {
+    if (prefixHasParameters && isTreatAsRegExp) {
       const options = normalizeLayerOptionsToPathToRegexp(this.opts);
       const { regexp, keys } = compilePathToRegexp(
         this.path,
@@ -553,7 +556,7 @@ var Layer = class {
       this.regexp = regexp;
       this.paramNames = keys;
       this.opts.pathAsRegExp = false;
-    } else if (treatAsRegExp) {
+    } else if (isTreatAsRegExp) {
       const pathString = this.path;
       const anchoredPattern = pathString.startsWith("^") ? pathString : `^${pathString}`;
       this.regexp = this.path instanceof RegExp ? this.path : new RegExp(anchoredPattern);
@@ -741,10 +744,10 @@ var RouterImplementation = class {
     return temporaryLayer.url(...arguments_);
   }
   use(...middleware) {
-    let explicitPath;
     if (this._isPathArray(middleware[0])) {
       return this._useWithPathArray(middleware);
     }
+    let explicitPath;
     const hasExplicitPath = this._hasExplicitPath(middleware[0]);
     if (hasExplicitPath) {
       explicitPath = middleware.shift();
@@ -882,31 +885,33 @@ var RouterImplementation = class {
    * @private
    */
   _registerMiddleware(middleware, explicitPath, hasExplicitPath) {
-    const prefixHasParameters = hasPathParameters(
+    const isPrefixHasParameters = hasPathParameters(
       this.opts.prefix || "",
       this.opts
     );
     const effectiveExplicitPath = (() => {
       if (explicitPath !== void 0) return explicitPath;
-      if (prefixHasParameters) return "";
+      if (isPrefixHasParameters) return "";
       return;
     })();
-    const effectiveHasExplicitPath = hasExplicitPath || explicitPath === void 0 && prefixHasParameters;
+    const isEffectiveHasExplicitPath = hasExplicitPath || explicitPath === void 0 && isPrefixHasParameters;
     const { path: middlewarePath, pathAsRegExp } = determineMiddlewarePath(
       effectiveExplicitPath,
-      prefixHasParameters
+      isPrefixHasParameters
     );
     let finalPath = middlewarePath;
-    let usePathToRegexp = pathAsRegExp;
-    const isRootPath = effectiveHasExplicitPath && middlewarePath === "/";
-    if (effectiveHasExplicitPath && typeof middlewarePath === "string") {
+    let isUsePathToRegexp = pathAsRegExp;
+    const isRootPath = isEffectiveHasExplicitPath && middlewarePath === "/";
+    if (isEffectiveHasExplicitPath && typeof middlewarePath === "string") {
       finalPath = middlewarePath;
-      usePathToRegexp = false;
+      isUsePathToRegexp = false;
     }
+    const ignoreWildcardParameter = effectiveExplicitPath === "" && middlewarePath === "{/*rest}" ? "rest" : void 0;
     this.register(finalPath, [], middleware, {
       end: isRootPath,
-      ignoreCaptures: !effectiveHasExplicitPath && !prefixHasParameters,
-      pathAsRegExp: usePathToRegexp
+      ignoreCaptures: !isEffectiveHasExplicitPath && !isPrefixHasParameters,
+      ignoreWildcardParameter,
+      pathAsRegExp: isUsePathToRegexp
     });
   }
   /**
@@ -1358,6 +1363,7 @@ var RouterImplementation = class {
       strict: options.strict || false,
       prefix: options.prefix || "",
       ignoreCaptures: options.ignoreCaptures,
+      ignoreWildcardParameter: options.ignoreWildcardParameter,
       pathAsRegExp: options.pathAsRegExp
     });
   }
@@ -1428,8 +1434,8 @@ var RouterImplementation = class {
       if (layer.match(path)) {
         matchResult.path.push(layer);
         const isMiddleware = layer.methods.length === 0;
-        const matchesMethod = layer.methods.includes(normalizedMethod);
-        if (isMiddleware || matchesMethod) {
+        const isMatchesMethod = layer.methods.includes(normalizedMethod);
+        if (isMiddleware || isMatchesMethod) {
           matchResult.pathAndMethod.push(layer);
           if (layer.methods.length > 0) {
             matchResult.route = true;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@koa/router",
   "description": "Router middleware for Koa.",
-  "version": "15.5.0",
+  "version": "15.7.0",
   "author": "Koa.js",
   "bugs": {
     "url": "https://github.com/koajs/router/issues",
@@ -31,28 +31,28 @@
     "path-to-regexp": "^8.4.2"
   },
   "devDependencies": {
-    "@commitlint/cli": "^20.5.3",
-    "@commitlint/config-conventional": "^20.5.3",
+    "@commitlint/cli": "^21.2.0",
+    "@commitlint/config-conventional": "^21.2.0",
     "@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": "^26.1.0",
     "@types/supertest": "^7.2.0",
-    "@typescript-eslint/eslint-plugin": "^8.59.1",
-    "@typescript-eslint/parser": "^8.59.1",
+    "@typescript-eslint/eslint-plugin": "^8.62.1",
+    "@typescript-eslint/parser": "^8.62.1",
     "c8": "^11.0.0",
     "chalk": "^5.6.2",
-    "eslint": "^10.3.0",
-    "eslint-plugin-unicorn": "^64.0.0",
+    "eslint": "^10.6.0",
+    "eslint-plugin-unicorn": "^70.0.0",
     "husky": "^9.1.7",
-    "joi": "^18.1.2",
+    "joi": "^18.2.3",
     "jsonwebtoken": "^9.0.3",
-    "koa": "^3.2.0",
-    "lint-staged": "^16.4.0",
-    "np": "^11.2.0",
-    "prettier": "^3.8.3",
+    "koa": "^3.2.1",
+    "lint-staged": "^17.0.8",
+    "np": "^11.2.1",
+    "prettier": "^3.9.4",
     "rimraf": "^6.1.3",
     "supertest": "^7.2.2",
     "ts-node": "^10.9.2",