@koa/router 15.1.2 → 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

@@ -842,4 +842,47 @@ type RouterMethodFunction<StateT = DefaultState, ContextT = DefaultContext> = {
  */
 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, Router, type RouterContext, type RouterInstance, type RouterMethodFunction, type RouterMiddleware, type RouterOptions, type RouterOptionsWithMethods, type RouterParameterMiddleware, type RouterWithMethods, type UrlOptions, Router 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

@@ -842,4 +842,47 @@ type RouterMethodFunction<StateT = DefaultState, ContextT = DefaultContext> = {
  */
 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, Router, type RouterContext, type RouterInstance, type RouterMethodFunction, type RouterMiddleware, type RouterOptions, type RouterOptionsWithMethods, type RouterParameterMiddleware, type RouterWithMethods, type UrlOptions, Router 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

@@ -31,13 +31,63 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   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");
@@ -1058,7 +1108,7 @@ var RouterImplementation = 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 RouterImplementation = 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;
@@ -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";
@@ -1399,5 +1448,6 @@ for (const httpMethod of httpMethods) {
 }
 export {
   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.2",
+  "version": "15.2.0",
   "author": "Alex Mingoia <talk@alexmingoia.com>",
   "bugs": {
     "url": "https://github.com/koajs/router/issues",
@@ -110,7 +110,7 @@
     "test:recipes": "TS_NODE_PROJECT=tsconfig.recipes.json node --require ts-node/register --test recipes/**/*.test.ts",
     "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",