h3 1.8.2 → 1.10.0

package/README.md

@@ -7,9 +7,11 @@
 [![License][license-src]][license-href]
 [![JSDocs][jsdocs-src]][jsdocs-href]
 
-H3 is a minimal h(ttp) framework built for high performance and portability.
+H3 (pronounced as /eɪtʃθriː/, like h-3) is a minimal h(ttp) framework built for high performance and portability.
 
-👉 [Online Playground](https://stackblitz.com/github/unjs/h3/tree/main/playground?startScript=dev)
+👉 [Online Playground](https://stackblitz.com/github/unjs/h3/tree/main/playground)
+
+👉 [Online Examples Playground](https://stackblitz.com/github/unjs/h3/tree/main/examples)
 
 ## Features
 
@@ -135,7 +137,7 @@ app.use(router);
 
 Routes are internally stored in a [Radix Tree](https://en.wikipedia.org/wiki/Radix_tree) and matched using [unjs/radix3](https://github.com/unjs/radix3).
 
-For using nested routers, see [this example](https://stackblitz.com/edit/github-2bmusk?file=app.ts&startScript=dev)
+For using nested routers, see [this example](./examples/nested-router.ts)
 
 ## More app usage examples
 
@@ -214,7 +216,9 @@ H3 has a concept of composable utilities that accept `event` (from `eventHandler
 
 - `getQuery(event)`
 - `getValidatedQuery(event, validate)`
-- `getRouterParams(event)`
+- `getRouterParams(event, { decode? })`
+- `getRouterParam(event, name, { decode? })`
+- `getValidatedRouterParams(event, validate, { decode? })`
 - `getMethod(event, default?)`
 - `isMethod(event, expected, allowHead?)`
 - `assertMethod(event, expected, allowHead?)`
@@ -312,6 +316,23 @@ PRs are welcome to add your packages.
 - [h3-valibot](https://github.com/intevel/h3-valibot)
   - `useValidateBody(event, schema)`
   - `useValidateParams(event, schema)`
+- [h3-compression](https://github.com/CodeDredd/h3-compression)
+  - `useGZipCompression(event, response)`
+  - `useDeflateCompression(event, response)`
+  - `useBrotliCompression(event, response)`
+  - `useCompression(event, response)`
+  - `useGZipCompressionStream(event, response)`
+  - `useDeflateCompressionStream(event, response)`
+  - `useCompressionStream(event, response)`
+- [@intlify/h3](https://github.com/intlify/h3)
+  - `defineI18nMiddleware(options)`
+  - `useTranslation(event)`
+  - `getHeaderLocale(event, options)`
+  - `getHeaderLocales(event, options)`
+  - `getCookieLocale(event, options)`
+  - `setCookieLocale(event, options)`
+  - `getPathLocale(event, options)`
+  - `getQueryLocale(event, options)`
 
 ## License
 

package/dist/index.cjs

@@ -250,8 +250,9 @@ async function validateData(data, fn) {
 function createValidationError(validateError) {
   throw createError({
     status: 400,
-    message: validateError.message || "Validation Failed",
-    ...validateError
+    statusMessage: "Validation Error",
+    message: validateError?.message || "Validation Error",
+    data: validateError
   });
 }
 
@@ -262,11 +263,22 @@ function getValidatedQuery(event, validate) {
   const query = getQuery(event);
   return validateData(query, validate);
 }
-function getRouterParams(event) {
-  return event.context.params || {};
+function getRouterParams(event, opts = {}) {
+  let params = event.context.params || {};
+  if (opts.decode) {
+    params = { ...params };
+    for (const key in params) {
+      params[key] = ufo.decode(params[key]);
+    }
+  }
+  return params;
 }
-function getRouterParam(event, name) {
-  const params = getRouterParams(event);
+function getValidatedRouterParams(event, validate, opts = {}) {
+  const routerParams = getRouterParams(event, opts);
+  return validateData(routerParams, validate);
+}
+function getRouterParam(event, name, opts = {}) {
+  const params = getRouterParams(event, opts);
   return params[name];
 }
 function getMethod(event, defaultMethod = "GET") {
@@ -366,7 +378,7 @@ const ParsedBodySymbol = Symbol.for("h3ParsedBody");
 const PayloadMethods$1 = ["PATCH", "POST", "PUT", "DELETE"];
 function readRawBody(event, encoding = "utf8") {
   assertMethod(event, PayloadMethods$1);
-  const _rawBody = event._requestBody || event.web?.request?.body || event.node.req[RawBodySymbol] || event.node.req.body;
+  const _rawBody = event._requestBody || event.web?.request?.body || event.node.req[RawBodySymbol] || event.node.req.rawBody || event.node.req.body;
   if (_rawBody) {
     const promise2 = Promise.resolve(_rawBody).then((_resolved) => {
       if (Buffer.isBuffer(_resolved)) {
@@ -668,6 +680,9 @@ function sendNoContent(event, code) {
   if (event.handled) {
     return;
   }
+  if (!code && event.node.res.statusCode !== 200) {
+    code = event.node.res.statusCode;
+  }
   const _code = sanitizeStatusCode(code, 204);
   if (_code === 204) {
     event.node.res.removeHeader("content-length");
@@ -1000,6 +1015,37 @@ function handleCors(event, options) {
   return false;
 }
 
+async function getRequestFingerprint(event, opts = {}) {
+  const fingerprint = [];
+  if (opts.ip !== false) {
+    fingerprint.push(
+      getRequestIP(event, { xForwardedFor: opts.xForwardedFor })
+    );
+  }
+  if (opts.method === true) {
+    fingerprint.push(event.method);
+  }
+  if (opts.path === true) {
+    fingerprint.push(event.path);
+  }
+  if (opts.userAgent === true) {
+    fingerprint.push(getRequestHeader(event, "user-agent"));
+  }
+  const fingerprintString = fingerprint.filter(Boolean).join("|");
+  if (!fingerprintString) {
+    return null;
+  }
+  if (opts.hash === false) {
+    return fingerprintString;
+  }
+  const buffer = await crypto__default.subtle.digest(
+    opts.hash || "SHA-1",
+    new TextEncoder().encode(fingerprintString)
+  );
+  const hash = [...new Uint8Array(buffer)].map((b) => b.toString(16).padStart(2, "0")).join("");
+  return hash;
+}
+
 const PayloadMethods = /* @__PURE__ */ new Set(["PATCH", "POST", "PUT", "DELETE"]);
 const ignoredHeaders = /* @__PURE__ */ new Set([
   "transfer-encoding",
@@ -2059,6 +2105,7 @@ exports.getHeaders = getHeaders;
 exports.getMethod = getMethod;
 exports.getProxyRequestHeaders = getProxyRequestHeaders;
 exports.getQuery = getQuery;
+exports.getRequestFingerprint = getRequestFingerprint;
 exports.getRequestHeader = getRequestHeader;
 exports.getRequestHeaders = getRequestHeaders;
 exports.getRequestHost = getRequestHost;
@@ -2075,6 +2122,7 @@ exports.getRouterParam = getRouterParam;
 exports.getRouterParams = getRouterParams;
 exports.getSession = getSession;
 exports.getValidatedQuery = getValidatedQuery;
+exports.getValidatedRouterParams = getValidatedRouterParams;
 exports.handleCacheHeaders = handleCacheHeaders;
 exports.handleCors = handleCors;
 exports.isCorsOriginAllowed = isCorsOriginAllowed;

package/dist/index.d.cts

@@ -50,7 +50,20 @@ declare class H3Event<_RequestT extends EventHandlerRequest = EventHandlerReques
     /** @deprecated Please use `event.node.res` instead. **/
     get res(): ServerResponse<IncomingMessage>;
 }
+/**
+ * Checks if the input is an H3Event object.
+ * @param input - The input to check.
+ * @returns True if the input is an H3Event object, false otherwise.
+ * @see H3Event
+ */
 declare function isEvent(input: any): input is H3Event;
+/**
+ * Creates a new H3Event instance from the given Node.js request and response objects.
+ * @param req - The NodeIncomingMessage object.
+ * @param res - The NodeServerResponse object.
+ * @returns A new H3Event instance.
+ * @see H3Event
+ */
 declare function createEvent(req: IncomingMessage, res: ServerResponse): H3Event;
 
 declare function defineEventHandler<Request extends EventHandlerRequest = EventHandlerRequest, Response = EventHandlerResponse>(handler: EventHandler<Request, Response> | EventHandlerObject<Request, Response>): EventHandler<Request, Response>;
@@ -58,6 +71,11 @@ declare function defineEventHandler<Request = EventHandlerRequest, Response = Ev
 declare const eventHandler: typeof defineEventHandler;
 declare function defineRequestMiddleware<Request extends EventHandlerRequest = EventHandlerRequest>(fn: _RequestMiddleware<Request>): _RequestMiddleware<Request>;
 declare function defineResponseMiddleware<Request extends EventHandlerRequest = EventHandlerRequest>(fn: _ResponseMiddleware<Request>): _ResponseMiddleware<Request>;
+/**
+ * Checks if any kind of input is an event handler.
+ * @param input The input to check.
+ * @returns True if the input is an event handler, false otherwise.
+ */
 declare function isEventHandler(input: any): input is EventHandler;
 declare function toEventHandler(input: any, _?: any, _route?: string): EventHandler;
 interface DynamicEventHandler extends EventHandler {
@@ -162,6 +180,7 @@ type EventHandlerResponse<T = any> = T | Promise<T>;
 interface EventHandlerRequest {
     body?: any;
     query?: QueryObject;
+    routerParams?: Record<string, string>;
 }
 type InferEventInput<Key extends keyof EventHandlerRequest, Event extends H3Event, T> = void extends T ? (Event extends H3Event<infer E> ? E[Key] : never) : T;
 interface EventHandler<Request extends EventHandlerRequest = EventHandlerRequest, Response extends EventHandlerResponse = EventHandlerResponse> {
@@ -178,9 +197,9 @@ type EventHandlerObject<Request extends EventHandlerRequest = EventHandlerReques
     handler: EventHandler<Request, Response>;
 };
 type LazyEventHandler = () => EventHandler | Promise<EventHandler>;
-type RequestHeaders = {
-    [name: string]: string | undefined;
-};
+type RequestHeaders = Partial<Record<HTTPHeaderName, string | undefined>>;
+type _HTTPHeaderName = "WWW-Authenticate" | "Authorization" | "Proxy-Authenticate" | "Proxy-Authorization" | "Age" | "Cache-Control" | "Clear-Site-Data" | "Expires" | "Pragma" | "Accept-CH" | "Critical-CH" | "Sec-CH-UA" | "Sec-CH-UA-Arch" | "Sec-CH-UA-Bitness" | "Sec-CH-UA-Full-Version-List" | "Sec-CH-UA-Mobile" | "Sec-CH-UA-Model" | "Sec-CH-UA-Platform" | "Sec-CH-UA-Platform-Version" | "Sec-CH-UA-Prefers-Color-Scheme" | "Sec-CH-UA-Prefers-Reduced-Motion" | "Downlink" | "ECT" | "RTT" | "Save-Data" | "Last-Modified" | "ETag" | "If-Match" | "If-None-Match" | "If-Modified-Since" | "If-Unmodified-Since" | "Vary" | "Connection" | "Keep-Alive" | "Accept" | "Accept-Encoding" | "Accept-Language" | "Expect" | "Max-Forwards" | "Cookie" | "Set-Cookie" | "Access-Control-Allow-Origin" | "Access-Control-Allow-Credentials" | "Access-Control-Allow-Headers" | "Access-Control-Allow-Methods" | "Access-Control-Expose-Headers" | "Access-Control-Max-Age" | "Access-Control-Request-Headers" | "Access-Control-Request-Method" | "Origin" | "Timing-Allow-Origin" | "Content-Disposition" | "Content-Length" | "Content-Type" | "Content-Encoding" | "Content-Language" | "Content-Location" | "Forwarded" | "X-Forwarded-For" | "X-Forwarded-Host" | "X-Forwarded-Proto" | "Via" | "Location" | "Refresh" | "From" | "Host" | "Referer" | "Referrer-Policy" | "User-Agent" | "Allow" | "Server" | "Accept-Ranges" | "Range" | "If-Range" | "Content-Range" | "Cross-Origin-Embedder-Policy" | "Cross-Origin-Opener-Policy" | "Cross-Origin-Resource-Policy" | "Content-Security-Policy" | "Content-Security-Policy-Report-Only" | "Expect-CT" | "Origin-Isolation" | "Permissions-Policy" | "Strict-Transport-Security" | "Upgrade-Insecure-Requests" | "X-Content-Type-Options" | "X-Frame-Options" | "X-Permitted-Cross-Domain-Policies" | "X-Powered-By" | "X-XSS-Protection" | "Sec-Fetch-Site" | "Sec-Fetch-Mode" | "Sec-Fetch-User" | "Sec-Fetch-Dest" | "Sec-Purpose" | "Service-Worker-Navigation-Preload" | "Last-Event-ID" | "NEL" | "Ping-From" | "Ping-To" | "Report-To" | "Transfer-Encoding" | "TE" | "Trailer" | "Sec-WebSocket-Key" | "Sec-WebSocket-Extensions" | "Sec-WebSocket-Accept" | "Sec-WebSocket-Protocol" | "Sec-WebSocket-Version" | "Accept-Push-Policy" | "Accept-Signature" | "Alt-Svc" | "Alt-Used" | "Date" | "Early-Data" | "Link" | "Push-Policy" | "Retry-After" | "Signature" | "Signed-Headers" | "Server-Timing" | "Service-Worker-Allowed" | "SourceMap" | "Upgrade" | "X-DNS-Prefetch-Control" | "X-Pingback" | "X-Requested-With" | "X-Robots-Tag";
+type HTTPHeaderName = _HTTPHeaderName | Lowercase<_HTTPHeaderName> | (string & {});
 
 /**
  * H3 Runtime Error
@@ -190,22 +209,22 @@ type RequestHeaders = {
  * @property {string} statusMessage - A string representing the HTTP status message.
  * @property {boolean} fatal - Indicates if the error is a fatal error.
  * @property {boolean} unhandled - Indicates if the error was unhandled and auto captured.
- * @property {any} data - An extra data that will be included in the response.
+ * @property {DataT} data - An extra data that will be included in the response.
  *                         This can be used to pass additional information about the error.
  * @property {boolean} internal - Setting this property to `true` will mark the error as an internal error.
  */
-declare class H3Error extends Error {
+declare class H3Error<DataT = unknown> extends Error {
     static __h3_error__: boolean;
     statusCode: number;
     fatal: boolean;
     unhandled: boolean;
     statusMessage?: string;
-    data?: any;
+    data?: DataT;
     cause?: unknown;
     constructor(message: string, opts?: {
         cause?: unknown;
     });
-    toJSON(): Pick<H3Error, "data" | "statusCode" | "statusMessage" | "message">;
+    toJSON(): Pick<H3Error<DataT>, "data" | "statusCode" | "statusMessage" | "message">;
 }
 /**
  * Creates a new `Error` that can be used to handle both internal and runtime errors.
@@ -213,10 +232,10 @@ declare class H3Error extends Error {
  * @param input {string | (Partial<H3Error> & { status?: number; statusText?: string })} - The error message or an object containing error properties.
  * @return {H3Error} - An instance of H3Error.
  */
-declare function createError(input: string | (Partial<H3Error> & {
+declare function createError<DataT = unknown>(input: string | (Partial<H3Error<DataT>> & {
     status?: number;
     statusText?: string;
-})): H3Error;
+})): H3Error<DataT>;
 /**
  * Receives an error and returns the corresponding response.
  * H3 internally uses this function to handle unhandled errors.
@@ -234,7 +253,7 @@ declare function sendError(event: H3Event, error: Error | H3Error, debug?: boole
  * @param input {*} - The input to check.
  * @return {boolean} - Returns true if the input is an instance of H3Error, false otherwise.
  */
-declare function isError(input: any): input is H3Error;
+declare function isError<DataT = unknown>(input: any): input is H3Error<DataT>;
 
 interface Layer {
     route: string;
@@ -276,6 +295,11 @@ declare function createApp(options?: AppOptions): App;
 declare function use(app: App, arg1: string | EventHandler | InputLayer | InputLayer[], arg2?: Partial<InputLayer> | EventHandler | EventHandler[], arg3?: Partial<InputLayer>): App;
 declare function createAppEventHandler(stack: Stack, options: AppOptions): EventHandler<EventHandlerRequest, Promise<void>>;
 
+/**
+ * Prefixes and executes a handler with a base path.
+ * @param base The base path to prefix. When set to an empty string, the handler will be run as is.
+ * @param handler The event handler to use with the adapted path.
+ */
 declare function useBase(base: string, handler: EventHandler): EventHandler;
 
 interface MultiPartData {
@@ -295,8 +319,8 @@ interface MultiPartData {
 declare function readRawBody<E extends Encoding = "utf8">(event: H3Event, encoding?: E): E extends false ? Promise<Buffer | undefined> : Promise<string | undefined>;
 /**
  * Reads request body and tries to safely parse using [destr](https://github.com/unjs/destr).
- * @param event {H3Event} H3 event passed by h3 handler
- * @param encoding {Encoding} encoding="utf-8" - The character encoding to use.
+ * @param event H3 event passed by h3 handler
+ * @param encoding The character encoding to use, defaults to 'utf-8'.
  *
  * @return {*} The `Object`, `Array`, `String`, `Number`, `Boolean`, or `null` value corresponding to the request JSON body
  *
@@ -307,12 +331,52 @@ declare function readRawBody<E extends Encoding = "utf8">(event: H3Event, encodi
 declare function readBody<T, Event extends H3Event = H3Event, _T = InferEventInput<"body", Event, T>>(event: Event, options?: {
     strict?: boolean;
 }): Promise<_T>;
+/**
+ * Tries to read the request body via `readBody`, then uses the provided validation function and either throws a validation error or returns the result.
+ * @param event The H3Event passed by the handler.
+ * @param validate The function to use for body validation. It will be called passing the read request body. If the result is not false, the parsed body will be returned.
+ * @throws If the validation function returns `false` or throws, a validation error will be thrown.
+ * @return {*} The `Object`, `Array`, `String`, `Number`, `Boolean`, or `null` value corresponding to the request JSON body.
+ * @see {readBody}
+ *
+ * ```ts
+ * // With a custom validation function
+ * const body = await readValidatedBody(event, (body) => {
+ *   return typeof body === "object" && body !== null
+ * })
+ *
+ * // With a zod schema
+ * import { z } from 'zod'
+ * const objectSchema = z.object()
+ * const body = await readValidatedBody(event, objectSchema.safeParse)
+ * ```
+ */
 declare function readValidatedBody<T, Event extends H3Event = H3Event, _T = InferEventInput<"body", Event, T>>(event: Event, validate: ValidateFunction<_T>): Promise<_T>;
+/**
+ * Tries to read and parse the body of a an H3Event as multipart form.
+ * @param event The H3Event object to read multipart form from.
+ *
+ * @return The parsed form data. If no form could be detected because the content type is not multipart/form-data or no boundary could be found.
+ *
+ * ```ts
+ * const formData = await readMultipartFormData(event)
+ * // The result could look like:
+ * // [
+ * //   {
+ * //     "data": "other",
+ * //     "name": "baz",
+ * //   },
+ * //   {
+ * //     "data": "something",
+ * //     "name": "some-other-data",
+ * //   },
+ * // ]
+ * ```
+ */
 declare function readMultipartFormData(event: H3Event): Promise<MultiPartData[] | undefined>;
 /**
- * Constructs a FormData object from an event.
- * @param event {H3Event}
- * @returns {FormData}
+ * Constructs a FormData object from an event, after converting it to a a web request.
+ * @param event The H3Event object to read the form data from.
  *
  * ```ts
  * const eventHandler = event => {
@@ -323,6 +387,11 @@ declare function readMultipartFormData(event: H3Event): Promise<MultiPartData[]
  * ```
  */
 declare function readFormData(event: H3Event): Promise<FormData>;
+/**
+ * Captures a stream from a request.
+ * @param event The H3Event object containing the request information.
+ * @returns Undefined if the request can't transport a payload, otherwise a ReadableStream of the request body.
+ */
 declare function getRequestWebStream(event: H3Event): undefined | ReadableStream;
 
 interface CacheConditions {
@@ -359,8 +428,15 @@ declare function handleCors(event: H3Event, options: H3CorsOptions): boolean;
 
 declare function getQuery<T, Event extends H3Event = H3Event, _T = Exclude<InferEventInput<"query", Event, T>, undefined>>(event: Event): _T;
 declare function getValidatedQuery<T, Event extends H3Event = H3Event, _T = InferEventInput<"query", Event, T>>(event: Event, validate: ValidateFunction<_T>): Promise<_T>;
-declare function getRouterParams(event: H3Event): NonNullable<H3Event["context"]["params"]>;
-declare function getRouterParam(event: H3Event, name: string): string | undefined;
+declare function getRouterParams(event: H3Event, opts?: {
+    decode?: boolean;
+}): NonNullable<H3Event["context"]["params"]>;
+declare function getValidatedRouterParams<T, Event extends H3Event = H3Event, _T = InferEventInput<"routerParams", Event, T>>(event: Event, validate: ValidateFunction<_T>, opts?: {
+    decode?: boolean;
+}): Promise<_T>;
+declare function getRouterParam(event: H3Event, name: string, opts?: {
+    decode?: boolean;
+}): string | undefined;
 /**
  * @deprecated Directly use `event.method` instead.
  */
@@ -369,7 +445,7 @@ declare function isMethod(event: H3Event, expected: HTTPMethod | HTTPMethod[], a
 declare function assertMethod(event: H3Event, expected: HTTPMethod | HTTPMethod[], allowHead?: boolean): void;
 declare function getRequestHeaders(event: H3Event): RequestHeaders;
 declare const getHeaders: typeof getRequestHeaders;
-declare function getRequestHeader(event: H3Event, name: string): RequestHeaders[string];
+declare function getRequestHeader(event: H3Event, name: HTTPHeaderName): RequestHeaders[string];
 declare const getHeader: typeof getRequestHeader;
 declare function getRequestHost(event: H3Event, opts?: {
     xForwardedHost?: boolean;
@@ -449,6 +525,23 @@ declare function deleteCookie(event: H3Event, name: string, serializeOptions?: C
  */
 declare function splitCookiesString(cookiesString: string | string[]): string[];
 
+interface RequestFingerprintOptions {
+    /** @default SHA-1 */
+    hash?: false | "SHA-1";
+    /** @default `true` */
+    ip?: boolean;
+    /** @default `false` */
+    xForwardedFor?: boolean;
+    /** @default `false` */
+    method?: boolean;
+    /** @default `false` */
+    path?: boolean;
+    /** @default `false` */
+    userAgent?: boolean;
+}
+/** @experimental Behavior of this utility might change in the future versions */
+declare function getRequestFingerprint(event: H3Event, opts?: RequestFingerprintOptions): Promise<string | null>;
+
 type Duplex = "half" | "full";
 interface ProxyOptions {
     headers?: RequestHeaders | HeadersInit;
@@ -488,14 +581,14 @@ declare function getResponseStatusText(event: H3Event): string;
 declare function defaultContentType(event: H3Event, type?: string): void;
 declare function sendRedirect(event: H3Event, location: string, code?: number): Promise<void>;
 declare function getResponseHeaders(event: H3Event): ReturnType<H3Event["res"]["getHeaders"]>;
-declare function getResponseHeader(event: H3Event, name: string): ReturnType<H3Event["res"]["getHeader"]>;
-declare function setResponseHeaders(event: H3Event, headers: Record<string, Parameters<OutgoingMessage["setHeader"]>[1]>): void;
+declare function getResponseHeader(event: H3Event, name: HTTPHeaderName): ReturnType<H3Event["res"]["getHeader"]>;
+declare function setResponseHeaders(event: H3Event, headers: Record<HTTPHeaderName, Parameters<OutgoingMessage["setHeader"]>[1]>): void;
 declare const setHeaders: typeof setResponseHeaders;
-declare function setResponseHeader(event: H3Event, name: string, value: Parameters<OutgoingMessage["setHeader"]>[1]): void;
+declare function setResponseHeader(event: H3Event, name: HTTPHeaderName, value: Parameters<OutgoingMessage["setHeader"]>[1]): void;
 declare const setHeader: typeof setResponseHeader;
 declare function appendResponseHeaders(event: H3Event, headers: Record<string, string>): void;
 declare const appendHeaders: typeof appendResponseHeaders;
-declare function appendResponseHeader(event: H3Event, name: string, value: string): void;
+declare function appendResponseHeader(event: H3Event, name: HTTPHeaderName, value: string): void;
 declare const appendHeader: typeof appendResponseHeader;
 /**
  * Remove all response headers, or only those specified in the headerNames array.
@@ -503,7 +596,7 @@ declare const appendHeader: typeof appendResponseHeader;
  * @param headerNames Array of header names to remove
  */
 declare function clearResponseHeaders(event: H3Event, headerNames?: string[]): void;
-declare function removeResponseHeader(event: H3Event, name: string): void;
+declare function removeResponseHeader(event: H3Event, name: HTTPHeaderName): void;
 declare function isStream(data: any): data is Readable | ReadableStream;
 declare function isWebResponse(data: any): data is Response;
 declare function sendStream(event: H3Event, stream: Readable | ReadableStream): Promise<void>;
@@ -578,4 +671,4 @@ declare function toPlainHandler(app: App): PlainHandler;
 /** @experimental */
 declare function fromPlainHandler(handler: PlainHandler): EventHandler<EventHandlerRequest, Promise<unknown>>;
 
-export { type AddRouteShortcuts, type App, type AppOptions, type AppUse, type CacheConditions, type CreateRouterOptions, type Duplex, type DynamicEventHandler, type Encoding, type EventHandler, type EventHandlerObject, type EventHandlerRequest, type EventHandlerResponse, type H3CorsOptions, H3Error, H3Event, type H3EventContext, H3Headers, H3Response, type HTTPMethod, type InferEventInput, type InputLayer, type InputStack, type Layer, type LazyEventHandler, MIMES, type Matcher, type MultiPartData, type NodeEventContext, type NodeListener, type NodeMiddleware, type NodePromisifiedHandler, type PlainHandler, type PlainRequest, type PlainResponse, type ProxyOptions, type RequestHeaders, type RouteNode, type Router, type RouterMethod, type RouterUse, type ServeStaticOptions, type Session, type SessionConfig, type SessionData, type Stack, type StaticAssetMeta, type ValidateFunction, type ValidateResult, type WebEventContext, type WebHandler, type _RequestMiddleware, type _ResponseMiddleware, appendCorsHeaders, appendCorsPreflightHeaders, appendHeader, appendHeaders, appendResponseHeader, appendResponseHeaders, assertMethod, callNodeListener, clearResponseHeaders, clearSession, createApp, createAppEventHandler, createError, createEvent, createRouter, defaultContentType, defineEventHandler, defineLazyEventHandler, defineNodeListener, defineNodeMiddleware, defineRequestMiddleware, defineResponseMiddleware, deleteCookie, dynamicEventHandler, eventHandler, fetchWithEvent, fromNodeMiddleware, fromPlainHandler, fromWebHandler, getCookie, getHeader, getHeaders, getMethod, getProxyRequestHeaders, getQuery, getRequestHeader, getRequestHeaders, getRequestHost, getRequestIP, getRequestPath, getRequestProtocol, getRequestURL, getRequestWebStream, getResponseHeader, getResponseHeaders, getResponseStatus, getResponseStatusText, getRouterParam, getRouterParams, getSession, getValidatedQuery, handleCacheHeaders, handleCors, isCorsOriginAllowed, isError, isEvent, isEventHandler, isMethod, isPreflightRequest, isStream, isWebResponse, lazyEventHandler, parseCookies, promisifyNodeListener, proxyRequest, readBody, readFormData, readMultipartFormData, readRawBody, readValidatedBody, removeResponseHeader, sanitizeStatusCode, sanitizeStatusMessage, sealSession, send, sendError, sendNoContent, sendProxy, sendRedirect, sendStream, sendWebResponse, serveStatic, setCookie, setHeader, setHeaders, setResponseHeader, setResponseHeaders, setResponseStatus, splitCookiesString, toEventHandler, toNodeListener, toPlainHandler, toWebHandler, toWebRequest, unsealSession, updateSession, use, useBase, useSession, writeEarlyHints };
+export { type AddRouteShortcuts, type App, type AppOptions, type AppUse, type CacheConditions, type CreateRouterOptions, type Duplex, type DynamicEventHandler, type Encoding, type EventHandler, type EventHandlerObject, type EventHandlerRequest, type EventHandlerResponse, type H3CorsOptions, H3Error, H3Event, type H3EventContext, H3Headers, H3Response, type HTTPHeaderName, type HTTPMethod, type InferEventInput, type InputLayer, type InputStack, type Layer, type LazyEventHandler, MIMES, type Matcher, type MultiPartData, type NodeEventContext, type NodeListener, type NodeMiddleware, type NodePromisifiedHandler, type PlainHandler, type PlainRequest, type PlainResponse, type ProxyOptions, type RequestFingerprintOptions, type RequestHeaders, type RouteNode, type Router, type RouterMethod, type RouterUse, type ServeStaticOptions, type Session, type SessionConfig, type SessionData, type Stack, type StaticAssetMeta, type ValidateFunction, type ValidateResult, type WebEventContext, type WebHandler, type _RequestMiddleware, type _ResponseMiddleware, appendCorsHeaders, appendCorsPreflightHeaders, appendHeader, appendHeaders, appendResponseHeader, appendResponseHeaders, assertMethod, callNodeListener, clearResponseHeaders, clearSession, createApp, createAppEventHandler, createError, createEvent, createRouter, defaultContentType, defineEventHandler, defineLazyEventHandler, defineNodeListener, defineNodeMiddleware, defineRequestMiddleware, defineResponseMiddleware, deleteCookie, dynamicEventHandler, eventHandler, fetchWithEvent, fromNodeMiddleware, fromPlainHandler, fromWebHandler, getCookie, getHeader, getHeaders, getMethod, getProxyRequestHeaders, getQuery, getRequestFingerprint, getRequestHeader, getRequestHeaders, getRequestHost, getRequestIP, getRequestPath, getRequestProtocol, getRequestURL, getRequestWebStream, getResponseHeader, getResponseHeaders, getResponseStatus, getResponseStatusText, getRouterParam, getRouterParams, getSession, getValidatedQuery, getValidatedRouterParams, handleCacheHeaders, handleCors, isCorsOriginAllowed, isError, isEvent, isEventHandler, isMethod, isPreflightRequest, isStream, isWebResponse, lazyEventHandler, parseCookies, promisifyNodeListener, proxyRequest, readBody, readFormData, readMultipartFormData, readRawBody, readValidatedBody, removeResponseHeader, sanitizeStatusCode, sanitizeStatusMessage, sealSession, send, sendError, sendNoContent, sendProxy, sendRedirect, sendStream, sendWebResponse, serveStatic, setCookie, setHeader, setHeaders, setResponseHeader, setResponseHeaders, setResponseStatus, splitCookiesString, toEventHandler, toNodeListener, toPlainHandler, toWebHandler, toWebRequest, unsealSession, updateSession, use, useBase, useSession, writeEarlyHints };

package/dist/index.d.mts

@@ -50,7 +50,20 @@ declare class H3Event<_RequestT extends EventHandlerRequest = EventHandlerReques
     /** @deprecated Please use `event.node.res` instead. **/
     get res(): ServerResponse<IncomingMessage>;
 }
+/**
+ * Checks if the input is an H3Event object.
+ * @param input - The input to check.
+ * @returns True if the input is an H3Event object, false otherwise.
+ * @see H3Event
+ */
 declare function isEvent(input: any): input is H3Event;
+/**
+ * Creates a new H3Event instance from the given Node.js request and response objects.
+ * @param req - The NodeIncomingMessage object.
+ * @param res - The NodeServerResponse object.
+ * @returns A new H3Event instance.
+ * @see H3Event
+ */
 declare function createEvent(req: IncomingMessage, res: ServerResponse): H3Event;
 
 declare function defineEventHandler<Request extends EventHandlerRequest = EventHandlerRequest, Response = EventHandlerResponse>(handler: EventHandler<Request, Response> | EventHandlerObject<Request, Response>): EventHandler<Request, Response>;
@@ -58,6 +71,11 @@ declare function defineEventHandler<Request = EventHandlerRequest, Response = Ev
 declare const eventHandler: typeof defineEventHandler;
 declare function defineRequestMiddleware<Request extends EventHandlerRequest = EventHandlerRequest>(fn: _RequestMiddleware<Request>): _RequestMiddleware<Request>;
 declare function defineResponseMiddleware<Request extends EventHandlerRequest = EventHandlerRequest>(fn: _ResponseMiddleware<Request>): _ResponseMiddleware<Request>;
+/**
+ * Checks if any kind of input is an event handler.
+ * @param input The input to check.
+ * @returns True if the input is an event handler, false otherwise.
+ */
 declare function isEventHandler(input: any): input is EventHandler;
 declare function toEventHandler(input: any, _?: any, _route?: string): EventHandler;
 interface DynamicEventHandler extends EventHandler {
@@ -162,6 +180,7 @@ type EventHandlerResponse<T = any> = T | Promise<T>;
 interface EventHandlerRequest {
     body?: any;
     query?: QueryObject;
+    routerParams?: Record<string, string>;
 }
 type InferEventInput<Key extends keyof EventHandlerRequest, Event extends H3Event, T> = void extends T ? (Event extends H3Event<infer E> ? E[Key] : never) : T;
 interface EventHandler<Request extends EventHandlerRequest = EventHandlerRequest, Response extends EventHandlerResponse = EventHandlerResponse> {
@@ -178,9 +197,9 @@ type EventHandlerObject<Request extends EventHandlerRequest = EventHandlerReques
     handler: EventHandler<Request, Response>;
 };
 type LazyEventHandler = () => EventHandler | Promise<EventHandler>;
-type RequestHeaders = {
-    [name: string]: string | undefined;
-};
+type RequestHeaders = Partial<Record<HTTPHeaderName, string | undefined>>;
+type _HTTPHeaderName = "WWW-Authenticate" | "Authorization" | "Proxy-Authenticate" | "Proxy-Authorization" | "Age" | "Cache-Control" | "Clear-Site-Data" | "Expires" | "Pragma" | "Accept-CH" | "Critical-CH" | "Sec-CH-UA" | "Sec-CH-UA-Arch" | "Sec-CH-UA-Bitness" | "Sec-CH-UA-Full-Version-List" | "Sec-CH-UA-Mobile" | "Sec-CH-UA-Model" | "Sec-CH-UA-Platform" | "Sec-CH-UA-Platform-Version" | "Sec-CH-UA-Prefers-Color-Scheme" | "Sec-CH-UA-Prefers-Reduced-Motion" | "Downlink" | "ECT" | "RTT" | "Save-Data" | "Last-Modified" | "ETag" | "If-Match" | "If-None-Match" | "If-Modified-Since" | "If-Unmodified-Since" | "Vary" | "Connection" | "Keep-Alive" | "Accept" | "Accept-Encoding" | "Accept-Language" | "Expect" | "Max-Forwards" | "Cookie" | "Set-Cookie" | "Access-Control-Allow-Origin" | "Access-Control-Allow-Credentials" | "Access-Control-Allow-Headers" | "Access-Control-Allow-Methods" | "Access-Control-Expose-Headers" | "Access-Control-Max-Age" | "Access-Control-Request-Headers" | "Access-Control-Request-Method" | "Origin" | "Timing-Allow-Origin" | "Content-Disposition" | "Content-Length" | "Content-Type" | "Content-Encoding" | "Content-Language" | "Content-Location" | "Forwarded" | "X-Forwarded-For" | "X-Forwarded-Host" | "X-Forwarded-Proto" | "Via" | "Location" | "Refresh" | "From" | "Host" | "Referer" | "Referrer-Policy" | "User-Agent" | "Allow" | "Server" | "Accept-Ranges" | "Range" | "If-Range" | "Content-Range" | "Cross-Origin-Embedder-Policy" | "Cross-Origin-Opener-Policy" | "Cross-Origin-Resource-Policy" | "Content-Security-Policy" | "Content-Security-Policy-Report-Only" | "Expect-CT" | "Origin-Isolation" | "Permissions-Policy" | "Strict-Transport-Security" | "Upgrade-Insecure-Requests" | "X-Content-Type-Options" | "X-Frame-Options" | "X-Permitted-Cross-Domain-Policies" | "X-Powered-By" | "X-XSS-Protection" | "Sec-Fetch-Site" | "Sec-Fetch-Mode" | "Sec-Fetch-User" | "Sec-Fetch-Dest" | "Sec-Purpose" | "Service-Worker-Navigation-Preload" | "Last-Event-ID" | "NEL" | "Ping-From" | "Ping-To" | "Report-To" | "Transfer-Encoding" | "TE" | "Trailer" | "Sec-WebSocket-Key" | "Sec-WebSocket-Extensions" | "Sec-WebSocket-Accept" | "Sec-WebSocket-Protocol" | "Sec-WebSocket-Version" | "Accept-Push-Policy" | "Accept-Signature" | "Alt-Svc" | "Alt-Used" | "Date" | "Early-Data" | "Link" | "Push-Policy" | "Retry-After" | "Signature" | "Signed-Headers" | "Server-Timing" | "Service-Worker-Allowed" | "SourceMap" | "Upgrade" | "X-DNS-Prefetch-Control" | "X-Pingback" | "X-Requested-With" | "X-Robots-Tag";
+type HTTPHeaderName = _HTTPHeaderName | Lowercase<_HTTPHeaderName> | (string & {});
 
 /**
  * H3 Runtime Error
@@ -190,22 +209,22 @@ type RequestHeaders = {
  * @property {string} statusMessage - A string representing the HTTP status message.
  * @property {boolean} fatal - Indicates if the error is a fatal error.
  * @property {boolean} unhandled - Indicates if the error was unhandled and auto captured.
- * @property {any} data - An extra data that will be included in the response.
+ * @property {DataT} data - An extra data that will be included in the response.
  *                         This can be used to pass additional information about the error.
  * @property {boolean} internal - Setting this property to `true` will mark the error as an internal error.
  */
-declare class H3Error extends Error {
+declare class H3Error<DataT = unknown> extends Error {
     static __h3_error__: boolean;
     statusCode: number;
     fatal: boolean;
     unhandled: boolean;
     statusMessage?: string;
-    data?: any;
+    data?: DataT;
     cause?: unknown;
     constructor(message: string, opts?: {
         cause?: unknown;
     });
-    toJSON(): Pick<H3Error, "data" | "statusCode" | "statusMessage" | "message">;
+    toJSON(): Pick<H3Error<DataT>, "data" | "statusCode" | "statusMessage" | "message">;
 }
 /**
  * Creates a new `Error` that can be used to handle both internal and runtime errors.
@@ -213,10 +232,10 @@ declare class H3Error extends Error {
  * @param input {string | (Partial<H3Error> & { status?: number; statusText?: string })} - The error message or an object containing error properties.
  * @return {H3Error} - An instance of H3Error.
  */
-declare function createError(input: string | (Partial<H3Error> & {
+declare function createError<DataT = unknown>(input: string | (Partial<H3Error<DataT>> & {
     status?: number;
     statusText?: string;
-})): H3Error;
+})): H3Error<DataT>;
 /**
  * Receives an error and returns the corresponding response.
  * H3 internally uses this function to handle unhandled errors.
@@ -234,7 +253,7 @@ declare function sendError(event: H3Event, error: Error | H3Error, debug?: boole
  * @param input {*} - The input to check.
  * @return {boolean} - Returns true if the input is an instance of H3Error, false otherwise.
  */
-declare function isError(input: any): input is H3Error;
+declare function isError<DataT = unknown>(input: any): input is H3Error<DataT>;
 
 interface Layer {
     route: string;
@@ -276,6 +295,11 @@ declare function createApp(options?: AppOptions): App;
 declare function use(app: App, arg1: string | EventHandler | InputLayer | InputLayer[], arg2?: Partial<InputLayer> | EventHandler | EventHandler[], arg3?: Partial<InputLayer>): App;
 declare function createAppEventHandler(stack: Stack, options: AppOptions): EventHandler<EventHandlerRequest, Promise<void>>;
 
+/**
+ * Prefixes and executes a handler with a base path.
+ * @param base The base path to prefix. When set to an empty string, the handler will be run as is.
+ * @param handler The event handler to use with the adapted path.
+ */
 declare function useBase(base: string, handler: EventHandler): EventHandler;
 
 interface MultiPartData {
@@ -295,8 +319,8 @@ interface MultiPartData {
 declare function readRawBody<E extends Encoding = "utf8">(event: H3Event, encoding?: E): E extends false ? Promise<Buffer | undefined> : Promise<string | undefined>;
 /**
  * Reads request body and tries to safely parse using [destr](https://github.com/unjs/destr).
- * @param event {H3Event} H3 event passed by h3 handler
- * @param encoding {Encoding} encoding="utf-8" - The character encoding to use.
+ * @param event H3 event passed by h3 handler
+ * @param encoding The character encoding to use, defaults to 'utf-8'.
  *
  * @return {*} The `Object`, `Array`, `String`, `Number`, `Boolean`, or `null` value corresponding to the request JSON body
  *
@@ -307,12 +331,52 @@ declare function readRawBody<E extends Encoding = "utf8">(event: H3Event, encodi
 declare function readBody<T, Event extends H3Event = H3Event, _T = InferEventInput<"body", Event, T>>(event: Event, options?: {
     strict?: boolean;
 }): Promise<_T>;
+/**
+ * Tries to read the request body via `readBody`, then uses the provided validation function and either throws a validation error or returns the result.
+ * @param event The H3Event passed by the handler.
+ * @param validate The function to use for body validation. It will be called passing the read request body. If the result is not false, the parsed body will be returned.
+ * @throws If the validation function returns `false` or throws, a validation error will be thrown.
+ * @return {*} The `Object`, `Array`, `String`, `Number`, `Boolean`, or `null` value corresponding to the request JSON body.
+ * @see {readBody}
+ *
+ * ```ts
+ * // With a custom validation function
+ * const body = await readValidatedBody(event, (body) => {
+ *   return typeof body === "object" && body !== null
+ * })
+ *
+ * // With a zod schema
+ * import { z } from 'zod'
+ * const objectSchema = z.object()
+ * const body = await readValidatedBody(event, objectSchema.safeParse)
+ * ```
+ */
 declare function readValidatedBody<T, Event extends H3Event = H3Event, _T = InferEventInput<"body", Event, T>>(event: Event, validate: ValidateFunction<_T>): Promise<_T>;
+/**
+ * Tries to read and parse the body of a an H3Event as multipart form.
+ * @param event The H3Event object to read multipart form from.
+ *
+ * @return The parsed form data. If no form could be detected because the content type is not multipart/form-data or no boundary could be found.
+ *
+ * ```ts
+ * const formData = await readMultipartFormData(event)
+ * // The result could look like:
+ * // [
+ * //   {
+ * //     "data": "other",
+ * //     "name": "baz",
+ * //   },
+ * //   {
+ * //     "data": "something",
+ * //     "name": "some-other-data",
+ * //   },
+ * // ]
+ * ```
+ */
 declare function readMultipartFormData(event: H3Event): Promise<MultiPartData[] | undefined>;
 /**
- * Constructs a FormData object from an event.
- * @param event {H3Event}
- * @returns {FormData}
+ * Constructs a FormData object from an event, after converting it to a a web request.
+ * @param event The H3Event object to read the form data from.
  *
  * ```ts
  * const eventHandler = event => {
@@ -323,6 +387,11 @@ declare function readMultipartFormData(event: H3Event): Promise<MultiPartData[]
  * ```
  */
 declare function readFormData(event: H3Event): Promise<FormData>;
+/**
+ * Captures a stream from a request.
+ * @param event The H3Event object containing the request information.
+ * @returns Undefined if the request can't transport a payload, otherwise a ReadableStream of the request body.
+ */
 declare function getRequestWebStream(event: H3Event): undefined | ReadableStream;
 
 interface CacheConditions {
@@ -359,8 +428,15 @@ declare function handleCors(event: H3Event, options: H3CorsOptions): boolean;
 
 declare function getQuery<T, Event extends H3Event = H3Event, _T = Exclude<InferEventInput<"query", Event, T>, undefined>>(event: Event): _T;
 declare function getValidatedQuery<T, Event extends H3Event = H3Event, _T = InferEventInput<"query", Event, T>>(event: Event, validate: ValidateFunction<_T>): Promise<_T>;
-declare function getRouterParams(event: H3Event): NonNullable<H3Event["context"]["params"]>;
-declare function getRouterParam(event: H3Event, name: string): string | undefined;
+declare function getRouterParams(event: H3Event, opts?: {
+    decode?: boolean;
+}): NonNullable<H3Event["context"]["params"]>;
+declare function getValidatedRouterParams<T, Event extends H3Event = H3Event, _T = InferEventInput<"routerParams", Event, T>>(event: Event, validate: ValidateFunction<_T>, opts?: {
+    decode?: boolean;
+}): Promise<_T>;
+declare function getRouterParam(event: H3Event, name: string, opts?: {
+    decode?: boolean;
+}): string | undefined;
 /**
  * @deprecated Directly use `event.method` instead.
  */
@@ -369,7 +445,7 @@ declare function isMethod(event: H3Event, expected: HTTPMethod | HTTPMethod[], a
 declare function assertMethod(event: H3Event, expected: HTTPMethod | HTTPMethod[], allowHead?: boolean): void;
 declare function getRequestHeaders(event: H3Event): RequestHeaders;
 declare const getHeaders: typeof getRequestHeaders;
-declare function getRequestHeader(event: H3Event, name: string): RequestHeaders[string];
+declare function getRequestHeader(event: H3Event, name: HTTPHeaderName): RequestHeaders[string];
 declare const getHeader: typeof getRequestHeader;
 declare function getRequestHost(event: H3Event, opts?: {
     xForwardedHost?: boolean;
@@ -449,6 +525,23 @@ declare function deleteCookie(event: H3Event, name: string, serializeOptions?: C
  */
 declare function splitCookiesString(cookiesString: string | string[]): string[];
 
+interface RequestFingerprintOptions {
+    /** @default SHA-1 */
+    hash?: false | "SHA-1";
+    /** @default `true` */
+    ip?: boolean;
+    /** @default `false` */
+    xForwardedFor?: boolean;
+    /** @default `false` */
+    method?: boolean;
+    /** @default `false` */
+    path?: boolean;
+    /** @default `false` */
+    userAgent?: boolean;
+}
+/** @experimental Behavior of this utility might change in the future versions */
+declare function getRequestFingerprint(event: H3Event, opts?: RequestFingerprintOptions): Promise<string | null>;
+
 type Duplex = "half" | "full";
 interface ProxyOptions {
     headers?: RequestHeaders | HeadersInit;
@@ -488,14 +581,14 @@ declare function getResponseStatusText(event: H3Event): string;
 declare function defaultContentType(event: H3Event, type?: string): void;
 declare function sendRedirect(event: H3Event, location: string, code?: number): Promise<void>;
 declare function getResponseHeaders(event: H3Event): ReturnType<H3Event["res"]["getHeaders"]>;
-declare function getResponseHeader(event: H3Event, name: string): ReturnType<H3Event["res"]["getHeader"]>;
-declare function setResponseHeaders(event: H3Event, headers: Record<string, Parameters<OutgoingMessage["setHeader"]>[1]>): void;
+declare function getResponseHeader(event: H3Event, name: HTTPHeaderName): ReturnType<H3Event["res"]["getHeader"]>;
+declare function setResponseHeaders(event: H3Event, headers: Record<HTTPHeaderName, Parameters<OutgoingMessage["setHeader"]>[1]>): void;
 declare const setHeaders: typeof setResponseHeaders;
-declare function setResponseHeader(event: H3Event, name: string, value: Parameters<OutgoingMessage["setHeader"]>[1]): void;
+declare function setResponseHeader(event: H3Event, name: HTTPHeaderName, value: Parameters<OutgoingMessage["setHeader"]>[1]): void;
 declare const setHeader: typeof setResponseHeader;
 declare function appendResponseHeaders(event: H3Event, headers: Record<string, string>): void;
 declare const appendHeaders: typeof appendResponseHeaders;
-declare function appendResponseHeader(event: H3Event, name: string, value: string): void;
+declare function appendResponseHeader(event: H3Event, name: HTTPHeaderName, value: string): void;
 declare const appendHeader: typeof appendResponseHeader;
 /**
  * Remove all response headers, or only those specified in the headerNames array.
@@ -503,7 +596,7 @@ declare const appendHeader: typeof appendResponseHeader;
  * @param headerNames Array of header names to remove
  */
 declare function clearResponseHeaders(event: H3Event, headerNames?: string[]): void;
-declare function removeResponseHeader(event: H3Event, name: string): void;
+declare function removeResponseHeader(event: H3Event, name: HTTPHeaderName): void;
 declare function isStream(data: any): data is Readable | ReadableStream;
 declare function isWebResponse(data: any): data is Response;
 declare function sendStream(event: H3Event, stream: Readable | ReadableStream): Promise<void>;
@@ -578,4 +671,4 @@ declare function toPlainHandler(app: App): PlainHandler;
 /** @experimental */
 declare function fromPlainHandler(handler: PlainHandler): EventHandler<EventHandlerRequest, Promise<unknown>>;
 
-export { type AddRouteShortcuts, type App, type AppOptions, type AppUse, type CacheConditions, type CreateRouterOptions, type Duplex, type DynamicEventHandler, type Encoding, type EventHandler, type EventHandlerObject, type EventHandlerRequest, type EventHandlerResponse, type H3CorsOptions, H3Error, H3Event, type H3EventContext, H3Headers, H3Response, type HTTPMethod, type InferEventInput, type InputLayer, type InputStack, type Layer, type LazyEventHandler, MIMES, type Matcher, type MultiPartData, type NodeEventContext, type NodeListener, type NodeMiddleware, type NodePromisifiedHandler, type PlainHandler, type PlainRequest, type PlainResponse, type ProxyOptions, type RequestHeaders, type RouteNode, type Router, type RouterMethod, type RouterUse, type ServeStaticOptions, type Session, type SessionConfig, type SessionData, type Stack, type StaticAssetMeta, type ValidateFunction, type ValidateResult, type WebEventContext, type WebHandler, type _RequestMiddleware, type _ResponseMiddleware, appendCorsHeaders, appendCorsPreflightHeaders, appendHeader, appendHeaders, appendResponseHeader, appendResponseHeaders, assertMethod, callNodeListener, clearResponseHeaders, clearSession, createApp, createAppEventHandler, createError, createEvent, createRouter, defaultContentType, defineEventHandler, defineLazyEventHandler, defineNodeListener, defineNodeMiddleware, defineRequestMiddleware, defineResponseMiddleware, deleteCookie, dynamicEventHandler, eventHandler, fetchWithEvent, fromNodeMiddleware, fromPlainHandler, fromWebHandler, getCookie, getHeader, getHeaders, getMethod, getProxyRequestHeaders, getQuery, getRequestHeader, getRequestHeaders, getRequestHost, getRequestIP, getRequestPath, getRequestProtocol, getRequestURL, getRequestWebStream, getResponseHeader, getResponseHeaders, getResponseStatus, getResponseStatusText, getRouterParam, getRouterParams, getSession, getValidatedQuery, handleCacheHeaders, handleCors, isCorsOriginAllowed, isError, isEvent, isEventHandler, isMethod, isPreflightRequest, isStream, isWebResponse, lazyEventHandler, parseCookies, promisifyNodeListener, proxyRequest, readBody, readFormData, readMultipartFormData, readRawBody, readValidatedBody, removeResponseHeader, sanitizeStatusCode, sanitizeStatusMessage, sealSession, send, sendError, sendNoContent, sendProxy, sendRedirect, sendStream, sendWebResponse, serveStatic, setCookie, setHeader, setHeaders, setResponseHeader, setResponseHeaders, setResponseStatus, splitCookiesString, toEventHandler, toNodeListener, toPlainHandler, toWebHandler, toWebRequest, unsealSession, updateSession, use, useBase, useSession, writeEarlyHints };
+export { type AddRouteShortcuts, type App, type AppOptions, type AppUse, type CacheConditions, type CreateRouterOptions, type Duplex, type DynamicEventHandler, type Encoding, type EventHandler, type EventHandlerObject, type EventHandlerRequest, type EventHandlerResponse, type H3CorsOptions, H3Error, H3Event, type H3EventContext, H3Headers, H3Response, type HTTPHeaderName, type HTTPMethod, type InferEventInput, type InputLayer, type InputStack, type Layer, type LazyEventHandler, MIMES, type Matcher, type MultiPartData, type NodeEventContext, type NodeListener, type NodeMiddleware, type NodePromisifiedHandler, type PlainHandler, type PlainRequest, type PlainResponse, type ProxyOptions, type RequestFingerprintOptions, type RequestHeaders, type RouteNode, type Router, type RouterMethod, type RouterUse, type ServeStaticOptions, type Session, type SessionConfig, type SessionData, type Stack, type StaticAssetMeta, type ValidateFunction, type ValidateResult, type WebEventContext, type WebHandler, type _RequestMiddleware, type _ResponseMiddleware, appendCorsHeaders, appendCorsPreflightHeaders, appendHeader, appendHeaders, appendResponseHeader, appendResponseHeaders, assertMethod, callNodeListener, clearResponseHeaders, clearSession, createApp, createAppEventHandler, createError, createEvent, createRouter, defaultContentType, defineEventHandler, defineLazyEventHandler, defineNodeListener, defineNodeMiddleware, defineRequestMiddleware, defineResponseMiddleware, deleteCookie, dynamicEventHandler, eventHandler, fetchWithEvent, fromNodeMiddleware, fromPlainHandler, fromWebHandler, getCookie, getHeader, getHeaders, getMethod, getProxyRequestHeaders, getQuery, getRequestFingerprint, getRequestHeader, getRequestHeaders, getRequestHost, getRequestIP, getRequestPath, getRequestProtocol, getRequestURL, getRequestWebStream, getResponseHeader, getResponseHeaders, getResponseStatus, getResponseStatusText, getRouterParam, getRouterParams, getSession, getValidatedQuery, getValidatedRouterParams, handleCacheHeaders, handleCors, isCorsOriginAllowed, isError, isEvent, isEventHandler, isMethod, isPreflightRequest, isStream, isWebResponse, lazyEventHandler, parseCookies, promisifyNodeListener, proxyRequest, readBody, readFormData, readMultipartFormData, readRawBody, readValidatedBody, removeResponseHeader, sanitizeStatusCode, sanitizeStatusMessage, sealSession, send, sendError, sendNoContent, sendProxy, sendRedirect, sendStream, sendWebResponse, serveStatic, setCookie, setHeader, setHeaders, setResponseHeader, setResponseHeaders, setResponseStatus, splitCookiesString, toEventHandler, toNodeListener, toPlainHandler, toWebHandler, toWebRequest, unsealSession, updateSession, use, useBase, useSession, writeEarlyHints };

package/dist/index.d.ts

@@ -50,7 +50,20 @@ declare class H3Event<_RequestT extends EventHandlerRequest = EventHandlerReques
     /** @deprecated Please use `event.node.res` instead. **/
     get res(): ServerResponse<IncomingMessage>;
 }
+/**
+ * Checks if the input is an H3Event object.
+ * @param input - The input to check.
+ * @returns True if the input is an H3Event object, false otherwise.
+ * @see H3Event
+ */
 declare function isEvent(input: any): input is H3Event;
+/**
+ * Creates a new H3Event instance from the given Node.js request and response objects.
+ * @param req - The NodeIncomingMessage object.
+ * @param res - The NodeServerResponse object.
+ * @returns A new H3Event instance.
+ * @see H3Event
+ */
 declare function createEvent(req: IncomingMessage, res: ServerResponse): H3Event;
 
 declare function defineEventHandler<Request extends EventHandlerRequest = EventHandlerRequest, Response = EventHandlerResponse>(handler: EventHandler<Request, Response> | EventHandlerObject<Request, Response>): EventHandler<Request, Response>;
@@ -58,6 +71,11 @@ declare function defineEventHandler<Request = EventHandlerRequest, Response = Ev
 declare const eventHandler: typeof defineEventHandler;
 declare function defineRequestMiddleware<Request extends EventHandlerRequest = EventHandlerRequest>(fn: _RequestMiddleware<Request>): _RequestMiddleware<Request>;
 declare function defineResponseMiddleware<Request extends EventHandlerRequest = EventHandlerRequest>(fn: _ResponseMiddleware<Request>): _ResponseMiddleware<Request>;
+/**
+ * Checks if any kind of input is an event handler.
+ * @param input The input to check.
+ * @returns True if the input is an event handler, false otherwise.
+ */
 declare function isEventHandler(input: any): input is EventHandler;
 declare function toEventHandler(input: any, _?: any, _route?: string): EventHandler;
 interface DynamicEventHandler extends EventHandler {
@@ -162,6 +180,7 @@ type EventHandlerResponse<T = any> = T | Promise<T>;
 interface EventHandlerRequest {
     body?: any;
     query?: QueryObject;
+    routerParams?: Record<string, string>;
 }
 type InferEventInput<Key extends keyof EventHandlerRequest, Event extends H3Event, T> = void extends T ? (Event extends H3Event<infer E> ? E[Key] : never) : T;
 interface EventHandler<Request extends EventHandlerRequest = EventHandlerRequest, Response extends EventHandlerResponse = EventHandlerResponse> {
@@ -178,9 +197,9 @@ type EventHandlerObject<Request extends EventHandlerRequest = EventHandlerReques
     handler: EventHandler<Request, Response>;
 };
 type LazyEventHandler = () => EventHandler | Promise<EventHandler>;
-type RequestHeaders = {
-    [name: string]: string | undefined;
-};
+type RequestHeaders = Partial<Record<HTTPHeaderName, string | undefined>>;
+type _HTTPHeaderName = "WWW-Authenticate" | "Authorization" | "Proxy-Authenticate" | "Proxy-Authorization" | "Age" | "Cache-Control" | "Clear-Site-Data" | "Expires" | "Pragma" | "Accept-CH" | "Critical-CH" | "Sec-CH-UA" | "Sec-CH-UA-Arch" | "Sec-CH-UA-Bitness" | "Sec-CH-UA-Full-Version-List" | "Sec-CH-UA-Mobile" | "Sec-CH-UA-Model" | "Sec-CH-UA-Platform" | "Sec-CH-UA-Platform-Version" | "Sec-CH-UA-Prefers-Color-Scheme" | "Sec-CH-UA-Prefers-Reduced-Motion" | "Downlink" | "ECT" | "RTT" | "Save-Data" | "Last-Modified" | "ETag" | "If-Match" | "If-None-Match" | "If-Modified-Since" | "If-Unmodified-Since" | "Vary" | "Connection" | "Keep-Alive" | "Accept" | "Accept-Encoding" | "Accept-Language" | "Expect" | "Max-Forwards" | "Cookie" | "Set-Cookie" | "Access-Control-Allow-Origin" | "Access-Control-Allow-Credentials" | "Access-Control-Allow-Headers" | "Access-Control-Allow-Methods" | "Access-Control-Expose-Headers" | "Access-Control-Max-Age" | "Access-Control-Request-Headers" | "Access-Control-Request-Method" | "Origin" | "Timing-Allow-Origin" | "Content-Disposition" | "Content-Length" | "Content-Type" | "Content-Encoding" | "Content-Language" | "Content-Location" | "Forwarded" | "X-Forwarded-For" | "X-Forwarded-Host" | "X-Forwarded-Proto" | "Via" | "Location" | "Refresh" | "From" | "Host" | "Referer" | "Referrer-Policy" | "User-Agent" | "Allow" | "Server" | "Accept-Ranges" | "Range" | "If-Range" | "Content-Range" | "Cross-Origin-Embedder-Policy" | "Cross-Origin-Opener-Policy" | "Cross-Origin-Resource-Policy" | "Content-Security-Policy" | "Content-Security-Policy-Report-Only" | "Expect-CT" | "Origin-Isolation" | "Permissions-Policy" | "Strict-Transport-Security" | "Upgrade-Insecure-Requests" | "X-Content-Type-Options" | "X-Frame-Options" | "X-Permitted-Cross-Domain-Policies" | "X-Powered-By" | "X-XSS-Protection" | "Sec-Fetch-Site" | "Sec-Fetch-Mode" | "Sec-Fetch-User" | "Sec-Fetch-Dest" | "Sec-Purpose" | "Service-Worker-Navigation-Preload" | "Last-Event-ID" | "NEL" | "Ping-From" | "Ping-To" | "Report-To" | "Transfer-Encoding" | "TE" | "Trailer" | "Sec-WebSocket-Key" | "Sec-WebSocket-Extensions" | "Sec-WebSocket-Accept" | "Sec-WebSocket-Protocol" | "Sec-WebSocket-Version" | "Accept-Push-Policy" | "Accept-Signature" | "Alt-Svc" | "Alt-Used" | "Date" | "Early-Data" | "Link" | "Push-Policy" | "Retry-After" | "Signature" | "Signed-Headers" | "Server-Timing" | "Service-Worker-Allowed" | "SourceMap" | "Upgrade" | "X-DNS-Prefetch-Control" | "X-Pingback" | "X-Requested-With" | "X-Robots-Tag";
+type HTTPHeaderName = _HTTPHeaderName | Lowercase<_HTTPHeaderName> | (string & {});
 
 /**
  * H3 Runtime Error
@@ -190,22 +209,22 @@ type RequestHeaders = {
  * @property {string} statusMessage - A string representing the HTTP status message.
  * @property {boolean} fatal - Indicates if the error is a fatal error.
  * @property {boolean} unhandled - Indicates if the error was unhandled and auto captured.
- * @property {any} data - An extra data that will be included in the response.
+ * @property {DataT} data - An extra data that will be included in the response.
  *                         This can be used to pass additional information about the error.
  * @property {boolean} internal - Setting this property to `true` will mark the error as an internal error.
  */
-declare class H3Error extends Error {
+declare class H3Error<DataT = unknown> extends Error {
     static __h3_error__: boolean;
     statusCode: number;
     fatal: boolean;
     unhandled: boolean;
     statusMessage?: string;
-    data?: any;
+    data?: DataT;
     cause?: unknown;
     constructor(message: string, opts?: {
         cause?: unknown;
     });
-    toJSON(): Pick<H3Error, "data" | "statusCode" | "statusMessage" | "message">;
+    toJSON(): Pick<H3Error<DataT>, "data" | "statusCode" | "statusMessage" | "message">;
 }
 /**
  * Creates a new `Error` that can be used to handle both internal and runtime errors.
@@ -213,10 +232,10 @@ declare class H3Error extends Error {
  * @param input {string | (Partial<H3Error> & { status?: number; statusText?: string })} - The error message or an object containing error properties.
  * @return {H3Error} - An instance of H3Error.
  */
-declare function createError(input: string | (Partial<H3Error> & {
+declare function createError<DataT = unknown>(input: string | (Partial<H3Error<DataT>> & {
     status?: number;
     statusText?: string;
-})): H3Error;
+})): H3Error<DataT>;
 /**
  * Receives an error and returns the corresponding response.
  * H3 internally uses this function to handle unhandled errors.
@@ -234,7 +253,7 @@ declare function sendError(event: H3Event, error: Error | H3Error, debug?: boole
  * @param input {*} - The input to check.
  * @return {boolean} - Returns true if the input is an instance of H3Error, false otherwise.
  */
-declare function isError(input: any): input is H3Error;
+declare function isError<DataT = unknown>(input: any): input is H3Error<DataT>;
 
 interface Layer {
     route: string;
@@ -276,6 +295,11 @@ declare function createApp(options?: AppOptions): App;
 declare function use(app: App, arg1: string | EventHandler | InputLayer | InputLayer[], arg2?: Partial<InputLayer> | EventHandler | EventHandler[], arg3?: Partial<InputLayer>): App;
 declare function createAppEventHandler(stack: Stack, options: AppOptions): EventHandler<EventHandlerRequest, Promise<void>>;
 
+/**
+ * Prefixes and executes a handler with a base path.
+ * @param base The base path to prefix. When set to an empty string, the handler will be run as is.
+ * @param handler The event handler to use with the adapted path.
+ */
 declare function useBase(base: string, handler: EventHandler): EventHandler;
 
 interface MultiPartData {
@@ -295,8 +319,8 @@ interface MultiPartData {
 declare function readRawBody<E extends Encoding = "utf8">(event: H3Event, encoding?: E): E extends false ? Promise<Buffer | undefined> : Promise<string | undefined>;
 /**
  * Reads request body and tries to safely parse using [destr](https://github.com/unjs/destr).
- * @param event {H3Event} H3 event passed by h3 handler
- * @param encoding {Encoding} encoding="utf-8" - The character encoding to use.
+ * @param event H3 event passed by h3 handler
+ * @param encoding The character encoding to use, defaults to 'utf-8'.
  *
  * @return {*} The `Object`, `Array`, `String`, `Number`, `Boolean`, or `null` value corresponding to the request JSON body
  *
@@ -307,12 +331,52 @@ declare function readRawBody<E extends Encoding = "utf8">(event: H3Event, encodi
 declare function readBody<T, Event extends H3Event = H3Event, _T = InferEventInput<"body", Event, T>>(event: Event, options?: {
     strict?: boolean;
 }): Promise<_T>;
+/**
+ * Tries to read the request body via `readBody`, then uses the provided validation function and either throws a validation error or returns the result.
+ * @param event The H3Event passed by the handler.
+ * @param validate The function to use for body validation. It will be called passing the read request body. If the result is not false, the parsed body will be returned.
+ * @throws If the validation function returns `false` or throws, a validation error will be thrown.
+ * @return {*} The `Object`, `Array`, `String`, `Number`, `Boolean`, or `null` value corresponding to the request JSON body.
+ * @see {readBody}
+ *
+ * ```ts
+ * // With a custom validation function
+ * const body = await readValidatedBody(event, (body) => {
+ *   return typeof body === "object" && body !== null
+ * })
+ *
+ * // With a zod schema
+ * import { z } from 'zod'
+ * const objectSchema = z.object()
+ * const body = await readValidatedBody(event, objectSchema.safeParse)
+ * ```
+ */
 declare function readValidatedBody<T, Event extends H3Event = H3Event, _T = InferEventInput<"body", Event, T>>(event: Event, validate: ValidateFunction<_T>): Promise<_T>;
+/**
+ * Tries to read and parse the body of a an H3Event as multipart form.
+ * @param event The H3Event object to read multipart form from.
+ *
+ * @return The parsed form data. If no form could be detected because the content type is not multipart/form-data or no boundary could be found.
+ *
+ * ```ts
+ * const formData = await readMultipartFormData(event)
+ * // The result could look like:
+ * // [
+ * //   {
+ * //     "data": "other",
+ * //     "name": "baz",
+ * //   },
+ * //   {
+ * //     "data": "something",
+ * //     "name": "some-other-data",
+ * //   },
+ * // ]
+ * ```
+ */
 declare function readMultipartFormData(event: H3Event): Promise<MultiPartData[] | undefined>;
 /**
- * Constructs a FormData object from an event.
- * @param event {H3Event}
- * @returns {FormData}
+ * Constructs a FormData object from an event, after converting it to a a web request.
+ * @param event The H3Event object to read the form data from.
  *
  * ```ts
  * const eventHandler = event => {
@@ -323,6 +387,11 @@ declare function readMultipartFormData(event: H3Event): Promise<MultiPartData[]
  * ```
  */
 declare function readFormData(event: H3Event): Promise<FormData>;
+/**
+ * Captures a stream from a request.
+ * @param event The H3Event object containing the request information.
+ * @returns Undefined if the request can't transport a payload, otherwise a ReadableStream of the request body.
+ */
 declare function getRequestWebStream(event: H3Event): undefined | ReadableStream;
 
 interface CacheConditions {
@@ -359,8 +428,15 @@ declare function handleCors(event: H3Event, options: H3CorsOptions): boolean;
 
 declare function getQuery<T, Event extends H3Event = H3Event, _T = Exclude<InferEventInput<"query", Event, T>, undefined>>(event: Event): _T;
 declare function getValidatedQuery<T, Event extends H3Event = H3Event, _T = InferEventInput<"query", Event, T>>(event: Event, validate: ValidateFunction<_T>): Promise<_T>;
-declare function getRouterParams(event: H3Event): NonNullable<H3Event["context"]["params"]>;
-declare function getRouterParam(event: H3Event, name: string): string | undefined;
+declare function getRouterParams(event: H3Event, opts?: {
+    decode?: boolean;
+}): NonNullable<H3Event["context"]["params"]>;
+declare function getValidatedRouterParams<T, Event extends H3Event = H3Event, _T = InferEventInput<"routerParams", Event, T>>(event: Event, validate: ValidateFunction<_T>, opts?: {
+    decode?: boolean;
+}): Promise<_T>;
+declare function getRouterParam(event: H3Event, name: string, opts?: {
+    decode?: boolean;
+}): string | undefined;
 /**
  * @deprecated Directly use `event.method` instead.
  */
@@ -369,7 +445,7 @@ declare function isMethod(event: H3Event, expected: HTTPMethod | HTTPMethod[], a
 declare function assertMethod(event: H3Event, expected: HTTPMethod | HTTPMethod[], allowHead?: boolean): void;
 declare function getRequestHeaders(event: H3Event): RequestHeaders;
 declare const getHeaders: typeof getRequestHeaders;
-declare function getRequestHeader(event: H3Event, name: string): RequestHeaders[string];
+declare function getRequestHeader(event: H3Event, name: HTTPHeaderName): RequestHeaders[string];
 declare const getHeader: typeof getRequestHeader;
 declare function getRequestHost(event: H3Event, opts?: {
     xForwardedHost?: boolean;
@@ -449,6 +525,23 @@ declare function deleteCookie(event: H3Event, name: string, serializeOptions?: C
  */
 declare function splitCookiesString(cookiesString: string | string[]): string[];
 
+interface RequestFingerprintOptions {
+    /** @default SHA-1 */
+    hash?: false | "SHA-1";
+    /** @default `true` */
+    ip?: boolean;
+    /** @default `false` */
+    xForwardedFor?: boolean;
+    /** @default `false` */
+    method?: boolean;
+    /** @default `false` */
+    path?: boolean;
+    /** @default `false` */
+    userAgent?: boolean;
+}
+/** @experimental Behavior of this utility might change in the future versions */
+declare function getRequestFingerprint(event: H3Event, opts?: RequestFingerprintOptions): Promise<string | null>;
+
 type Duplex = "half" | "full";
 interface ProxyOptions {
     headers?: RequestHeaders | HeadersInit;
@@ -488,14 +581,14 @@ declare function getResponseStatusText(event: H3Event): string;
 declare function defaultContentType(event: H3Event, type?: string): void;
 declare function sendRedirect(event: H3Event, location: string, code?: number): Promise<void>;
 declare function getResponseHeaders(event: H3Event): ReturnType<H3Event["res"]["getHeaders"]>;
-declare function getResponseHeader(event: H3Event, name: string): ReturnType<H3Event["res"]["getHeader"]>;
-declare function setResponseHeaders(event: H3Event, headers: Record<string, Parameters<OutgoingMessage["setHeader"]>[1]>): void;
+declare function getResponseHeader(event: H3Event, name: HTTPHeaderName): ReturnType<H3Event["res"]["getHeader"]>;
+declare function setResponseHeaders(event: H3Event, headers: Record<HTTPHeaderName, Parameters<OutgoingMessage["setHeader"]>[1]>): void;
 declare const setHeaders: typeof setResponseHeaders;
-declare function setResponseHeader(event: H3Event, name: string, value: Parameters<OutgoingMessage["setHeader"]>[1]): void;
+declare function setResponseHeader(event: H3Event, name: HTTPHeaderName, value: Parameters<OutgoingMessage["setHeader"]>[1]): void;
 declare const setHeader: typeof setResponseHeader;
 declare function appendResponseHeaders(event: H3Event, headers: Record<string, string>): void;
 declare const appendHeaders: typeof appendResponseHeaders;
-declare function appendResponseHeader(event: H3Event, name: string, value: string): void;
+declare function appendResponseHeader(event: H3Event, name: HTTPHeaderName, value: string): void;
 declare const appendHeader: typeof appendResponseHeader;
 /**
  * Remove all response headers, or only those specified in the headerNames array.
@@ -503,7 +596,7 @@ declare const appendHeader: typeof appendResponseHeader;
  * @param headerNames Array of header names to remove
  */
 declare function clearResponseHeaders(event: H3Event, headerNames?: string[]): void;
-declare function removeResponseHeader(event: H3Event, name: string): void;
+declare function removeResponseHeader(event: H3Event, name: HTTPHeaderName): void;
 declare function isStream(data: any): data is Readable | ReadableStream;
 declare function isWebResponse(data: any): data is Response;
 declare function sendStream(event: H3Event, stream: Readable | ReadableStream): Promise<void>;
@@ -578,4 +671,4 @@ declare function toPlainHandler(app: App): PlainHandler;
 /** @experimental */
 declare function fromPlainHandler(handler: PlainHandler): EventHandler<EventHandlerRequest, Promise<unknown>>;
 
-export { type AddRouteShortcuts, type App, type AppOptions, type AppUse, type CacheConditions, type CreateRouterOptions, type Duplex, type DynamicEventHandler, type Encoding, type EventHandler, type EventHandlerObject, type EventHandlerRequest, type EventHandlerResponse, type H3CorsOptions, H3Error, H3Event, type H3EventContext, H3Headers, H3Response, type HTTPMethod, type InferEventInput, type InputLayer, type InputStack, type Layer, type LazyEventHandler, MIMES, type Matcher, type MultiPartData, type NodeEventContext, type NodeListener, type NodeMiddleware, type NodePromisifiedHandler, type PlainHandler, type PlainRequest, type PlainResponse, type ProxyOptions, type RequestHeaders, type RouteNode, type Router, type RouterMethod, type RouterUse, type ServeStaticOptions, type Session, type SessionConfig, type SessionData, type Stack, type StaticAssetMeta, type ValidateFunction, type ValidateResult, type WebEventContext, type WebHandler, type _RequestMiddleware, type _ResponseMiddleware, appendCorsHeaders, appendCorsPreflightHeaders, appendHeader, appendHeaders, appendResponseHeader, appendResponseHeaders, assertMethod, callNodeListener, clearResponseHeaders, clearSession, createApp, createAppEventHandler, createError, createEvent, createRouter, defaultContentType, defineEventHandler, defineLazyEventHandler, defineNodeListener, defineNodeMiddleware, defineRequestMiddleware, defineResponseMiddleware, deleteCookie, dynamicEventHandler, eventHandler, fetchWithEvent, fromNodeMiddleware, fromPlainHandler, fromWebHandler, getCookie, getHeader, getHeaders, getMethod, getProxyRequestHeaders, getQuery, getRequestHeader, getRequestHeaders, getRequestHost, getRequestIP, getRequestPath, getRequestProtocol, getRequestURL, getRequestWebStream, getResponseHeader, getResponseHeaders, getResponseStatus, getResponseStatusText, getRouterParam, getRouterParams, getSession, getValidatedQuery, handleCacheHeaders, handleCors, isCorsOriginAllowed, isError, isEvent, isEventHandler, isMethod, isPreflightRequest, isStream, isWebResponse, lazyEventHandler, parseCookies, promisifyNodeListener, proxyRequest, readBody, readFormData, readMultipartFormData, readRawBody, readValidatedBody, removeResponseHeader, sanitizeStatusCode, sanitizeStatusMessage, sealSession, send, sendError, sendNoContent, sendProxy, sendRedirect, sendStream, sendWebResponse, serveStatic, setCookie, setHeader, setHeaders, setResponseHeader, setResponseHeaders, setResponseStatus, splitCookiesString, toEventHandler, toNodeListener, toPlainHandler, toWebHandler, toWebRequest, unsealSession, updateSession, use, useBase, useSession, writeEarlyHints };
+export { type AddRouteShortcuts, type App, type AppOptions, type AppUse, type CacheConditions, type CreateRouterOptions, type Duplex, type DynamicEventHandler, type Encoding, type EventHandler, type EventHandlerObject, type EventHandlerRequest, type EventHandlerResponse, type H3CorsOptions, H3Error, H3Event, type H3EventContext, H3Headers, H3Response, type HTTPHeaderName, type HTTPMethod, type InferEventInput, type InputLayer, type InputStack, type Layer, type LazyEventHandler, MIMES, type Matcher, type MultiPartData, type NodeEventContext, type NodeListener, type NodeMiddleware, type NodePromisifiedHandler, type PlainHandler, type PlainRequest, type PlainResponse, type ProxyOptions, type RequestFingerprintOptions, type RequestHeaders, type RouteNode, type Router, type RouterMethod, type RouterUse, type ServeStaticOptions, type Session, type SessionConfig, type SessionData, type Stack, type StaticAssetMeta, type ValidateFunction, type ValidateResult, type WebEventContext, type WebHandler, type _RequestMiddleware, type _ResponseMiddleware, appendCorsHeaders, appendCorsPreflightHeaders, appendHeader, appendHeaders, appendResponseHeader, appendResponseHeaders, assertMethod, callNodeListener, clearResponseHeaders, clearSession, createApp, createAppEventHandler, createError, createEvent, createRouter, defaultContentType, defineEventHandler, defineLazyEventHandler, defineNodeListener, defineNodeMiddleware, defineRequestMiddleware, defineResponseMiddleware, deleteCookie, dynamicEventHandler, eventHandler, fetchWithEvent, fromNodeMiddleware, fromPlainHandler, fromWebHandler, getCookie, getHeader, getHeaders, getMethod, getProxyRequestHeaders, getQuery, getRequestFingerprint, getRequestHeader, getRequestHeaders, getRequestHost, getRequestIP, getRequestPath, getRequestProtocol, getRequestURL, getRequestWebStream, getResponseHeader, getResponseHeaders, getResponseStatus, getResponseStatusText, getRouterParam, getRouterParams, getSession, getValidatedQuery, getValidatedRouterParams, handleCacheHeaders, handleCors, isCorsOriginAllowed, isError, isEvent, isEventHandler, isMethod, isPreflightRequest, isStream, isWebResponse, lazyEventHandler, parseCookies, promisifyNodeListener, proxyRequest, readBody, readFormData, readMultipartFormData, readRawBody, readValidatedBody, removeResponseHeader, sanitizeStatusCode, sanitizeStatusMessage, sealSession, send, sendError, sendNoContent, sendProxy, sendRedirect, sendStream, sendWebResponse, serveStatic, setCookie, setHeader, setHeaders, setResponseHeader, setResponseHeaders, setResponseStatus, splitCookiesString, toEventHandler, toNodeListener, toPlainHandler, toWebHandler, toWebRequest, unsealSession, updateSession, use, useBase, useSession, writeEarlyHints };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { withoutTrailingSlash, withoutBase, getQuery as getQuery$1, decodePath, withLeadingSlash, parseURL } from 'ufo';
+import { withoutTrailingSlash, withoutBase, getQuery as getQuery$1, decode, decodePath, withLeadingSlash, parseURL } from 'ufo';
 import { parse as parse$1, serialize } from 'cookie-es';
 import { createRouter as createRouter$1, toRouteMatcher } from 'radix3';
 import destr from 'destr';
@@ -243,8 +243,9 @@ async function validateData(data, fn) {
 function createValidationError(validateError) {
   throw createError({
     status: 400,
-    message: validateError.message || "Validation Failed",
-    ...validateError
+    statusMessage: "Validation Error",
+    message: validateError?.message || "Validation Error",
+    data: validateError
   });
 }
 
@@ -255,11 +256,22 @@ function getValidatedQuery(event, validate) {
   const query = getQuery(event);
   return validateData(query, validate);
 }
-function getRouterParams(event) {
-  return event.context.params || {};
+function getRouterParams(event, opts = {}) {
+  let params = event.context.params || {};
+  if (opts.decode) {
+    params = { ...params };
+    for (const key in params) {
+      params[key] = decode(params[key]);
+    }
+  }
+  return params;
 }
-function getRouterParam(event, name) {
-  const params = getRouterParams(event);
+function getValidatedRouterParams(event, validate, opts = {}) {
+  const routerParams = getRouterParams(event, opts);
+  return validateData(routerParams, validate);
+}
+function getRouterParam(event, name, opts = {}) {
+  const params = getRouterParams(event, opts);
   return params[name];
 }
 function getMethod(event, defaultMethod = "GET") {
@@ -359,7 +371,7 @@ const ParsedBodySymbol = Symbol.for("h3ParsedBody");
 const PayloadMethods$1 = ["PATCH", "POST", "PUT", "DELETE"];
 function readRawBody(event, encoding = "utf8") {
   assertMethod(event, PayloadMethods$1);
-  const _rawBody = event._requestBody || event.web?.request?.body || event.node.req[RawBodySymbol] || event.node.req.body;
+  const _rawBody = event._requestBody || event.web?.request?.body || event.node.req[RawBodySymbol] || event.node.req.rawBody || event.node.req.body;
   if (_rawBody) {
     const promise2 = Promise.resolve(_rawBody).then((_resolved) => {
       if (Buffer.isBuffer(_resolved)) {
@@ -661,6 +673,9 @@ function sendNoContent(event, code) {
   if (event.handled) {
     return;
   }
+  if (!code && event.node.res.statusCode !== 200) {
+    code = event.node.res.statusCode;
+  }
   const _code = sanitizeStatusCode(code, 204);
   if (_code === 204) {
     event.node.res.removeHeader("content-length");
@@ -993,6 +1008,37 @@ function handleCors(event, options) {
   return false;
 }
 
+async function getRequestFingerprint(event, opts = {}) {
+  const fingerprint = [];
+  if (opts.ip !== false) {
+    fingerprint.push(
+      getRequestIP(event, { xForwardedFor: opts.xForwardedFor })
+    );
+  }
+  if (opts.method === true) {
+    fingerprint.push(event.method);
+  }
+  if (opts.path === true) {
+    fingerprint.push(event.path);
+  }
+  if (opts.userAgent === true) {
+    fingerprint.push(getRequestHeader(event, "user-agent"));
+  }
+  const fingerprintString = fingerprint.filter(Boolean).join("|");
+  if (!fingerprintString) {
+    return null;
+  }
+  if (opts.hash === false) {
+    return fingerprintString;
+  }
+  const buffer = await crypto.subtle.digest(
+    opts.hash || "SHA-1",
+    new TextEncoder().encode(fingerprintString)
+  );
+  const hash = [...new Uint8Array(buffer)].map((b) => b.toString(16).padStart(2, "0")).join("");
+  return hash;
+}
+
 const PayloadMethods = /* @__PURE__ */ new Set(["PATCH", "POST", "PUT", "DELETE"]);
 const ignoredHeaders = /* @__PURE__ */ new Set([
   "transfer-encoding",
@@ -2012,4 +2058,4 @@ async function _handleWebRequest(app, request, context) {
   });
 }
 
-export { H3Error, H3Event, H3Headers, H3Response, MIMES, appendCorsHeaders, appendCorsPreflightHeaders, appendHeader, appendHeaders, appendResponseHeader, appendResponseHeaders, assertMethod, callNodeListener, clearResponseHeaders, clearSession, createApp, createAppEventHandler, createError, createEvent, createRouter, defaultContentType, defineEventHandler, defineLazyEventHandler, defineNodeListener, defineNodeMiddleware, defineRequestMiddleware, defineResponseMiddleware, deleteCookie, dynamicEventHandler, eventHandler, fetchWithEvent, fromNodeMiddleware, fromPlainHandler, fromWebHandler, getCookie, getHeader, getHeaders, getMethod, getProxyRequestHeaders, getQuery, getRequestHeader, getRequestHeaders, getRequestHost, getRequestIP, getRequestPath, getRequestProtocol, getRequestURL, getRequestWebStream, getResponseHeader, getResponseHeaders, getResponseStatus, getResponseStatusText, getRouterParam, getRouterParams, getSession, getValidatedQuery, handleCacheHeaders, handleCors, isCorsOriginAllowed, isError, isEvent, isEventHandler, isMethod, isPreflightRequest, isStream, isWebResponse, lazyEventHandler, parseCookies, promisifyNodeListener, proxyRequest, readBody, readFormData, readMultipartFormData, readRawBody, readValidatedBody, removeResponseHeader, sanitizeStatusCode, sanitizeStatusMessage, sealSession, send, sendError, sendNoContent, sendProxy, sendRedirect, sendStream, sendWebResponse, serveStatic, setCookie, setHeader, setHeaders, setResponseHeader, setResponseHeaders, setResponseStatus, splitCookiesString, toEventHandler, toNodeListener, toPlainHandler, toWebHandler, toWebRequest, unsealSession, updateSession, use, useBase, useSession, writeEarlyHints };
+export { H3Error, H3Event, H3Headers, H3Response, MIMES, appendCorsHeaders, appendCorsPreflightHeaders, appendHeader, appendHeaders, appendResponseHeader, appendResponseHeaders, assertMethod, callNodeListener, clearResponseHeaders, clearSession, createApp, createAppEventHandler, createError, createEvent, createRouter, defaultContentType, defineEventHandler, defineLazyEventHandler, defineNodeListener, defineNodeMiddleware, defineRequestMiddleware, defineResponseMiddleware, deleteCookie, dynamicEventHandler, eventHandler, fetchWithEvent, fromNodeMiddleware, fromPlainHandler, fromWebHandler, getCookie, getHeader, getHeaders, getMethod, getProxyRequestHeaders, getQuery, getRequestFingerprint, getRequestHeader, getRequestHeaders, getRequestHost, getRequestIP, getRequestPath, getRequestProtocol, getRequestURL, getRequestWebStream, getResponseHeader, getResponseHeaders, getResponseStatus, getResponseStatusText, getRouterParam, getRouterParams, getSession, getValidatedQuery, getValidatedRouterParams, handleCacheHeaders, handleCors, isCorsOriginAllowed, isError, isEvent, isEventHandler, isMethod, isPreflightRequest, isStream, isWebResponse, lazyEventHandler, parseCookies, promisifyNodeListener, proxyRequest, readBody, readFormData, readMultipartFormData, readRawBody, readValidatedBody, removeResponseHeader, sanitizeStatusCode, sanitizeStatusMessage, sealSession, send, sendError, sendNoContent, sendProxy, sendRedirect, sendStream, sendWebResponse, serveStatic, setCookie, setHeader, setHeaders, setResponseHeader, setResponseHeaders, setResponseStatus, splitCookiesString, toEventHandler, toNodeListener, toPlainHandler, toWebHandler, toWebRequest, unsealSession, updateSession, use, useBase, useSession, writeEarlyHints };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "h3",
-  "version": "1.8.2",
+  "version": "1.10.0",
   "description": "Minimal H(TTP) framework built for high performance and portability.",
   "repository": "unjs/h3",
   "license": "MIT",
@@ -21,50 +21,49 @@
   ],
   "dependencies": {
     "cookie-es": "^1.0.0",
-    "defu": "^6.1.2",
-    "destr": "^2.0.1",
-    "iron-webcrypto": "^0.10.1",
+    "defu": "^6.1.3",
+    "destr": "^2.0.2",
+    "iron-webcrypto": "^1.0.0",
     "radix3": "^1.1.0",
-    "ufo": "^1.3.0",
+    "ufo": "^1.3.2",
     "uncrypto": "^0.1.3",
-    "unenv": "^1.7.4"
+    "unenv": "^1.8.0"
   },
   "devDependencies": {
     "0x": "^5.7.0",
-    "@types/express": "^4.17.18",
-    "@types/node": "^20.7.0",
-    "@types/supertest": "^2.0.13",
-    "@vitest/coverage-v8": "^0.34.5",
-    "autocannon": "^7.12.0",
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.10.4",
+    "@types/supertest": "^6.0.2",
+    "@vitest/coverage-v8": "^1.0.2",
+    "autocannon": "^7.14.0",
     "changelogen": "^0.5.5",
     "connect": "^3.7.0",
-    "eslint": "^8.50.0",
+    "eslint": "^8.55.0",
     "eslint-config-unjs": "^0.2.1",
     "express": "^4.18.2",
     "get-port": "^7.0.0",
-    "jiti": "^1.20.0",
+    "jiti": "^1.21.0",
     "listhen": "^1.5.5",
-    "node-fetch-native": "^1.4.0",
-    "prettier": "^3.0.3",
+    "node-fetch-native": "^1.4.1",
+    "prettier": "^3.1.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "supertest": "^6.3.3",
-    "typescript": "^5.2.2",
+    "typescript": "^5.3.3",
     "unbuild": "^2.0.0",
-    "vitest": "^0.34.5",
-    "zod": "^3.22.2"
+    "vitest": "^1.0.2",
+    "zod": "^3.22.4"
   },
-  "packageManager": "pnpm@8.8.0",
+  "packageManager": "pnpm@8.11.0",
   "scripts": {
     "build": "unbuild",
     "dev": "vitest",
-    "lint": "eslint --cache --ext .ts,.js,.mjs,.cjs . && prettier -c src test playground",
-    "lint:fix": "eslint --cache --ext .ts,.js,.mjs,.cjs . --fix && prettier -c src test playground -w",
+    "lint": "eslint --cache --ext .ts,.js,.mjs,.cjs . && prettier -c src test playground examples",
+    "lint:fix": "eslint --cache --ext .ts,.js,.mjs,.cjs . --fix && prettier -c src test playground examples -w",
     "play": "listhen -w ./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",
     "release-rc": "pnpm test && pnpm build && changelogen --release --prerelease rc --push --publish --publishTag rc",
-    "test": "pnpm lint && vitest --run typecheck && vitest --run --coverage",
-    "test:types": "vitest typecheck"
+    "test": "pnpm lint && vitest --run --coverage"
   }
 }