feat: support universal { fetch } handlers (#1210)

Author: pi0

src/h3.ts

@@ -5,9 +5,14 @@ import { callMiddleware, normalizeMiddleware } from "./middleware.ts";
 
 import type { ServerRequest } from "srvx";
 import type { RouterContext, MatchedRoute } from "rou3";
-import type { FetchHandler, H3Config, H3Plugin } from "./types/h3.ts";
+import type { RouteHandler, H3Config, H3Plugin } from "./types/h3.ts";
 import type { H3EventContext } from "./types/context.ts";
-import type { EventHandler, Middleware } from "./types/handler.ts";
+import type {
+  EventHandler,
+  FetchableObject,
+  FetchHandler,
+  Middleware,
+} from "./types/handler.ts";
 import type {
   H3Route,
   HTTPMethod,
@@ -110,7 +115,7 @@ export const H3Core = /* @__PURE__ */ (() => {
 
     mount(
       base: string,
-      input: FetchHandler | { fetch: FetchHandler } | H3Type,
+      input: FetchHandler | FetchableObject | H3Type,
     ): H3Type {
       if ("handler" in input) {
         if (input._middleware.length > 0) {
@@ -144,15 +149,22 @@ export const H3Core = /* @__PURE__ */ (() => {
     on(
       method: HTTPMethod | Lowercase<HTTPMethod> | "",
       route: string,
-      handler: EventHandler,
+      handler: RouteHandler,
       opts?: RouteOptions,
     ): H3Type {
       const _method = (method || "").toUpperCase();
       route = new URL(route, "http://_").pathname;
+      if (
+        typeof handler === "object" &&
+        typeof (handler as FetchableObject)?.fetch === "function"
+      ) {
+        const _fetchHandler = (handler as FetchableObject).fetch.bind(handler);
+        handler = (event) => _fetchHandler(event.req);
+      }
       this._addRoute({
         method: _method as HTTPMethod,
         route,
-        handler,
+        handler: handler as EventHandler,
         middleware: opts?.middleware,
         meta: { ...(handler as EventHandler).meta, ...opts?.meta },
       });

src/handler.ts

@@ -30,18 +30,24 @@ export function defineHandler<
   Res = EventHandlerResponse,
 >(def: EventHandlerObject<Req, Res>): EventHandlerWithFetch<Req, Res>;
 
-export function defineHandler(arg1: unknown): EventHandlerWithFetch {
-  if (typeof arg1 === "function") {
-    return handlerWithFetch(arg1 as EventHandler);
+export function defineHandler(
+  input: EventHandler | EventHandlerObject,
+): EventHandlerWithFetch {
+  if (typeof input === "function") {
+    return handlerWithFetch(input as EventHandler);
   }
-  const { middleware, handler, meta } = arg1 as EventHandlerObject;
-  const _handler = handlerWithFetch(
-    middleware?.length
-      ? (event) => callMiddleware(event, middleware, handler)
-      : handler,
+  const handler: EventHandler =
+    input.handler ||
+    (input.fetch ? (event) => input.fetch!(event.req) : () => {});
+
+  return Object.assign(
+    handlerWithFetch(
+      input.middleware?.length
+        ? (event) => callMiddleware(event, input.middleware!, handler)
+        : handler,
+    ),
+    input,
   );
-  _handler.meta = meta;
-  return _handler;
 }
 
 type StringHeaders<T> = {
@@ -100,6 +106,9 @@ function handlerWithFetch<
   Req extends EventHandlerRequest = EventHandlerRequest,
   Res = EventHandlerResponse,
 >(handler: EventHandler<Req, Res>): EventHandlerWithFetch<Req, Res> {
+  if ("fetch" in handler) {
+    return handler as EventHandlerWithFetch<Req, Res>;
+  }
   return Object.assign(handler, {
     fetch: (req: ServerRequest | URL | string): Promise<Response> => {
       if (typeof req === "string") {

src/index.ts

@@ -9,7 +9,7 @@ export type {
   PreparedResponse,
   RouteOptions,
   MiddlewareOptions,
-  FetchHandler,
+  RouteHandler,
 } from "./types/h3.ts";
 
 export { definePlugin } from "./types/h3.ts";
@@ -38,6 +38,8 @@ export type {
   LazyEventHandler,
   Middleware,
   EventHandlerObject,
+  FetchHandler,
+  FetchableObject,
 } from "./types/handler.ts";
 
 export {

src/types/h3.ts

@@ -1,8 +1,8 @@
 import type { H3EventContext } from "./context.ts";
-import type { EventHandler, Middleware } from "./handler.ts";
+import type { EventHandler, FetchableObject, Middleware } from "./handler.ts";
 import type { HTTPError } from "../error.ts";
 import type { MaybePromise } from "./_utils.ts";
-import type { ServerRequest } from "srvx";
+import type { FetchHandler, ServerRequest } from "srvx";
 import type { MatchedRoute } from "rou3";
 import type { H3Event } from "../event.ts";
 
@@ -44,7 +44,7 @@ export interface H3Route {
   handler: EventHandler;
 }
 
-// --- H3 Pluins ---
+// --- H3 Plugins ---
 
 export type H3Plugin = (h3: H3) => void;
 
@@ -56,7 +56,7 @@ export function definePlugin<T = unknown>(
 
 // --- H3 App ---
 
-export type FetchHandler = (req: ServerRequest) => Response | Promise<Response>;
+export type RouteHandler = EventHandler | FetchableObject;
 
 export type RouteOptions = {
   middleware?: Middleware[];
@@ -152,22 +152,22 @@ export declare class H3 {
   on(
     method: HTTPMethod | Lowercase<HTTPMethod> | "",
     route: string,
-    handler: EventHandler,
+    handler: RouteHandler,
     opts?: RouteOptions,
   ): this;
 
   /**
    * Register a route handler for all HTTP methods.
    */
-  all(route: string, handler: EventHandler, opts?: RouteOptions): this;
-
-  get(route: string, handler: EventHandler, opts?: RouteOptions): this;
-  post(route: string, handler: EventHandler, opts?: RouteOptions): this;
-  put(route: string, handler: EventHandler, opts?: RouteOptions): this;
-  delete(route: string, handler: EventHandler, opts?: RouteOptions): this;
-  patch(route: string, handler: EventHandler, opts?: RouteOptions): this;
-  head(route: string, handler: EventHandler, opts?: RouteOptions): this;
-  options(route: string, handler: EventHandler, opts?: RouteOptions): this;
-  connect(route: string, handler: EventHandler, opts?: RouteOptions): this;
-  trace(route: string, handler: EventHandler, opts?: RouteOptions): this;
+  all(route: string, handler: RouteHandler, opts?: RouteOptions): this;
+
+  get(route: string, handler: RouteHandler, opts?: RouteOptions): this;
+  post(route: string, handler: RouteHandler, opts?: RouteOptions): this;
+  put(route: string, handler: RouteHandler, opts?: RouteOptions): this;
+  delete(route: string, handler: RouteHandler, opts?: RouteOptions): this;
+  patch(route: string, handler: RouteHandler, opts?: RouteOptions): this;
+  head(route: string, handler: RouteHandler, opts?: RouteOptions): this;
+  options(route: string, handler: RouteHandler, opts?: RouteOptions): this;
+  connect(route: string, handler: RouteHandler, opts?: RouteOptions): this;
+  trace(route: string, handler: RouteHandler, opts?: RouteOptions): this;
 }

src/types/handler.ts

@@ -14,15 +14,12 @@ export interface EventHandler<
   meta?: H3RouteMeta;
 }
 
-export type EventHandlerFetch<T extends Response | TypedResponse = Response> = (
-  req: ServerRequest | URL | string,
-) => Promise<T>;
-
 export interface EventHandlerObject<
   _RequestT extends EventHandlerRequest = EventHandlerRequest,
   _ResponseT extends EventHandlerResponse = EventHandlerResponse,
 > {
-  handler: EventHandler<_RequestT, _ResponseT>;
+  handler?: EventHandler<_RequestT, _ResponseT>;
+  fetch?: FetchHandler;
   middleware?: Middleware[];
   meta?: H3RouteMeta;
 }
@@ -35,13 +32,6 @@ export interface EventHandlerRequest {
 
 export type EventHandlerResponse<T = unknown> = T | Promise<T>;
 
-export type EventHandlerWithFetch<
-  _RequestT extends EventHandlerRequest = EventHandlerRequest,
-  _ResponseT extends EventHandlerResponse = EventHandlerResponse,
-> = EventHandler<_RequestT, _ResponseT> & {
-  fetch: EventHandlerFetch<TypedResponse<_ResponseT, ResponseHeaderMap>>;
-};
-
 export type TypedServerRequest<
   _RequestT extends EventHandlerRequest = EventHandlerRequest,
 > = Omit<ServerRequest, "json" | "headers" | "clone"> &
@@ -53,6 +43,22 @@ export type TypedServerRequest<
     "json" | "headers" | "clone"
   >;
 
+// --- fetchable ---
+
+export type FetchHandler = (req: ServerRequest) => Response | Promise<Response>;
+export type FetchableObject = { fetch: FetchHandler };
+
+export type EventHandlerWithFetch<
+  _RequestT extends EventHandlerRequest = EventHandlerRequest,
+  _ResponseT extends EventHandlerResponse = EventHandlerResponse,
+> = EventHandler<_RequestT, _ResponseT> & {
+  fetch: EventHandlerFetch<TypedResponse<_ResponseT, ResponseHeaderMap>>;
+};
+
+export type EventHandlerFetch<T extends Response | TypedResponse = Response> = (
+  req: ServerRequest | URL | string,
+) => Promise<T>;
+
 //  --- middleware ---
 
 export type Middleware = (

test/app.test.ts

@@ -230,6 +230,16 @@ describeMatrix("app", (t, { it, expect }) => {
     expect(await res.text()).toBe("42");
   });
 
+  it("can use fetchable routes", async () => {
+    t.app.get("/fetchable", {
+      fetch: async () => {
+        return new Response("fetchable");
+      },
+    });
+    const res = await t.fetch("/fetchable");
+    expect(await res.text()).toBe("fetchable");
+  });
+
   it("handles next() call with no routes matching", async () => {
     t.app.use(() => {});
     t.app.use(() => {});

test/handler.test.ts

@@ -18,14 +18,24 @@ describe("handler.ts", () => {
       expect(eventHandler).toBe(handler);
     });
 
-    it("object syntax", () => {
+    it("object syntax (h3 handler)", () => {
       const handler = vi.fn();
       const middleware = [vi.fn()];
       const eventHandler = defineHandler({ handler, middleware });
       eventHandler({} as H3Event);
       expect(middleware[0]).toHaveBeenCalled();
       expect(handler).toHaveBeenCalled();
     });
+
+    it("object syntax (fetchable)", () => {
+      const fetchHandler = vi.fn();
+      const middleware = [vi.fn()];
+      const eventHandler = defineHandler({ fetch: fetchHandler, middleware });
+      eventHandler({} as H3Event);
+      expect(eventHandler.fetch).toBe(fetchHandler);
+      expect(middleware[0]).toHaveBeenCalled();
+      expect(fetchHandler).toHaveBeenCalled();
+    });
   });
 
   describe("dynamicEventHandler", () => {