🤖 Merge PR DefinitelyTyped#74161 [express-serve-static-core] Fix req.params type by @krzysdz

krzysdz · web-flow · commit 6c487a4d2ecc · 2026-01-10T01:05:51.000-08:00
Co-authored-by: krzysdz &lt;krzysdz@users.noreply.github.com&gt;
diff --git a/types/express-serve-static-core/express-serve-static-core-tests.ts b/types/express-serve-static-core/express-serve-static-core-tests.ts
@@ -45,16 +45,16 @@ app.route("/:foo").get(req => {
     req.is(1);
 });
 
-// Params can used as an array
-app.get<express.ParamsArray>("/*", req => {
-    req.params[0]; // $ExpectType string
-    req.params.length; // $ExpectType number
+// Wildcard parameters return string arrays
+app.get("/*foo", req => {
+    req.params.foo; // $ExpectType string[]
+    req.params.foo.length; // $ExpectType number
 });
 
-// Params can used as an array - under route
-app.route("/*").get<express.ParamsArray>(req => {
-    req.params[0]; // $ExpectType string
-    req.params.length; // $ExpectType number
+// Wildcard parameters return string arrays - under route
+app.route("/*foo").get(req => {
+    req.params.foo; // $ExpectType string[]
+    req.params.foo.length; // $ExpectType number
 });
 
 // Params can be a custom type
@@ -74,10 +74,16 @@ app.route("/:foo/:bar").get<{ foo: string; bar: number }>(req => {
     req.params.baz;
 });
 
-// Optional params
-app.get("/:foo/:bar?", req => {
+// Regular expressions have parameters that always are strings, never arrays of strings
+app.get(/^\/(.*?)\|(?<b>\d+)/, req => {
+    req.params[0]; // $ExpectType string
+    req.params.foo; // $ExpectType string
+});
+
+// Regular expressions have parameters that always are strings, never arrays of strings - under route
+app.route(/^\/(.*?)\|(?<b>\d+)/).get(req => {
+    req.params[0]; // $ExpectType string
     req.params.foo; // $ExpectType string
-    req.params.bar; // $ExpectType string | undefined
 });
 
 // Express 5.0: Optional params
@@ -107,14 +113,6 @@ app.get("/:foo/:bar-:baz/:qux", req => {
     req.params.quxx;
 });
 
-// regex parameters - not supported
-app.get("/:foo/:bar(\\d:+)/:baz", req => {
-    req.params.foo; // $ExpectType string
-    req.params.bar; // $ExpectType string
-    req.params.qux; // $ExpectType string
-    req.params.quxx; // $ExpectType string
-});
-
 // long path parameters - https://github.com/DefinitelyTyped/DefinitelyTyped/pull/53513#issuecomment-870550063
 app.get("/website-api/jobalarm/:jobalarmId/:subscriptionId/search", req => {
     req.params.jobalarmId; // $ExpectType string
diff --git a/types/express-serve-static-core/index.d.ts b/types/express-serve-static-core/index.d.ts
@@ -42,10 +42,13 @@ export interface Dictionary<T> {
 }
 
 export interface ParamsDictionary {
-    [key: string]: string;
+    [key: string]: string | string[];
+    [key: number]: string;
 }
-export type ParamsArray = string[];
-export type Params = ParamsDictionary | ParamsArray;
+export interface ParamsFlatDictionary {
+    [key: string | number]: string;
+}
+export type Params = ParamsDictionary | ParamsFlatDictionary;
 
 export interface Locals extends Express.Locals {}
 
@@ -96,20 +99,26 @@ type GetRouteParameter<S extends string> = RemoveTail<
     `.${string}`
 >;
 
-// prettier-ignore
-export type RouteParameters<Route extends string> = Route extends `${infer Required}{${infer Optional}}${infer Next}`
-    ? ParseRouteParameters<Required> & Partial<ParseRouteParameters<Optional>> & RouteParameters<Next>
-    : ParseRouteParameters<Route>;
+// dprint-ignore
+export type RouteParameters<Route extends string | RegExp> = Route extends string
+    ? Route extends `${infer Required}{${infer Optional}}${infer Next}`
+        ? ParseRouteParameters<Required> & Partial<ParseRouteParameters<Optional>> & RouteParameters<Next>
+        : ParseRouteParameters<Route>
+    : ParamsFlatDictionary;
 
 type ParseRouteParameters<Route extends string> = string extends Route ? ParamsDictionary
-    : Route extends `${string}(${string}` ? ParamsDictionary // TODO: handling for regex parameters
     : Route extends `${string}:${infer Rest}` ?
             & (
                 GetRouteParameter<Rest> extends never ? ParamsDictionary
-                    : GetRouteParameter<Rest> extends `${infer ParamName}?` ? { [P in ParamName]?: string } // TODO: Remove old `?` handling when Express 5 is promoted to "latest"
                     : { [P in GetRouteParameter<Rest>]: string }
             )
             & (Rest extends `${GetRouteParameter<Rest>}${infer Next}` ? RouteParameters<Next> : unknown)
+    : Route extends `${string}*${infer Rest}` ?
+            & (
+                GetRouteParameter<Rest> extends never ? ParamsDictionary
+                    : { [P in GetRouteParameter<Rest>]: string[] }
+            )
+            & (Rest extends `${GetRouteParameter<Rest>}${infer Next}` ? RouteParameters<Next> : unknown)
     : {};
 
 /* eslint-disable @definitelytyped/no-unnecessary-generics */
@@ -118,7 +127,7 @@ export interface IRouterMatcher<
     Method extends "all" | "get" | "post" | "put" | "delete" | "patch" | "options" | "head" = any,
 > {
     <
-        Route extends string,
+        Route extends string | RegExp,
         P = RouteParameters<Route>,
         ResBody = any,
         ReqBody = any,
@@ -131,7 +140,7 @@ export interface IRouterMatcher<
         ...handlers: Array<RequestHandler<P, ResBody, ReqBody, ReqQuery, LocalsObj>>
     ): T;
     <
-        Path extends string,
+        Path extends string | RegExp,
         P = RouteParameters<Path>,
         ResBody = any,
         ReqBody = any,
@@ -168,7 +177,7 @@ export interface IRouterMatcher<
     (path: PathParams, subApplication: Application): T;
 }
 
-export interface IRouterHandler<T, Route extends string = string> {
+export interface IRouterHandler<T, Route extends string | RegExp = string> {
     (...handlers: Array<RequestHandler<RouteParameters<Route>>>): T;
     (...handlers: Array<RequestHandlerParams<RouteParameters<Route>>>): T;
     <
@@ -284,7 +293,7 @@ export interface IRouter extends RequestHandler {
 
     use: IRouterHandler<this> & IRouterMatcher<this>;
 
-    route<T extends string>(prefix: T): IRoute<T>;
+    route<T extends string | RegExp>(prefix: T): IRoute<T>;
     route(prefix: PathParams): IRoute;
     /**
      * Stack of configured routes
@@ -303,7 +312,7 @@ export interface ILayer {
     handle: (req: Request, res: Response, next: NextFunction) => any;
 }
 
-export interface IRoute<Route extends string = string> {
+export interface IRoute<Route extends string | RegExp = string> {
     path: string;
     stack: ILayer[];
     all: IRouterHandler<this, Route>;
@@ -381,16 +390,14 @@ export type Errback = (err: Error) => void;
 
 /**
  * @param P  For most requests, this should be `ParamsDictionary`, but if you're
- * using this in a route handler for a route that uses a `RegExp` or a wildcard
- * `string` path (e.g. `'/user/*'`), then `req.params` will be an array, in
- * which case you should use `ParamsArray` instead.
- *
- * @see https://expressjs.com/en/api.html#req.params
+ * using this in a route handler for a route that uses a `RegExp`, then `req.params`
+ * will only contains strings, in which case you should use `ParamsFlatDictionary` instead.
  *
  * @example
- *     app.get('/user/:id', (req, res) => res.send(req.params.id)); // implicitly `ParamsDictionary`
- *     app.get<ParamsArray>(/user\/(.*)/, (req, res) => res.send(req.params[0]));
- *     app.get<ParamsArray>('/user/*', (req, res) => res.send(req.params[0]));
+ *     app.get('/user/:id', (req, res) => res.send(req.params.id)); // implicitly `ParamsDictionary`, parameter is string
+ *     app.get('/user/*id', (req, res) => res.send(req.params.id)); // implicitly `ParamsDictionary`, parameter is string[]
+ *     app.get(/user\/(?<id>.*)/, (req, res) => res.send(req.params.id)); // implicitly `ParamsFlatDictionary`, parameter is string
+ *     app.get(/user\/(.*)/, (req, res) => res.send(req.params[0])); // implicitly `ParamsFlatDictionary`, parameter is string
  */
 export interface Request<
     P = ParamsDictionary,
diff --git a/types/express-serve-static-core/v4/express-serve-static-core-tests.ts b/types/express-serve-static-core/v4/express-serve-static-core-tests.ts
@@ -42,18 +42,6 @@ app.route("/:foo").get(req => {
     req.is(1);
 });
 
-// Params can used as an array
-app.get<express.ParamsArray>("/*", req => {
-    req.params[0]; // $ExpectType string
-    req.params.length; // $ExpectType number
-});
-
-// Params can used as an array - under route
-app.route("/*").get<express.ParamsArray>(req => {
-    req.params[0]; // $ExpectType string
-    req.params.length; // $ExpectType number
-});
-
 // Params can be a custom type
 // NB. out-of-the-box all params are strings, however, other types are allowed to accommodate request validation/coercion middleware
 app.get<{ foo: string; bar: number }>("/:foo/:bar", req => {
diff --git a/types/express-serve-static-core/v4/index.d.ts b/types/express-serve-static-core/v4/index.d.ts
@@ -42,10 +42,9 @@ export interface Dictionary<T> {
 }
 
 export interface ParamsDictionary {
-    [key: string]: string;
+    [key: string | number]: string;
 }
-export type ParamsArray = string[];
-export type Params = ParamsDictionary | ParamsArray;
+export type Params = ParamsDictionary;
 
 export interface Locals extends Express.Locals {}
 
@@ -382,19 +381,6 @@ export interface RequestRanges extends RangeParserRanges {}
 
 export type Errback = (err: Error) => void;
 
-/**
- * @param P  For most requests, this should be `ParamsDictionary`, but if you're
- * using this in a route handler for a route that uses a `RegExp` or a wildcard
- * `string` path (e.g. `'/user/*'`), then `req.params` will be an array, in
- * which case you should use `ParamsArray` instead.
- *
- * @see https://expressjs.com/en/api.html#req.params
- *
- * @example
- *     app.get('/user/:id', (req, res) => res.send(req.params.id)); // implicitly `ParamsDictionary`
- *     app.get<ParamsArray>(/user\/(.*)/, (req, res) => res.send(req.params[0]));
- *     app.get<ParamsArray>('/user/*', (req, res) => res.send(req.params[0]));
- */
 export interface Request<
     P = ParamsDictionary,
     ResBody = any,
diff --git a/types/express/express-tests.ts b/types/express/express-tests.ts
@@ -1,5 +1,5 @@
 import express = require("express");
-import { ParamsArray, Request, RequestRanges } from "express-serve-static-core";
+import { Request, RequestRanges } from "express-serve-static-core";
 import * as http from "http";
 
 namespace express_tests {
@@ -139,24 +139,6 @@ namespace express_tests {
         req.params[0];
     });
 
-    // Params can used as an array
-    router.get<ParamsArray>("/*", req => {
-        req.params[0]; // $ExpectType string
-        req.params.length; // $ExpectType number
-    });
-
-    // Params can used as an array and can be specified via an explicit param type (express-serve-static-core)
-    router.get("/*", (req: Request<ParamsArray>) => {
-        req.params[0]; // $ExpectType string
-        req.params.length; // $ExpectType number
-    });
-
-    // Params can used as an array and can be specified via an explicit param type (express)
-    router.get("/*", (req: express.Request<ParamsArray>) => {
-        req.params[0]; // $ExpectType string
-        req.params.length; // $ExpectType number
-    });
-
     // Params can be a custom type
     // NB. out-of-the-box all params are strings, however, other types are allowed to accomadate request validation/coersion middleware
     router.get<{ foo: string; bar: number }>("/:foo/:bar", req => {
diff --git a/types/express/v4/express-tests.ts b/types/express/v4/express-tests.ts
@@ -1,5 +1,5 @@
 import express = require("express");
-import { ParamsArray, Request, RequestRanges } from "express-serve-static-core";
+import { Request, RequestRanges } from "express-serve-static-core";
 import * as http from "http";
 
 namespace express_tests {
@@ -146,24 +146,6 @@ namespace express_tests {
         req.params[0];
     });
 
-    // Params can used as an array
-    router.get<ParamsArray>("/*", req => {
-        req.params[0]; // $ExpectType string
-        req.params.length; // $ExpectType number
-    });
-
-    // Params can used as an array and can be specified via an explicit param type (express-serve-static-core)
-    router.get("/*", (req: Request<ParamsArray>) => {
-        req.params[0]; // $ExpectType string
-        req.params.length; // $ExpectType number
-    });
-
-    // Params can used as an array and can be specified via an explicit param type (express)
-    router.get("/*", (req: express.Request<ParamsArray>) => {
-        req.params[0]; // $ExpectType string
-        req.params.length; // $ExpectType number
-    });
-
     // Params can be a custom type
     // NB. out-of-the-box all params are strings, however, other types are allowed to accomadate request validation/coersion middleware
     router.get<{ foo: string; bar: number }>("/:foo/:bar", req => {
diff --git a/types/i18n/i18n-tests.ts b/types/i18n/i18n-tests.ts
@@ -248,7 +248,7 @@ app.get("/ar", (_req: Express.Request, res: i18n.Response) => {
     i18n.setLocale(res, "ar");
     i18n.setLocale(res.locals, "ar");
 
-    i18n.setLocale([req, res.locals], req.params.lang);
+    i18n.setLocale([req, res.locals], "ar");
     i18n.setLocale(res, "ar", true);
 });
 
