feat: add event handler generics for typed request body and query (#417)

Co-authored-by: Pooya Parsa <pooya@pi0.io>

.github/workflows/ci.yml

@@ -24,5 +24,6 @@ jobs:
       - run: pnpm install
       - run: pnpm lint
       - run: pnpm build
+      - run: pnpm test:types
       - run: pnpm vitest --coverage && rm -rf coverage/tmp
       - uses: codecov/codecov-action@v3

.gitignore

@@ -6,3 +6,4 @@ coverage
 .profile
 .idea
 .eslintcache
+tsconfig.vitest-temp.json

package.json

@@ -27,7 +27,8 @@
     "play": "listhen ./playground/app.ts",
     "profile": "0x -o -D .profile -P 'autocannon -c 100 -p 10 -d 40 http://localhost:$PORT' ./playground/server.cjs",
     "release": "pnpm test && pnpm build && changelogen --release && pnpm publish && git push --follow-tags",
-    "test": "pnpm lint && vitest run --coverage"
+    "test": "pnpm lint && vitest --run typecheck && vitest --run --coverage",
+    "test:types": "vitest typecheck"
   },
   "dependencies": {
     "cookie-es": "^1.0.0",

src/event/event.ts

@@ -1,5 +1,5 @@
 import type { IncomingHttpHeaders } from "node:http";
-import type { H3EventContext, HTTPMethod } from "../types";
+import type { H3EventContext, HTTPMethod, EventHandlerRequest } from "../types";
 import type { NodeIncomingMessage, NodeServerResponse } from "../node";
 import {
   MIMES,
@@ -25,7 +25,11 @@ export interface NodeEventContext {
   res: NodeServerResponse;
 }
 
-export class H3Event implements Pick<FetchEvent, "respondWith"> {
+export class H3Event<
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  _RequestT extends EventHandlerRequest = EventHandlerRequest
+> implements Pick<FetchEvent, "respondWith">
+{
   "__is_event__" = true;
 
   // Context

src/event/utils.ts

@@ -1,8 +1,32 @@
-import type { EventHandler, LazyEventHandler } from "../types";
+import type {
+  EventHandler,
+  LazyEventHandler,
+  EventHandlerRequest,
+  EventHandlerResponse,
+} from "../types";
 
-export function defineEventHandler<T = any>(
-  handler: EventHandler<T>
-): EventHandler<T> {
+export function defineEventHandler<
+  Request extends EventHandlerRequest = EventHandlerRequest,
+  Response = any
+>(handler: EventHandler<Request, Response>): EventHandler<Request, Response>;
+// TODO: remove when appropriate
+// This signature provides backwards compatibility with previous signature where first generic was return type
+export function defineEventHandler<
+  Request = EventHandlerRequest,
+  Response = EventHandlerResponse
+>(
+  handler: EventHandler<
+    Request extends EventHandlerRequest ? Request : any,
+    Request extends EventHandlerRequest ? Response : Request
+  >
+): EventHandler<
+  Request extends EventHandlerRequest ? Request : any,
+  Request extends EventHandlerRequest ? Response : Request
+>;
+export function defineEventHandler<
+  Request extends EventHandlerRequest = EventHandlerRequest,
+  Response = EventHandlerResponse
+>(handler: EventHandler<Request, Response>): EventHandler<Request, Response> {
   handler.__is_handler__ = true;
   return handler;
 }

src/types.ts

@@ -1,5 +1,6 @@
+import type { QueryObject } from "ufo";
 import type { H3Event } from "./event";
-import { Session } from "./utils/session";
+import type { Session } from "./utils/session";
 
 export type {
   ValidateFunction,
@@ -40,9 +41,25 @@ export interface H3EventContext extends Record<string, any> {
 
 export type EventHandlerResponse<T = any> = T | Promise<T>;
 
-export interface EventHandler<T = any> {
+export interface EventHandlerRequest {
+  // TODO: Default to unknown in next major version
+  body?: any;
+
+  query?: QueryObject;
+}
+
+export type InferEventInput<
+  Key extends keyof EventHandlerRequest,
+  Event extends H3Event,
+  T
+> = void extends T ? (Event extends H3Event<infer E> ? E[Key] : never) : T;
+
+export interface EventHandler<
+  Request extends EventHandlerRequest = EventHandlerRequest,
+  Response extends EventHandlerResponse = EventHandlerResponse
+> {
   __is_handler__?: true;
-  (event: H3Event): EventHandlerResponse<T>;
+  (event: H3Event<Request>): Response;
 }
 
 export type LazyEventHandler = () => EventHandler | Promise<EventHandler>;

src/utils/body.ts

@@ -1,6 +1,6 @@
 import type { IncomingMessage } from "node:http";
 import destr from "destr";
-import type { Encoding, HTTPMethod } from "../types";
+import type { Encoding, HTTPMethod, InferEventInput } from "../types";
 import type { H3Event } from "../event";
 import { createError } from "../error";
 import { parse as parseMultipartData } from "./internal/multipart";
@@ -91,13 +91,15 @@ export function readRawBody<E extends Encoding = "utf8">(
  * const body = await readBody(event)
  * ```
  */
-export async function readBody<T = any>(
-  event: H3Event,
-  options: { strict?: boolean } = {}
-): Promise<T | undefined | string> {
+
+export async function readBody<
+  T,
+  Event extends H3Event = H3Event,
+  _T = InferEventInput<"body", Event, T>
+>(event: Event, options: { strict?: boolean } = {}): Promise<_T> {
   const request = event.node.req as InternalRequest<T>;
   if (ParsedBodySymbol in request) {
-    return request[ParsedBodySymbol];
+    return request[ParsedBodySymbol] as _T;
   }
 
   const contentType = request.headers["content-type"] || "";
@@ -116,13 +118,14 @@ export async function readBody<T = any>(
   }
 
   request[ParsedBodySymbol] = parsed;
-  return parsed;
+  return parsed as unknown as _T;
 }
 
-export async function readValidatedBody<T>(
-  event: H3Event,
-  validate: ValidateFunction<T>
-): Promise<T> {
+export async function readValidatedBody<
+  T,
+  Event extends H3Event = H3Event,
+  _T = InferEventInput<"body", Event, T>
+>(event: Event, validate: ValidateFunction<_T>): Promise<_T> {
   const _body = await readBody(event, { strict: true });
   return validateData(_body, validate);
 }

src/utils/request.ts

@@ -1,17 +1,22 @@
 import { getQuery as _getQuery } from "ufo";
 import { createError } from "../error";
-import type { HTTPMethod, RequestHeaders } from "../types";
+import type { HTTPMethod, InferEventInput, RequestHeaders } from "../types";
 import type { H3Event } from "../event";
 import { validateData, ValidateFunction } from "./internal/validate";
 
-export function getQuery(event: H3Event) {
-  return _getQuery(event.path || "");
+export function getQuery<
+  T,
+  Event extends H3Event = H3Event,
+  _T = Exclude<InferEventInput<"query", Event, T>, undefined>
+>(event: Event): _T {
+  return _getQuery(event.path || "") as _T;
 }
 
-export function getValidatedQuery<T>(
-  event: H3Event,
-  validate: ValidateFunction<T>
-): Promise<T> {
+export function getValidatedQuery<
+  T,
+  Event extends H3Event = H3Event,
+  _T = InferEventInput<"query", Event, T>
+>(event: Event, validate: ValidateFunction<_T>): Promise<_T> {
   const query = getQuery(event);
   return validateData(query, validate);
 }

test/types.test-d.ts

@@ -0,0 +1,104 @@
+import { describe, it, expectTypeOf } from "vitest";
+import type { QueryObject } from "ufo";
+import {
+  eventHandler,
+  H3Event,
+  getQuery,
+  readBody,
+  readValidatedBody,
+  getValidatedQuery,
+} from "../src";
+
+describe("types", () => {
+  describe("eventHandler", () => {
+    it("return type (inferred)", () => {
+      const handler = eventHandler(() => {
+        return {
+          foo: "bar",
+        };
+      });
+      const response = handler({} as H3Event);
+      expectTypeOf(response).toEqualTypeOf<{ foo: string }>();
+    });
+
+    it("return type (simple generic)", () => {
+      const handler = eventHandler<string>(() => {
+        return "";
+      });
+      const response = handler({} as H3Event);
+      expectTypeOf(response).toEqualTypeOf<string>();
+    });
+  });
+
+  describe("readBody", () => {
+    it("untyped", () => {
+      eventHandler(async (event) => {
+        const body = await readBody(event);
+        // TODO: Default to unknown in next major version
+        expectTypeOf(body).toBeAny();
+      });
+    });
+
+    it("typed via generic", () => {
+      eventHandler(async (event) => {
+        const body = await readBody<string>(event);
+        expectTypeOf(body).not.toBeAny();
+        expectTypeOf(body).toBeString();
+      });
+    });
+
+    it("typed via validator", () => {
+      eventHandler(async (event) => {
+        // eslint-disable-next-line unicorn/consistent-function-scoping
+        const validator = (body: unknown) => body as { id: string };
+        const body = await readValidatedBody(event, validator);
+        expectTypeOf(body).not.toBeAny();
+        expectTypeOf(body).toEqualTypeOf<{ id: string }>();
+      });
+    });
+
+    it("typed via event handler", () => {
+      eventHandler<{ body: { id: string } }>(async (event) => {
+        const body = await readBody(event);
+        expectTypeOf(body).not.toBeAny();
+        expectTypeOf(body).toEqualTypeOf<{ id: string }>();
+      });
+    });
+  });
+
+  describe("getQuery", () => {
+    it("untyped", () => {
+      eventHandler((event) => {
+        const query = getQuery(event);
+        expectTypeOf(query).not.toBeAny();
+        expectTypeOf(query).toEqualTypeOf<QueryObject>();
+      });
+    });
+
+    it("typed via generic", () => {
+      eventHandler((event) => {
+        const query = getQuery<{ id: string }>(event);
+        expectTypeOf(query).not.toBeAny();
+        expectTypeOf(query).toEqualTypeOf<{ id: string }>();
+      });
+    });
+
+    it("typed via validator", () => {
+      eventHandler(async (event) => {
+        // eslint-disable-next-line unicorn/consistent-function-scoping
+        const validator = (body: unknown) => body as { id: string };
+        const body = await getValidatedQuery(event, validator);
+        expectTypeOf(body).not.toBeAny();
+        expectTypeOf(body).toEqualTypeOf<{ id: string }>();
+      });
+    });
+
+    it("typed via event handler", () => {
+      eventHandler<{ query: { id: string } }>((event) => {
+        const query = getQuery(event);
+        expectTypeOf(query).not.toBeAny();
+        expectTypeOf(query).toEqualTypeOf<{ id: string }>();
+      });
+    });
+  });
+});

tsconfig.json

@@ -3,6 +3,8 @@
     "baseUrl": ".",
     "target": "ESNext",
     "module": "ESNext",
+    "skipLibCheck": true,
+    "allowSyntheticDefaultImports": true,
     "moduleResolution": "Node",
     "lib": [
       "WebWorker",
@@ -16,6 +18,7 @@
     ]
   },
   "include": [
-    "src"
+    "src",
+    "test/types.test-d.ts"
   ]
 }