refactor: merge H3Event with types

Author: pi0

src/_deprecated.ts

@@ -11,7 +11,7 @@ import { withBase } from "./utils/base.ts";
 import { sanitizeStatusCode, sanitizeStatusMessage } from "./utils/sanitize.ts";
 
 import type { NodeHandler, NodeMiddleware } from "./adapters.ts";
-import type { H3Event } from "./types/event.ts";
+import type { H3Event } from "./event.ts";
 import type { EventHandler } from "./types/handler.ts";
 import type { H3Config } from "./types/h3.ts";
 import type {

src/adapters.ts

@@ -8,8 +8,9 @@ import type {
   ServerRequest,
 } from "srvx";
 import type { H3 } from "./h3.ts";
-import type { H3Event, H3EventContext } from "./types/event.ts";
+import type { H3EventContext } from "./types/context.ts";
 import type { EventHandler, EventHandlerResponse } from "./types/handler.ts";
+import type { H3Event } from "./event.ts";
 
 export type NodeHandler = (
   req: NodeServerRequest,

src/event.ts

@@ -1,15 +1,43 @@
 import type { ServerRequest, ServerRuntimeContext } from "srvx";
-import type { H3Event as H3EventT, H3EventContext } from "./types/event.ts";
+import type { H3EventContext } from "./types/context.ts";
 
 import { EmptyObject } from "./utils/internal/obj.ts";
 import { FastURL } from "srvx";
+import type {
+  EventHandlerRequest,
+  TypedServerRequest,
+} from "./types/handler.ts";
 
-export class H3Event implements H3EventT {
-  static __is_event__ = true;
+export class H3Event<
+  _RequestT extends EventHandlerRequest = EventHandlerRequest,
+> {
+  /**
+   * Incoming HTTP request info.
+   *
+   * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/Request)
+   */
+  readonly req: TypedServerRequest<_RequestT>;
 
-  req: ServerRequest;
+  /**
+   * Access to the parsed request URL.
+   *
+   * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/URL)
+   */
   url: URL;
-  context: H3EventContext;
+
+  /**
+   * Event context.
+   */
+  readonly context: H3EventContext;
+
+  /**
+   * @internal
+   */
+  static __is_event__ = true;
+
+  /**
+   * @internal
+   */
   _res?: H3EventResponse;
 
   constructor(req: ServerRequest, context?: H3EventContext) {
@@ -20,49 +48,84 @@ export class H3Event implements H3EventT {
     this.url = _url && _url instanceof URL ? _url : new FastURL(req.url);
   }
 
+  /**
+   * Prepared HTTP response.
+   */
   get res(): H3EventResponse {
     if (!this._res) {
       this._res = new H3EventResponse();
     }
     return this._res;
   }
 
-  get path(): string {
-    return this.url.pathname + this.url.search;
+  /**
+   * Access to runtime specific additional context.
+   *
+   */
+  get runtime(): ServerRuntimeContext | undefined {
+    return this.req.runtime;
   }
 
-  get method(): string {
-    return this.req.method;
+  /**
+   * Tell the runtime about an ongoing operation that shouldn't close until the promise resolves.
+   */
+  waitUntil(promise: Promise<any>): void {
+    this.req.waitUntil?.(promise);
   }
 
-  get headers(): Headers {
-    return this.req.headers;
+  toString(): string {
+    return `[${this.req.method}] ${this.req.url}`;
   }
 
-  get runtime(): ServerRuntimeContext | undefined {
-    return this.req.runtime;
+  toJSON(): string {
+    return this.toString();
   }
 
+  // ------------- deprecated  ---------------
+
+  /**
+   * Access to the raw Node.js req/res objects.
+   *
+   * @deprecated Use `event.runtime.{node|deno|bun|...}.` instead.
+   */
   get node(): ServerRuntimeContext["node"] | undefined {
     return this.req.runtime?.node;
   }
 
-  waitUntil(promise: Promise<any>): void {
-    this.req.waitUntil?.(promise);
+  /**
+   * Access to the incoming request headers.
+   *
+   * @deprecated Use `event.req.headers` instead.
+   *
+   */
+  get headers(): Headers {
+    return this.req.headers;
   }
 
-  toString(): string {
-    return `[${this.req.method}] ${this.req.url}`;
+  /**
+   * Access to the incoming request url (pathname+search).
+   *
+   * @deprecated Use `event.url.pathname + event.url.search` instead.
+   *
+   * Example: `/api/hello?name=world`
+   * */
+  get path(): string {
+    return this.url.pathname + this.url.search;
   }
 
-  toJSON(): string {
-    return this.toString();
+  /**
+   * Access to the incoming request method.
+   *
+   * @deprecated Use `event.req.method` instead.
+   */
+  get method(): string {
+    return this.req.method;
   }
 }
 
 class H3EventResponse {
   status?: number;
-  // statusText?: string;
+  statusText?: string;
   _headers?: Headers;
   get headers(): Headers {
     if (!this._headers) {

src/h3.ts

@@ -5,7 +5,7 @@ import { callMiddleware, normalizeMiddleware } from "./middleware.ts";
 
 import type { RouterContext } from "rou3";
 import type { FetchHandler, H3Config, H3Plugin } from "./types/h3.ts";
-import type { H3EventContext } from "./types/event.ts";
+import type { H3EventContext } from "./types/context.ts";
 import type { EventHandler, Middleware } from "./types/handler.ts";
 import type {
   H3Route,

src/handler.ts

@@ -95,7 +95,7 @@ function handlerWithFetch<
       _init?: RequestInit,
     ): Promise<Response> => {
       const req = toRequest(_req, _init);
-      const event = new H3Event(req);
+      const event = new H3Event(req) as H3Event<Req>;
       try {
         return Promise.resolve(handleResponse(handler(event), event));
       } catch (error: any) {

src/index.ts

@@ -17,7 +17,7 @@ export { definePlugin } from "./types/h3.ts";
 export { H3 } from "./h3.ts";
 
 // Event
-export type { H3EventContext } from "./types/event.ts";
+export type { H3EventContext } from "./types/context.ts";
 export { H3Event } from "./event.ts";
 export { isEvent, mockEvent } from "./utils/event.ts";
 

src/middleware.ts

@@ -2,7 +2,7 @@ import { routeToRegExp } from "rou3";
 import { kNotFound } from "./response.ts";
 
 import type { H3 } from "./h3.ts";
-import type { H3Event } from "./types/event.ts";
+import type { H3Event } from "./event.ts";
 import type { MiddlewareOptions } from "./types/h3.ts";
 import type { EventHandler, Middleware } from "./types/handler.ts";
 

src/response.ts

@@ -3,7 +3,7 @@ import { HTTPError } from "./error.ts";
 import { isJSONSerializable } from "./utils/internal/object.ts";
 
 import type { H3Config } from "./types/h3.ts";
-import type { H3Event } from "./types/event.ts";
+import type { H3Event } from "./event.ts";
 
 export const kNotFound: symbol = /* @__PURE__ */ Symbol.for("h3.notFound");
 export const kHandled: symbol = /* @__PURE__ */ Symbol.for("h3.handled");

src/types/context.ts

@@ -0,0 +1,30 @@
+import type { Session } from "../utils/session.ts";
+import type { H3Route } from "./h3.ts";
+
+export interface H3EventContext extends Record<string, any> {
+  /* Matched router parameters */
+  params?: Record<string, string>;
+
+  /* Matched middleware parameters */
+  middlewareParams?: Record<string, string>;
+
+  /**
+   * Matched router Node
+   *
+   * @experimental The object structure may change in non-major version.
+   */
+  matchedRoute?: H3Route;
+
+  /* Cached session data */
+  sessions?: Record<string, Session>;
+
+  /* Trusted IP Address of client */
+  clientAddress?: string;
+
+  /* Basic authentication data */
+  basicAuth?: {
+    username?: string;
+    password?: string;
+    realm?: string;
+  };
+}