@koa/router 15.1.1 → 15.2.0

package/README.md

@@ -490,6 +490,36 @@ router.get('/files/{/*path}', (ctx) => {
 
 **Note:** Custom regex patterns in parameters (`:param(regex)`) are **no longer supported** in v14+ due to path-to-regexp v8. Use validation in handlers or middleware instead.
 
+**Helper for parameter validation (v14+)** <small>(Added on v15.2)</small>
+
+If you want to keep regex-style validation, register a param middleware instead:
+
+```javascript
+import Router, { createParameterValidationMiddleware } from '@koa/router';
+
+const uuid =
+  /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+
+const validateId = createParameterValidationMiddleware('id', uuid);
+
+router.param('id', validateId).get('/role/:id', middleware);
+```
+
+Or validate inline on a specific route:
+
+```javascript
+import Router, { createParameterValidationMiddleware } from '@koa/router';
+
+const uuid =
+  /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+
+router.get(
+  '/role/:id',
+  createParameterValidationMiddleware('id', uuid),
+  middleware
+);
+```
+
 ### router.routes()
 
 Returns router middleware which dispatches matched routes.

package/dist/index.d.mts

@@ -172,6 +172,7 @@ declare class Layer<StateT = DefaultState, ContextT = DefaultContext, BodyT = un
     private _reconfigurePathMatching;
 }
 
+type RouterInstance<StateT = koa.DefaultState, ContextT = koa.DefaultContext> = RouterImplementation<StateT, ContextT>;
 /**
  * Middleware with router property
  */
@@ -181,7 +182,7 @@ type RouterComposedMiddleware<StateT = koa.DefaultState, ContextT = koa.DefaultC
 /**
  * @module koa-router
  */
-declare class Router<StateT = koa.DefaultState, ContextT = koa.DefaultContext> {
+declare class RouterImplementation<StateT = koa.DefaultState, ContextT = koa.DefaultContext> {
     opts: RouterOptions;
     methods: string[];
     exclusive: boolean;
@@ -642,7 +643,8 @@ interface RouterConstructor {
     url(path: string, ...parameters: unknown[]): string;
     readonly prototype: Router;
 }
-declare const RouterExport: RouterConstructor;
+type Router<StateT = koa.DefaultState, ContextT = koa.DefaultContext> = RouterInstance<StateT, ContextT>;
+declare const Router: RouterConstructor;
 
 /**
  * Type definitions for @koa/router
@@ -738,7 +740,7 @@ type RouterParameterContext<StateT = DefaultState, ContextT = DefaultContext> =
     /**
      * Router instance
      */
-    router: Router<StateT, ContextT>;
+    router: RouterInstance<StateT, ContextT>;
     /**
      * Matched route path (internal)
      */
@@ -831,13 +833,56 @@ type RouterOptionsWithMethods<M extends string = string> = Omit<RouterOptions, '
  * Type for a dynamic HTTP method function on Router
  */
 type RouterMethodFunction<StateT = DefaultState, ContextT = DefaultContext> = {
-    <T = {}, U = {}, B = unknown>(name: string, path: string | RegExp, ...middleware: Array<RouterMiddleware<StateT & T, ContextT & U, B>>): Router<StateT, ContextT>;
-    <T = {}, U = {}, B = unknown>(path: string | RegExp | Array<string | RegExp>, ...middleware: Array<RouterMiddleware<StateT & T, ContextT & U, B>>): Router<StateT, ContextT>;
+    <T = {}, U = {}, B = unknown>(name: string, path: string | RegExp, ...middleware: Array<RouterMiddleware<StateT & T, ContextT & U, B>>): RouterInstance<StateT, ContextT>;
+    <T = {}, U = {}, B = unknown>(path: string | RegExp | Array<string | RegExp>, ...middleware: Array<RouterMiddleware<StateT & T, ContextT & U, B>>): RouterInstance<StateT, ContextT>;
 };
 /**
  * Router with additional HTTP methods based on the methods option.
  * Use createRouter() factory function for automatic type inference.
  */
-type RouterWithMethods<M extends string, StateT = DefaultState, ContextT = DefaultContext> = Router<StateT, ContextT> & Record<Lowercase<M>, RouterMethodFunction<StateT, ContextT>>;
+type RouterWithMethods<M extends string, StateT = DefaultState, ContextT = DefaultContext> = RouterInstance<StateT, ContextT> & Record<Lowercase<M>, RouterMethodFunction<StateT, ContextT>>;
 
-export { type AllowedMethodsOptions, type HttpMethod, Layer, type LayerOptions, type MatchResult, RouterExport as Router, type RouterContext, Router as RouterInstance, type RouterMethodFunction, type RouterMiddleware, type RouterOptions, type RouterOptionsWithMethods, type RouterParameterMiddleware, type RouterWithMethods, type UrlOptions, RouterExport as default };
+/**
+ * Parameter validation helpers.
+ *
+ * These utilities exist to help migrate legacy `:param(regex)` usage from older
+ * router/path-to-regexp versions to v14+ (path-to-regexp v8), where inline
+ * parameter regexes are no longer supported in route strings.
+ */
+
+/**
+ * Options for createParameterValidationMiddleware helper
+ */
+type ParameterValidationOptions = {
+    /**
+     * HTTP status to use when the value does not match
+     * @default 400
+     */
+    status?: number;
+    /**
+     * Error message to use when the value does not match
+     * @default `Invalid value for parameter "<parameterName>"`
+     */
+    message?: string;
+    /**
+     * Whether the error message should be exposed to the client.
+     * Passed through to HttpError#expose.
+     */
+    expose?: boolean;
+    /**
+     * Optional custom error factory. If provided, it is used
+     * instead of the default HttpError.
+     */
+    createError?: (parameterName: string, value: string) => Error;
+};
+/**
+ * Convenience helper to recreate legacy `:param(regex)` validation.
+ *
+ * @example
+ * const validateUuid = createParameterValidationMiddleware('id', uuidRegex);
+ * router.param('id', validateUuid).get('/role/:id', handler);
+ * router.get('/role/:id', createParameterValidationMiddleware('id', uuidRegex)
+ */
+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 };

package/dist/index.d.ts

@@ -172,6 +172,7 @@ declare class Layer<StateT = DefaultState, ContextT = DefaultContext, BodyT = un
     private _reconfigurePathMatching;
 }
 
+type RouterInstance<StateT = koa.DefaultState, ContextT = koa.DefaultContext> = RouterImplementation<StateT, ContextT>;
 /**
  * Middleware with router property
  */
@@ -181,7 +182,7 @@ type RouterComposedMiddleware<StateT = koa.DefaultState, ContextT = koa.DefaultC
 /**
  * @module koa-router
  */
-declare class Router<StateT = koa.DefaultState, ContextT = koa.DefaultContext> {
+declare class RouterImplementation<StateT = koa.DefaultState, ContextT = koa.DefaultContext> {
     opts: RouterOptions;
     methods: string[];
     exclusive: boolean;
@@ -642,7 +643,8 @@ interface RouterConstructor {
     url(path: string, ...parameters: unknown[]): string;
     readonly prototype: Router;
 }
-declare const RouterExport: RouterConstructor;
+type Router<StateT = koa.DefaultState, ContextT = koa.DefaultContext> = RouterInstance<StateT, ContextT>;
+declare const Router: RouterConstructor;
 
 /**
  * Type definitions for @koa/router
@@ -738,7 +740,7 @@ type RouterParameterContext<StateT = DefaultState, ContextT = DefaultContext> =
     /**
      * Router instance
      */
-    router: Router<StateT, ContextT>;
+    router: RouterInstance<StateT, ContextT>;
     /**
      * Matched route path (internal)
      */
@@ -831,13 +833,56 @@ type RouterOptionsWithMethods<M extends string = string> = Omit<RouterOptions, '
  * Type for a dynamic HTTP method function on Router
  */
 type RouterMethodFunction<StateT = DefaultState, ContextT = DefaultContext> = {
-    <T = {}, U = {}, B = unknown>(name: string, path: string | RegExp, ...middleware: Array<RouterMiddleware<StateT & T, ContextT & U, B>>): Router<StateT, ContextT>;
-    <T = {}, U = {}, B = unknown>(path: string | RegExp | Array<string | RegExp>, ...middleware: Array<RouterMiddleware<StateT & T, ContextT & U, B>>): Router<StateT, ContextT>;
+    <T = {}, U = {}, B = unknown>(name: string, path: string | RegExp, ...middleware: Array<RouterMiddleware<StateT & T, ContextT & U, B>>): RouterInstance<StateT, ContextT>;
+    <T = {}, U = {}, B = unknown>(path: string | RegExp | Array<string | RegExp>, ...middleware: Array<RouterMiddleware<StateT & T, ContextT & U, B>>): RouterInstance<StateT, ContextT>;
 };
 /**
  * Router with additional HTTP methods based on the methods option.
  * Use createRouter() factory function for automatic type inference.
  */
-type RouterWithMethods<M extends string, StateT = DefaultState, ContextT = DefaultContext> = Router<StateT, ContextT> & Record<Lowercase<M>, RouterMethodFunction<StateT, ContextT>>;
+type RouterWithMethods<M extends string, StateT = DefaultState, ContextT = DefaultContext> = RouterInstance<StateT, ContextT> & Record<Lowercase<M>, RouterMethodFunction<StateT, ContextT>>;
 
-export { type AllowedMethodsOptions, type HttpMethod, Layer, type LayerOptions, type MatchResult, RouterExport as Router, type RouterContext, Router as RouterInstance, type RouterMethodFunction, type RouterMiddleware, type RouterOptions, type RouterOptionsWithMethods, type RouterParameterMiddleware, type RouterWithMethods, type UrlOptions, RouterExport as default };
+/**
+ * Parameter validation helpers.
+ *
+ * These utilities exist to help migrate legacy `:param(regex)` usage from older
+ * router/path-to-regexp versions to v14+ (path-to-regexp v8), where inline
+ * parameter regexes are no longer supported in route strings.
+ */
+
+/**
+ * Options for createParameterValidationMiddleware helper
+ */
+type ParameterValidationOptions = {
+    /**
+     * HTTP status to use when the value does not match
+     * @default 400
+     */
+    status?: number;
+    /**
+     * Error message to use when the value does not match
+     * @default `Invalid value for parameter "<parameterName>"`
+     */
+    message?: string;
+    /**
+     * Whether the error message should be exposed to the client.
+     * Passed through to HttpError#expose.
+     */
+    expose?: boolean;
+    /**
+     * Optional custom error factory. If provided, it is used
+     * instead of the default HttpError.
+     */
+    createError?: (parameterName: string, value: string) => Error;
+};
+/**
+ * Convenience helper to recreate legacy `:param(regex)` validation.
+ *
+ * @example
+ * const validateUuid = createParameterValidationMiddleware('id', uuidRegex);
+ * router.param('id', validateUuid).get('/role/:id', handler);
+ * router.get('/role/:id', createParameterValidationMiddleware('id', uuidRegex)
+ */
+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 };

package/dist/index.js

@@ -30,14 +30,64 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  Router: () => RouterExport,
+  Router: () => Router,
+  createParameterValidationMiddleware: () => createParameterValidationMiddleware,
   default: () => router_default
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/utils/parameter-match.ts
+var import_http_errors = __toESM(require("http-errors"));
+function createParameterValidationMiddleware(parameterName, pattern, options = {}) {
+  if (!(pattern instanceof RegExp)) {
+    throw new TypeError("pattern must be a RegExp instance");
+  }
+  const matcher = new RegExp(pattern.source, pattern.flags);
+  const createDefaultHttpError = (message) => {
+    const httpError = (0, import_http_errors.default)(options.status ?? 400, message);
+    if (options.expose !== void 0) {
+      httpError.expose = options.expose;
+    }
+    return httpError;
+  };
+  const validateValue = (value) => {
+    if (matcher.global || matcher.sticky) {
+      matcher.lastIndex = 0;
+    }
+    if (matcher.test(value)) {
+      return;
+    }
+    if (options.createError) {
+      throw options.createError(parameterName, value);
+    }
+    throw createDefaultHttpError(
+      options.message ?? `Invalid value for parameter "${parameterName}": "${value}"`
+    );
+  };
+  const middleware = async (argument1, argument2, argument3) => {
+    if (typeof argument1 !== "string") {
+      const context = argument1;
+      const next2 = argument2;
+      const parameterValue = context.params && parameterName in context.params ? context.params[parameterName] : void 0;
+      if (typeof parameterValue !== "string") {
+        throw createDefaultHttpError(
+          options.message ?? `Missing required parameter "${parameterName}" in route params`
+        );
+      }
+      validateValue(parameterValue);
+      return next2();
+    }
+    const value = argument1;
+    const next = argument3;
+    validateValue(value);
+    return next();
+  };
+  return middleware;
+}
+
 // src/router.ts
 var import_koa_compose = __toESM(require("koa-compose"));
-var import_http_errors = __toESM(require("http-errors"));
+var import_http_errors2 = __toESM(require("http-errors"));
 
 // src/layer.ts
 var import_node_url = require("url");
@@ -594,7 +644,7 @@ var debug = (0, import_debug.default)("koa-router");
 
 // src/router.ts
 var httpMethods = getAllHttpMethods();
-var Router = class {
+var RouterImplementation = class {
   opts;
   methods;
   exclusive;
@@ -1058,7 +1108,7 @@ var Router = class {
    */
   _handleNotImplemented(context, allowedMethodsList, options) {
     if (options.throw) {
-      const error = typeof options.notImplemented === "function" ? options.notImplemented() : new import_http_errors.default.NotImplemented();
+      const error = typeof options.notImplemented === "function" ? options.notImplemented() : new import_http_errors2.default.NotImplemented();
       throw error;
     }
     context.status = 501;
@@ -1079,7 +1129,7 @@ var Router = class {
    */
   _handleMethodNotAllowed(context, allowedMethodsList, options) {
     if (options.throw) {
-      const error = typeof options.methodNotAllowed === "function" ? options.methodNotAllowed() : new import_http_errors.default.MethodNotAllowed();
+      const error = typeof options.methodNotAllowed === "function" ? options.methodNotAllowed() : new import_http_errors2.default.MethodNotAllowed();
       throw error;
     }
     context.status = 405;
@@ -1419,12 +1469,12 @@ var Router = class {
     return this._registerMethod("options", ...arguments_);
   }
 };
-var RouterExport = Router;
-var router_default = RouterExport;
+var Router = RouterImplementation;
+var router_default = Router;
 for (const httpMethod of httpMethods) {
-  const isAlreadyDefined = COMMON_HTTP_METHODS.includes(httpMethod) || httpMethod in Router.prototype;
+  const isAlreadyDefined = COMMON_HTTP_METHODS.includes(httpMethod) || httpMethod in RouterImplementation.prototype;
   if (!isAlreadyDefined) {
-    Object.defineProperty(Router.prototype, httpMethod, {
+    Object.defineProperty(RouterImplementation.prototype, httpMethod, {
       value: function(...arguments_) {
         return this._registerMethod(httpMethod, ...arguments_);
       },
@@ -1436,7 +1486,8 @@ for (const httpMethod of httpMethods) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  Router
+  Router,
+  createParameterValidationMiddleware
 });
 if (module.exports.default) {
   Object.assign(module.exports.default, module.exports);

package/dist/index.mjs

@@ -1,3 +1,52 @@
+// src/utils/parameter-match.ts
+import createHttpError from "http-errors";
+function createParameterValidationMiddleware(parameterName, pattern, options = {}) {
+  if (!(pattern instanceof RegExp)) {
+    throw new TypeError("pattern must be a RegExp instance");
+  }
+  const matcher = new RegExp(pattern.source, pattern.flags);
+  const createDefaultHttpError = (message) => {
+    const httpError = createHttpError(options.status ?? 400, message);
+    if (options.expose !== void 0) {
+      httpError.expose = options.expose;
+    }
+    return httpError;
+  };
+  const validateValue = (value) => {
+    if (matcher.global || matcher.sticky) {
+      matcher.lastIndex = 0;
+    }
+    if (matcher.test(value)) {
+      return;
+    }
+    if (options.createError) {
+      throw options.createError(parameterName, value);
+    }
+    throw createDefaultHttpError(
+      options.message ?? `Invalid value for parameter "${parameterName}": "${value}"`
+    );
+  };
+  const middleware = async (argument1, argument2, argument3) => {
+    if (typeof argument1 !== "string") {
+      const context = argument1;
+      const next2 = argument2;
+      const parameterValue = context.params && parameterName in context.params ? context.params[parameterName] : void 0;
+      if (typeof parameterValue !== "string") {
+        throw createDefaultHttpError(
+          options.message ?? `Missing required parameter "${parameterName}" in route params`
+        );
+      }
+      validateValue(parameterValue);
+      return next2();
+    }
+    const value = argument1;
+    const next = argument3;
+    validateValue(value);
+    return next();
+  };
+  return middleware;
+}
+
 // src/router.ts
 import compose from "koa-compose";
 import HttpError from "http-errors";
@@ -557,7 +606,7 @@ var debug = debugModule("koa-router");
 
 // src/router.ts
 var httpMethods = getAllHttpMethods();
-var Router = class {
+var RouterImplementation = class {
   opts;
   methods;
   exclusive;
@@ -1382,12 +1431,12 @@ var Router = class {
     return this._registerMethod("options", ...arguments_);
   }
 };
-var RouterExport = Router;
-var router_default = RouterExport;
+var Router = RouterImplementation;
+var router_default = Router;
 for (const httpMethod of httpMethods) {
-  const isAlreadyDefined = COMMON_HTTP_METHODS.includes(httpMethod) || httpMethod in Router.prototype;
+  const isAlreadyDefined = COMMON_HTTP_METHODS.includes(httpMethod) || httpMethod in RouterImplementation.prototype;
   if (!isAlreadyDefined) {
-    Object.defineProperty(Router.prototype, httpMethod, {
+    Object.defineProperty(RouterImplementation.prototype, httpMethod, {
       value: function(...arguments_) {
         return this._registerMethod(httpMethod, ...arguments_);
       },
@@ -1398,6 +1447,7 @@ for (const httpMethod of httpMethods) {
   }
 }
 export {
-  RouterExport as Router,
+  Router,
+  createParameterValidationMiddleware,
   router_default as default
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@koa/router",
   "description": "Router middleware for koa. Maintained by Forward Email and Lad.",
-  "version": "15.1.1",
+  "version": "15.2.0",
   "author": "Alex Mingoia <talk@alexmingoia.com>",
   "bugs": {
     "url": "https://github.com/koajs/router/issues",
@@ -35,18 +35,18 @@
     "path-to-regexp": "^8.3.0"
   },
   "devDependencies": {
-    "@commitlint/cli": "^20.2.0",
-    "@commitlint/config-conventional": "^20.2.0",
+    "@commitlint/cli": "^20.3.0",
+    "@commitlint/config-conventional": "^20.3.0",
     "@koa/bodyparser": "^6.0.0",
     "@types/debug": "^4.1.12",
-    "@types/jsonwebtoken": "^9.0.7",
+    "@types/jsonwebtoken": "^9.0.10",
     "@types/koa": "^3.0.1",
     "@types/node": "^25.0.3",
     "@types/supertest": "^6.0.3",
-    "@typescript-eslint/eslint-plugin": "^8.50.0",
-    "@typescript-eslint/parser": "^8.50.0",
+    "@typescript-eslint/eslint-plugin": "^8.51.0",
+    "@typescript-eslint/parser": "^8.51.0",
     "c8": "^10.1.3",
-    "chalk": "^5.4.1",
+    "chalk": "^5.6.2",
     "eslint": "^9.39.2",
     "eslint-plugin-unicorn": "^62.0.0",
     "husky": "^9.1.7",
@@ -108,9 +108,9 @@
     "lint": "npm run lint:ts",
     "test:core": "TS_NODE_PROJECT=tsconfig.ts-node.json node --require ts-node/register --test test/*.test.ts test/**/*.test.ts",
     "test:recipes": "TS_NODE_PROJECT=tsconfig.recipes.json node --require ts-node/register --test recipes/**/*.test.ts",
-    "pretest:all": "npm run lint",
+    "pretest:all": "npm run lint && npm run build",
     "test:all": "TS_NODE_PROJECT=tsconfig.ts-node.json node --require ts-node/register --test test/*.test.ts test/**/*.test.ts recipes/**/*.test.ts",
-    "test:coverage": "c8 npm run test:all",
+    "test:coverage": "c8 --all --exclude eslint.config.js --exclude tsup.config.ts --exclude src/types.ts --exclude \"bench/**\" --exclude \"dist/**\" --exclude \"recipes/**\" --exclude \"test/**\" --exclude-after-remap npm run test:all",
     "ts:check": "tsc --noEmit --project tsconfig.typecheck.json",
     "ts:check:test": "tsc --noEmit --project tsconfig.test.json",
     "prebuild": "rimraf dist",