h3 2.0.1-rc.2 → 2.0.1-rc.21

package/dist/docs/0.guide/1.basics/3.handler.md

@@ -0,0 +1,165 @@
+# Event Handlers
+
+> An event handler is a function that receives an H3Event and returns a response.
+
+You can define typed event handlers using `defineHandler`.
+
+```js
+import { H3, defineHandler } from "h3";
+
+const app = new H3();
+
+const handler = defineHandler((event) => "Response");
+
+app.get("/", handler);
+```
+
+> [!NOTE]
+> Using `defineHandler` is optional.
+> You can instead, simply use a function that accepts an [`H3Event`](/guide/api/h3event) and returns a response.
+
+The callback function can be sync or async:
+
+```js
+defineHandler(async (event) => "Response");
+```
+
+## Object Syntax
+
+### middleware
+
+You can optionally register some [middleware](/guide/basics/middleware) to run with event handler to intercept request, response or errors.
+
+```js
+import { basicAuth } from "h3";
+
+defineHandler({
+  middleware: [basicAuth({ password: "test" })],
+  handler: (event) => "Hi!",
+});
+```
+
+<read-more></read-more>
+
+<read-more></read-more>
+
+### meta
+
+You can define optional route meta attached to handlers, and access them from any other middleware.
+
+```js
+import { H3, defineHandler } from "h3";
+
+const app = new H3();
+
+app.use((event) => {
+  console.log(event.context.matchedRoute?.meta); // { tag: "admin" }
+});
+
+app.get("/admin/**", defineHandler({
+  meta: { tag: "admin" },
+  handler: (event) => "Hi!",
+})
+```
+
+<read-more>
+
+It is also possible to add route meta when registering them to app instance.
+</read-more>
+
+## Handler `.fetch`
+
+Event handlers defined with `defineHandler`, can act as a web handler without even using [H3](/guide/api/h3) class.
+
+```js
+const handler = defineHandler(async (event) => `Request: ${event.req.url}`);
+
+const response = await handler.fetch("http://localhost/");
+console.log(response, await response.text());
+```
+
+## Lazy Handlers
+
+You can define lazy event handlers using `defineLazyEventHandler`. This allow you to define some one-time logic that will be executed only once when the first request matching the route is received.
+
+A lazy event handler must return an event handler.
+
+```js
+import { defineLazyEventHandler } from "h3";
+
+defineLazyEventHandler(async () => {
+  await initSomething(); // Will be executed only once
+  return (event) => {
+    return "Response";
+  };
+});
+```
+
+This is useful to define some one-time logic such as configuration, class initialization, heavy computation, etc.
+
+Another use-case is lazy loading route chunks:
+
+```js [app.mjs]
+import { H3, defineLazyEventHandler } from "h3";
+
+const app = new H3();
+
+app.all(
+  "/route",
+  defineLazyEventHandler(() => import("./route.mjs").then((mod) => mod.default)),
+);
+```
+
+```js [route.mjs]
+import { defineHandler } from "h3";
+
+export default defineHandler((event) => "Hello!");
+```
+
+## Converting to Handler
+
+There are situations that you might want to convert an event handler or utility made for Node.js or another framework to H3.
+There are built-in utils to do this.
+
+### From Web Handlers
+
+Request handlers with [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) => [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) signuture can be converted into H3 event handlers using `fromWebHandler` utility or [H3.mount](/guide/api/h3#h3mount).
+
+```js
+import { H3, fromWebHandler } from "h3";
+
+export const app = new H3();
+
+const webHandler = (request) => new Response("👋 Hello!");
+
+// Using fromWebHandler utiliy
+app.all("/web", fromWebHandler(webHandler));
+
+// Using simple wrapper
+app.all("/web", (event) => webHandler(event.req));
+
+// Using app.mount
+app.mount("/web", webHandler);
+```
+
+### From Node.js Handlers
+
+If you have a legacy request handler with `(req, res) => {}` syntax made for Node.js, you can use `fromNodeHandler` to convert it to an h3 event handler.
+
+> [!IMPORTANT]
+> Node.js event handlers can only run within Node.js server runtime!
+
+```js
+import { H3, fromNodeHandler } from "h3";
+
+// Force using Node.js compatibility (also works with Bun and Deno)
+import { serve } from "h3/node";
+
+export const app = new H3();
+
+const nodeHandler = (req, res) => {
+  res.end("Node handlers work!");
+};
+
+app.get("/web", fromNodeHandler(nodeHandler));
+```

package/dist/docs/0.guide/1.basics/4.response.md

@@ -0,0 +1,162 @@
+# Sending Response
+
+> H3 automatically converts any returned value into a web response.
+
+Values returned from [Event Handlers](/guide/basics/handler) are automatically converted to a web [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) by H3.
+
+**Example:** Simple event handler function.
+
+```js
+const handler = defineHandler((event) => ({ hello: "world" }));
+```
+
+H3 smartly converts handler into:
+
+```js
+const handler = (event) =>
+  new Response(JSON.stringify({ hello: "world" }), {
+    headers: {
+      "content-type": "application/json;charset=UTF-8",
+    },
+  });
+```
+
+> [!TIP]
+> 🚀 H3 uses srvx `FastResponse` internally to optimize performances in Node.js runtime.
+
+If the returned value from event handler is a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) or from an [async function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function), H3 will wait for it to resolve before sending the response.
+
+If an error is thrown, H3 automatically handles it with error handler.
+
+<read-more></read-more>
+
+## Preparing Response
+
+Before returning a response in main handler, you can prepare response headers and status using [`event.res`](/guide/api/h3event#eventres).
+
+```js
+defineHandler((event) => {
+  event.res.status = 200;
+  event.res.statusText = "OK";
+  event.res.headers.set("Content-Type", "text/html");
+  return "<h1>Hello, World</h1>";
+});
+```
+
+> [!NOTE]
+> If a full [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response/Response) value is returned, prepared status is discarded and headers will be merged/overriden. For performance reasons, it is best to only set headers only from final Response in this case.
+
+> [!NOTE]
+> If an Error happens, prepared status and headers will be discarded. The recommended way to include headers in error responses is via `new HTTPError({ headers })`. As a last resort for headers that need to be set implicitly before the error is known (e.g., CORS), you can use `event.res.errHeaders` — these will be merged into error responses automatically.
+
+## Response Types
+
+H3 smartly converts JavaScript values into web [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response/Response).
+
+### JSON Serializable Value
+
+Returning a [JSON](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON) serializable value (**object**, **array**, **number** or **boolean**), it will be stringified using [JSON.stringify()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) and sent with default `application/json` content-type.
+
+**Example:**
+
+```ts
+app.get("/", (event) => ({ hello: "world" }));
+```
+
+> [!TIP]
+> Returned objects with `.toJSON()` property can customize serialization behavior. Check [MDN docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) for more info.
+
+### String
+
+Returning a string value, sends it as plain text body.
+
+> [!NOTE]
+> If not setting `content-type` header, it can default to `text/plain;charset=UTF-8`.
+
+**Example:** Send HTML response.
+
+```ts
+app.get("/", (event) => {
+  event.res.headers.set("Content-Type", "text/html;charset=UTF-8");
+  return "<h1>hello world</h1>";
+});
+```
+
+You can also use `html` utility as shortcut.
+
+```js
+import { html } from "h3";
+
+app.get("/", () => html("<h1>hello world</h1>"));
+```
+
+### `Response`
+
+Returning a web [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response/Response), sends-it as final reponse.
+
+**Example:**
+
+```ts
+app.get("/", (event) => new Response("Hello, world!", { headers: { "x-powered-by": "H3" } }));
+```
+
+> [!IMPORTANT]
+> When sending a `Response`, any [prepared headers](#preparing-response) that set before, will be merged as default headers. `event.res.{status,statusText}` will be ignored. For performance reasons, it is best to only set headers only from final `Response`.
+
+### `ReadableStream` or `Readable`
+
+Returning a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or Node.js [`Readable`](https://nodejs.org/api/stream.html#readable-streams) sends it as stream.
+
+### `ArrayBuffer` or `Uint8Array` or `Buffer`
+
+Send binary [ArrayBuffer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer), [Uint8Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) or node [Buffer](https://nodejs.org/api/buffer.html#buffer).
+
+`content-length` header will be automatically set.
+
+### `Blob`
+
+Send a [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) as stream.
+
+`Content-type` and `Content-Length` headers will be automatically set.
+
+### `File`
+
+Send a [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File) as stream.
+
+`Content-type`, `Content-Length` and `Content-Disposition` headers will be automatically set.
+
+## Special Types
+
+Some less commonly possible values for response types.
+
+### `null` or `undefined`
+
+Sends a response with empty body.
+
+> [!TIP]
+> If there is no `return` statement in event handler, it is same as `return undefined`.
+
+### `Error`
+
+Retuning an [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) instance will send it.
+
+> [!IMPORTANT]
+> It is better to `throw` errors instead of returning them. This allows proper propagation from any nested utility.
+
+<read-more></read-more>
+
+### `BigInt`
+
+Value will be sent as stringified version of BigInt number.
+
+> [!NOTE]
+> Returning a JSON object, does not allows BigInt serialization. You need to implement `.toJSON`. Check [MDN docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) for more info.
+
+### `Symbol` or `Function`
+
+**Returning Symbol or Function has undetermined behavior.** Currently, H3 sends a string-like representation of unknown Symbols and Functions but this behavior might be changed to throw an error in the future versions.
+
+There are some internal known Symbols H3 internally uses:
+
+- `Symbol.for("h3.notFound")`: Indicate no route is found to throw a 404 error.
+- `Symbol.for("h3.handled")`: Indicate request is somehow handled and H3 should not continue (Node.js specific).

package/dist/docs/0.guide/1.basics/5.error.md

@@ -0,0 +1,117 @@
+# Error Handling
+
+> Send errors by throwing an HTTPError.
+
+H3 captures all possible errors during [request lifecycle](/guide/basics/lifecycle).
+
+## `HTTPError`
+
+You can create and throw HTTP errors using `HTTPError` with different syntaxes.
+
+```js
+import { HTTPError } from "h3";
+
+app.get("/error", (event) => {
+  // Using message and details
+  throw new HTTPError("Invalid user input", { status: 400 });
+
+  // Using HTTPError.status(code)
+  throw HTTPError.status(400, "Bad Request");
+
+  // Using single object
+  throw new HTTPError({
+    status: 400,
+    statusText: "Bad Request",
+    message: "Invalid user input",
+    data: { field: "email" },
+    body: { date: new Date().toJSON() },
+    headers: {},
+  });
+});
+```
+
+This will end the request with `400 - Bad Request` status code and the following JSON response:
+
+```json
+{
+  "date": "2025-06-05T04:20:00.0Z",
+  "status": 400,
+  "statusText": "Bad Request",
+  "message": "Invalid user input",
+  "data": {
+    "field": "email"
+  }
+}
+```
+
+### `HTTPError` Fields
+
+- `status`: HTTP status code in the range 200–599.
+- `statusText`: HTTP status text to be sent in the response header.
+- `message`: Error message to be included in the JSON body.
+- `data`: Additional data to be attached under the `data` key in the error JSON body.
+- `body`: Additional top-level properties to be attached in the error JSON body.
+- `headers`: Additional HTTP headers to be sent in the error response.
+- `cause`: The original error object that caused this error, useful for tracing and debugging.
+- `unhandled`: Indicates whether the error was thrown for unknown reasons. See [Unhandled Errors](#unhandled-errors).
+
+> [!TIP]
+The recommended way to include headers in error responses is to use `new HTTPError({ headers })`:
+
+> ```js
+> throw new HTTPError({
+>   status: 400,
+>   message: "Invalid input",
+>   headers: { "x-request-id": requestId },
+> });
+> ```
+
+> When an error is thrown, any [prepared headers](/guide/basics/response#preparing-response) set via `event.res.headers` are **not** included in the error response. As a last resort for headers that need to be set implicitly before the error is known (e.g., CORS headers), you can use `event.res.errHeaders`. Built-in utilities like `handleCors` automatically set both.
+
+> [!IMPORTANT]
+> Error `statusText` should be short (max 512 to 1024 characters) and only include tab, spaces or visible ASCII characters and extended characters (byte value 128–255). Prefer `message` in JSON body for extended message.
+
+## Unhandled Errors
+
+Any error that occurs during calling [request lifecycle](/guide/basics/lifecycle) without using `HTTPError` will be processed as an <u>unhandled</u> error.
+
+```js
+app.get("/error", (event) => {
+  // This will cause an unhandled error.
+  throw new Error("Something went wrong");
+});
+```
+
+> [!TIP]
+> For enhanced security, H3 hides certain fields of unhandled errors (`data`, `body`, `stack` and `message`) in JSON response.
+
+## Catching Errors
+
+Using global [`onError`](/guide/api/h3#global-hooks) hook:
+
+```js
+import { H3, onError } from "h3";
+
+// Globally handling errors
+const app = new H3({
+  onError: (error) => {
+    console.error(error);
+  },
+});
+```
+
+Using [`onError` middleware](/guide/basics/middleware) to catch errors.
+
+```js
+import { onError } from "h3";
+
+// Handling errors using middleware
+app.use(
+  onError((error, event) => {
+    console.error(error);
+  }),
+);
+```
+
+> [!TIP]
+> When using nested apps, global hooks of sub-apps will not be called. Therefore it is better to use `onError` middleware.

package/dist/docs/0.guide/1.basics/6.nested-apps.md

@@ -0,0 +1,57 @@
+# Nested Apps
+
+> H3 has a native `mount` method for adding nested sub-apps to the main instance.
+
+Typically, H3 projects consist of several [Event Handlers](/guide/basics/handler) defined in one or multiple files (or even [lazy loaded](/guide/basics/handler#lazy-handlers) for faster startup times).
+
+It is sometimes more convenient to combine multiple `H3` instances or even use another HTTP framework used by a different team and mount it to the main app instance. H3 provides a native [`.mount`](/guide/api/h3#h3mount) method to facilitate this.
+
+## Nested H3 Apps
+
+H3 natively allows mounting sub-apps. When mounted, sub-app routes and middleware are **merged** with the base url prefix into the main app instance.
+
+```js
+import { H3, serve } from "h3";
+
+const nestedApp = new H3()
+  .use((event) => {
+    event.res.headers.set("x-api", "1");
+  })
+  .get("/**:slug", (event) => ({
+    pathname: event.url.pathname,
+    slug: event.context.params?.slug,
+  }));
+
+const app = new H3().mount("/api", nestedApp);
+```
+
+In the example above, when fetching the `/api/test` URL, `pathname` will be `/api/test` (the real path), and `slug` will be `/test` (wildcard param).
+
+> [!NOTE]
+> Global config and hooks won't be inherited from the nested app. Consider always setting them from the main app.
+
+## Nested Web Standard Apps
+
+Mount a `.fetch` compatible server instance like [Hono](https://hono.dev/) or [Elysia](https://elysiajs.com/) under the base URL.
+
+> [!NOTE]
+> Base prefix will be removed from `request.url` passed to the mounted app.
+
+```js
+import { H3 } from "h3";
+import { Hono } from "hono";
+import { Elysia } from "elysia";
+
+const app = new H3()
+  .mount(
+    "/elysia",
+    new Elysia().get("/test", () => "Hello Elysia!"),
+  )
+  .mount(
+    "/hono",
+    new Hono().get("/test", (c) => c.text("Hello Hono!")),
+  );
+```
+
+> [!TIP]
+> Similarly, you can mount an H3 app in [Hono](https://hono.dev/docs/api/hono#mount) or [Elysia](https://elysiajs.com/patterns/mount#mount-1).

package/dist/docs/0.guide/2.api/0.h3.md

@@ -0,0 +1,145 @@
+# H3
+
+> H3 class is the core of server.
+
+You can create a new H3 app instance using `new H3()`:
+
+```js
+import { H3 } from "h3";
+
+const app = new H3({
+  /* optional config */
+});
+```
+
+## `H3` Methods
+
+### `H3.request`
+
+A [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)-compatible function allowing to fetch app routes.
+
+- Input can be a relative path, [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL), or [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request).
+- Returned value is a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) promise.
+
+```ts
+const response = await app.request("/");
+console.log(response, await response.text());
+```
+
+### `H3.fetch`
+Similar to `H3.request` but only accepts one `(req: Request)` argument for cross runtime compatibility.
+
+### `H3.on`
+
+Register route handler for specific HTTP method.
+
+```js
+const app = new H3().on("GET", "/", () => "OK");
+```
+
+<read-more></read-more>
+
+### `H3.[method]`
+
+Register route handler for specific HTTP method (shortcut for `app.on(method, ...)`).
+
+```js
+const app = new H3().get("/", () => "OK");
+```
+
+### `H3.all`
+
+Register route handler for all HTTP methods.
+
+```js
+const app = new H3().all("/", () => "OK");
+```
+
+### `H3.use`
+
+Register a global [middleware](/guide/basics/middleware).
+
+```js
+const app = new H3()
+  .use((event) => {
+    console.log(`request: ${event.req.url}`);
+  })
+  .all("/", () => "OK");
+```
+
+<read-more></read-more>
+
+### `H3.register`
+
+Register a H3 plugin to extend app.
+
+<read-more></read-more>
+
+### `H3.handler`
+
+An H3 [event handler](/guide/basics/handler) useful to compose multiple H3 app instances.
+
+**Example:** Nested apps.
+
+```js
+import { H3, serve, redirect, withBase } from "h3";
+
+const nestedApp = new H3().get("/test", () => "/test (sub app)");
+
+const app = new H3()
+  .get("/", (event) => redirect(event, "/api/test"))
+  .all("/api/**", withBase("/api", nestedApp.handler));
+
+serve(app);
+```
+
+### `H3.mount`
+
+Using `.mount` method, you can register a sub-app with prefix.
+
+<read-more></read-more>
+
+## `H3` Options
+
+You can pass global app configuration when initializing an app.
+
+Supported options:
+
+- `debug`: Displays debugging stack traces in HTTP responses (potentially dangerous for production!).
+- `silent`: When enabled, console errors for unhandled exceptions will not be displayed.
+- `plugins`: (see [plugins](/guide/advanced/plugins) for more information)
+
+> [!IMPORTANT]
+Enabling `debug` option, sends important stuff like stack traces in error responses. Only enable during development.
+
+### Global Hooks
+
+When initializing an H3 app, you can register global hooks:
+
+- `onError`
+- `onRequest`
+- `onResponse`
+These hooks are called for every request and can be used to add global logic to your app such as logging, error handling, etc.
+
+```js
+const app = new H3({
+  onRequest: (event) => {
+    console.log("Request:", event.req.url);
+  },
+  onResponse: (response, event) => {
+    console.log("Response:", event.url.pathname, response.status);
+  },
+  onError: (error, event) => {
+    console.error(error);
+  },
+});
+```
+
+> [!IMPORTANT]
+> Global hooks only run from main H3 app and **not** sub-apps. Use [middleware](/guide/basics/middleware) for more flexibility.
+
+## `H3` Properties
+
+### `H3.config`
+
+Global H3 instance config.