[libdom] Allow Response / Request to be generics

Suggestion

🔍 Search Terms

request, response, libdom, generic, generics, type parameters

✅ Viability Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

⭐ Suggestion

Similar to the FormData request by @wesbos in https://github.com/microsoft/TypeScript/issues/43797, it would be great if the Request and Response globals could also accept generic type parameters.

This will become more relevant as more frameworks continue to increase their usage of these standard globals, also in Node.js.

Consider the following example of an App Route handler in Next.js (handling a POST request to an API route):

export async function POST(request: Request): Response {
  const body = await request.json();
     // ^? const body: any ❌
  return new Response(JSON.stringify({
    abc: 123, // ❌ POST function return type cannot check type of response body object
  }))
}

What would be amazing would be something similar to this:

type RequestBody = { zzz: number };
type ResponseBody = { abc: number };

export async function POST(request: Request<RequestBody>): Response<ResponseBody> {
  const body = await request.json();
     // ^? const body: { zzz: number } ✅
  return new Response(JSON.stringify({
    abc: 123, // ✅ type checked
  }))
}

📃 Motivating Example

The second example in the Suggestion section above.

💻 Use Cases

For typing the response body of API routes

Prior Art

• @types/express: Request and Response types - which both accept a generic type parameter.
• Next.js: NextResponse accepting generic parameters

Workaround

Response

Wasn't able to find a nice workaround for typing the body of a Response yet.

Request

Using Type Assertion / casting via as:

type RequestBody = { zzz: string };

export async function POST(request: Request) {
  const body = await request.json() as RequestBody;

Caveats

1. Arguably, the Request body is unknown until runtime, so this is better handled instead with Zod or some other runtime validation. But for quick/simple projects without this validation, it's nice to be able to type the request body type.

Start by reviewing the lib.dom declarations for the Request and Response globals and the related FormData proposal in issue #43797. Clarify how generic body types should affect request.json() and response typing while preserving compatibility. Done means the proposed generic parameters and their behavior are specified and covered by the relevant TypeScript declaration tests.