feat: add new utility that help to valdiate route params and/or migrate from previous versions to v14+

Author: 3imed-jaberi

FULL_MIGRATION_TO_V15+.md

@@ -134,6 +134,35 @@ The new version uses **`path-to-regexp` v8** via a wrapper (`src/utils/path-to-r
 
     > **Note:** Custom regex patterns in parameters (`:param(regex)`) are **no longer supported** in v15+ due to path-to-regexp v8. Use validation in handlers or middleware instead.
 
+  - **Helper available (since v15.2):** Use `createParameterValidationMiddleware(name, regexp)` to keep regex validation while moving it into middleware. The same helper can also be used inline on specific routes.
+
+    ```js
+    import Router, { createParameterValidationMiddleware } from '@koa/router';
+
+    const validateUserId = createParameterValidationMiddleware(
+      'id',
+      /^[0-9]+$/
+    );
+
+    router.param('id', validateUserId).get('/user/:id', (ctx) => {
+      ctx.body = { id: Number(ctx.params.id) };
+    });
+    ```
+
+    Inline per-route example (same helper):
+
+    ```js
+    import Router, { createParameterValidationMiddleware } from '@koa/router';
+
+    router.get(
+      '/user/:id',
+      createParameterValidationMiddleware('id', /^[0-9]+$/),
+      (ctx) => {
+        ctx.body = { id: Number(ctx.params.id) };
+      }
+    );
+    ```
+
 - **Migration strategy:**
   - **Before (v10):**
 

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.json

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

recipes/README.md

@@ -12,6 +12,7 @@ Common patterns and recipes for building real-world applications with @koa/route
 | **[Authentication & Authorization](./authentication-authorization/)** | JWT-based authentication with role-based access control                           |
 | **[Request Validation](./request-validation/)**                       | Validate request data with Joi middleware                                         |
 | **[Parameter Validation](./parameter-validation/)**                   | Validate and transform URL parameters using `router.param()`                      |
+| **[Regex Parameter Validation](./regex-parameter-validation/)**       | Validate URL parameters with regex (replacement for `:param(regex)` in v14+)      |
 | **[API Versioning](./api-versioning/)**                               | Implement API versioning with multiple routers                                    |
 | **[Error Handling](./error-handling/)**                               | Centralized error handling with custom error classes                              |
 | **[Pagination](./pagination/)**                                       | Pagination middleware with configurable limits and metadata                       |

recipes/regex-parameter-validation/regex-parameter-validation.test.ts

@@ -0,0 +1,88 @@
+/**
+ * Tests for Regex Parameter Validation Recipe
+ */
+
+import { describe, it } from 'node:test';
+import * as assert from 'node:assert';
+import * as http from 'node:http';
+import request from 'supertest';
+import Koa from 'koa';
+
+import Router from '../router-module-loader';
+import { createParameterValidationMiddleware } from '../router-module-loader';
+
+describe('Regex Parameter Validation', () => {
+  it('should validate UUID via router.param()', async () => {
+    const app = new Koa();
+    const router = new Router();
+
+    const uuidRegex =
+      /^[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.param(
+      'id',
+      createParameterValidationMiddleware('id', uuidRegex, {
+        status: 400,
+        message: 'Invalid id (expected UUID)'
+      })
+    );
+
+    router.get('/role/:id', (ctx) => {
+      ctx.body = { id: ctx.params.id, ok: true };
+    });
+
+    app.use(router.routes());
+
+    const validUUID = '123e4567-e89b-12d3-a456-426614174000';
+    const res1 = await request(http.createServer(app.callback()))
+      .get(`/role/${validUUID}`)
+      .expect(200);
+
+    assert.strictEqual(res1.body.ok, true);
+    assert.strictEqual(res1.body.id, validUUID);
+
+    await request(http.createServer(app.callback()))
+      .get('/role/invalid-id')
+      .expect(400);
+  });
+
+  it('should validate UUID inline on a specific route', async () => {
+    const app = new Koa();
+    const router = new Router();
+
+    const uuidRegex =
+      /^[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(
+      '/roles/:id',
+      createParameterValidationMiddleware('id', uuidRegex, {
+        status: 400,
+        message: 'Invalid id (expected UUID)'
+      }),
+      (ctx) => {
+        ctx.body = { id: ctx.params.id, ok: true };
+      }
+    );
+
+    // A different route with same param name, but without validation
+    router.get('/roles-unvalidated/:id', (ctx) => {
+      ctx.body = { id: ctx.params.id, ok: true };
+    });
+
+    app.use(router.routes());
+
+    const validUUID = '123e4567-e89b-12d3-a456-426614174000';
+    await request(http.createServer(app.callback()))
+      .get(`/roles/${validUUID}`)
+      .expect(200);
+
+    await request(http.createServer(app.callback()))
+      .get('/roles/invalid-id')
+      .expect(400);
+
+    // This should NOT be validated (inline middleware applies only to /roles/:id)
+    await request(http.createServer(app.callback()))
+      .get('/roles-unvalidated/invalid-id')
+      .expect(200);
+  });
+});

recipes/regex-parameter-validation/regex-parameter-validation.ts

@@ -0,0 +1,50 @@
+/**
+ * Regex Parameter Validation Recipe (v14+)
+ *
+ * Demonstrates how to validate route parameters with regex in v14+,
+ * where `:param(regex)` is no longer supported in the path string.
+ *
+ * Shows both styles:
+ * - router.param('id', createParameterValidationMiddleware(...))
+ * - router.get('/role/:id', createParameterValidationMiddleware(...), handler)
+ */
+
+import Router, {
+  createParameterValidationMiddleware
+} from '../router-module-loader';
+
+const uuidRegex =
+  /^[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 router = new Router();
+
+// ===========================================
+// Style A: router.param() (applies to all routes using :id)
+// ===========================================
+router.param(
+  'id',
+  createParameterValidationMiddleware('id', uuidRegex, {
+    status: 400,
+    message: 'Invalid id (expected UUID)'
+  })
+);
+
+router.get('/role/:id', (ctx) => {
+  ctx.body = { id: ctx.params.id, source: 'router.param' };
+});
+
+// ===========================================
+// Style B: Inline per-route middleware (applies to this route only)
+// ===========================================
+router.get(
+  '/roles/:id',
+  createParameterValidationMiddleware('id', uuidRegex, {
+    status: 400,
+    message: 'Invalid id (expected UUID)'
+  }),
+  (ctx) => {
+    ctx.body = { id: ctx.params.id, source: 'inline' };
+  }
+);
+
+export { router };

recipes/router-module-loader.ts

@@ -9,5 +9,9 @@
  * - For dist build: '../dist/index'
  * - For published package: '@koa/router'
  */
-export { default, default as Router } from '../src/index';
+export {
+  default,
+  default as Router,
+  createParameterValidationMiddleware
+} from '../src/index';
 export type * from '../src/index';

src/index.ts

@@ -20,4 +20,9 @@ export type {
   RouterWithMethods
 } from './types';
 
+export {
+  createParameterValidationMiddleware,
+  type ParameterValidationOptions
+} from './utils/parameter-match';
+
 export { default, Router, type RouterInstance } from './router';

src/utils/parameter-match.ts

@@ -0,0 +1,135 @@
+/**
+ * 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.
+ */
+
+import createHttpError from 'http-errors';
+
+import type {
+  RouterContext,
+  RouterMiddleware,
+  RouterParameterMiddleware
+} from '../types';
+
+/**
+ * Options for createParameterValidationMiddleware helper
+ */
+export 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)
+ */
+export function createParameterValidationMiddleware(
+  parameterName: string,
+  pattern: RegExp,
+  options: ParameterValidationOptions = {}
+): RouterMiddleware<any, any, any> & RouterParameterMiddleware<any, any, any> {
+  if (!(pattern instanceof RegExp)) {
+    throw new TypeError('pattern must be a RegExp instance');
+  }
+
+  // clone the RegExp once so we do not mutate the caller's instance
+  const matcher = new RegExp(pattern.source, pattern.flags);
+
+  const createDefaultHttpError = (message: string) => {
+    const httpError = createHttpError(options.status ?? 400, message);
+    if (options.expose !== undefined) {
+      httpError.expose = options.expose;
+    }
+
+    return httpError;
+  };
+
+  const validateValue = (value: string) => {
+    // ensure deterministic behavior even when /g or /y flags are present
+    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: RouterMiddleware<any, any, any> &
+    RouterParameterMiddleware<any, any, any> = async (
+    argument1: unknown,
+    argument2: unknown,
+    argument3?: unknown
+  ) => {
+    // called as a normal route middleware: (ctx, next)
+    if (typeof argument1 !== 'string') {
+      const context = argument1 as RouterContext<any, any, any> & {
+        params?: Record<string, string>;
+      };
+      const next = argument2 as Parameters<RouterMiddleware<any, any, any>>[1];
+
+      const parameterValue =
+        context.params && parameterName in context.params
+          ? context.params[parameterName]
+          : undefined;
+
+      if (typeof parameterValue !== 'string') {
+        throw createDefaultHttpError(
+          options.message ??
+            `Missing required parameter "${parameterName}" in route params`
+        );
+      }
+
+      validateValue(parameterValue);
+      return next();
+    }
+
+    // called as router.param middleware: (value, ctx, next)
+    const value = argument1 as string;
+    // // keep for compatibility (router.param passes ctx as second arg)
+    // void argument2;
+    const next = argument3 as () => Promise<unknown>;
+
+    validateValue(value);
+    return next();
+  };
+
+  return middleware;
+}