Repository: TypeScript
Issue: [libdom] Allow Response / Request to be generics
Labels: Suggestion,Awaiting More Feedback

# Suggestion

<!--
  Please fill in each section completely. Thank you!
-->

## 🔍 Search Terms

<!--
  💡 Did you know? TypeScript has over 2,000 open suggestions!
  🔎 Please search thoroughly before logging new feature requests as most common ideas already have a proposal in progress.
  The "Common Feature Requests" section of the FAQ lists many popular requests: https://github.com/Microsoft/TypeScript/wiki/FAQ#common-feature-requests

  Replace the text below:
-->

request, response, libdom, generic, generics, type parameters

## ✅ Viability Checklist

<!--
   Suggestions that don't meet all these criteria are very, very unlikely to be accepted.
   We always recommend reviewing the TypeScript design goals before investing time writing
   a proposal for ideas outside the scope of the project.
-->
My suggestion meets these guidelines:

* [x] This wouldn't be a breaking change in existing TypeScript/JavaScript code
* [x] This wouldn't change the runtime behavior of existing JavaScript code
* [x] This could be implemented without emitting different JS based on the types of the expressions
* [x] This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
* [x] This feature would agree with the rest of [TypeScript's Design Goals](https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals).


## ⭐ Suggestion

<!-- A summary of what you'd like to see added or changed -->

Similar to the `FormData` request by @wesbos in https://github.com/microsoft/TypeScript/issues/43797, it would be great if the [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) and [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/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):

```ts
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:

```ts
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

<!--
  If you were announcing this feature in a blog post, what's a short explanation that shows
  a developer why this feature improves the language?
-->

The second example in the Suggestion section above.

## 💻 Use Cases

<!--
  What do you want to use this for?
  What shortcomings exist with current approaches?
  What workarounds are you using in the meantime?
-->

For typing the response body of API routes

### Prior Art

`@types/express`: [`Request` and `Response` types](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/be74f7ba952fdd657cfddd883069383b72491671/types/express/index.d.ts#L113-L131) - which both accept a generic type parameter.

### 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`:

```ts
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.