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

package/dist/docs/0.guide/2.api/1.h3event.md

@@ -0,0 +1,113 @@
+# H3Event
+
+> H3Event, carries incoming request, prepared response and context.
+
+With each HTTP request, H3 internally creates an `H3Event` object and passes it though event handlers until sending the response.
+
+<read-more></read-more>
+
+An event is passed through all the lifecycle hooks and composable utils to use it as context.
+
+**Example:**
+
+```js
+app.get("/", async (event) => {
+  // Log HTTP request
+  console.log(`[${event.req.method}] ${event.req.url}`);
+
+  // Parsed URL and query params
+  const searchParams = event.url.searchParams;
+
+  // Try to read request JSON body
+  const jsonBody = await event.req.json().catch(() => {});
+
+  return "OK";
+});
+```
+
+## `H3Event` Methods
+
+### `H3Event.waitUntil`
+
+Tell the runtime about an ongoing operation that shouldn't close until the promise resolves.
+
+```js [app.mjs]
+import { logRequest } from "./tracing.mjs";
+
+app.get("/", (event) => {
+  request.waitUntil(logRequest(request));
+  return "OK";
+});
+```
+
+```js [tracing.mjs]
+export async function logRequest(request) {
+  await fetch("https://telemetry.example.com", {
+    method: "POST",
+    body: JSON.stringify({
+      method: request.method,
+      url: request.url,
+      ip: request.ip,
+    }),
+  });
+}
+```
+
+## `H3Event` Properties
+
+### `H3Event.app?`
+
+Access to the H3 [application instance](/guide/api/h3).
+
+### `H3Event.context`
+
+The context is an object that contains arbitrary information about the request.
+
+You can store your custom properties inside `event.context` to share across utils.
+
+**Known context keys:**
+
+- `context.params`: Matched router parameters.
+- `middlewareParams`: Matched middleware parameters
+- `matchedRoute`: Matched router route object.
+- `sessions`: Cached session data.
+- `basicAuth`: Basic authentication data.
+
+### `H3Event.req`
+Incoming HTTP request info based on native [Web Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) with additional runtime addons (see [srvx docs](https://srvx.h3.dev/guide/handler#extended-request-context)).
+
+```ts
+app.get("/", async (event) => {
+  const url = event.req.url;
+  const method = event.req.method;
+  const headers = event.req.headers;
+
+  // (note: you can consume body only once with either of this)
+  const bodyStream = await event.req.body;
+  const textBody = await event.req.text();
+  const jsonBody = await event.req.json();
+  const formDataBody = await event.req.formData();
+
+  return "OK";
+});
+```
+
+### `H3Event.url`
+
+Access to the full parsed request [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL).
+
+### `H3Event.res`
+
+Prepared HTTP response status and headers.
+
+```ts
+app.get("/", (event) => {
+  event.res.status = 200;
+  event.res.statusText = "OK";
+  event.res.headers.set("x-test", "works");
+
+  return "OK";
+});
+```
+
+<read-more></read-more>

package/dist/docs/0.guide/3.advanced/0.plugins.md

@@ -0,0 +1,50 @@
+# Plugins
+
+> H3 plugins allow you to extend an H3 app instance with reusable logic.
+
+## Register Plugins
+
+Plugins can be registered either when creating a new [H3 instance](/guide/api/h3) or by using [H3.register](/guide/api/h3#h3register).
+
+```js
+import { H3 } from "h3";
+import { logger } from "./logger.mjs";
+
+// Using instance config
+const app = new H3({
+  plugins: [logger()],
+});
+
+// Or register later
+app.register(logger());
+
+// ... rest of the code..
+app.get("/**", () => "Hello, World!");
+```
+
+> [!NOTE]
+> Plugins are always registered immediately. Therefore, the order in which they are used might be important depending on the plugin's functionality.
+
+## Creating Plugins
+
+H3 plugins are simply functions that accept an [H3 instance](/guide/api/h3) as the first argument and immediately apply logic to extend it.
+
+```js
+app.register((app) => {
+  app.use(...)
+})
+```
+
+For convenience, H3 provides a built-in `definePlugin` utility, which creates a typed factory function with optional plugin-specific options.
+
+```js
+import { definePlugin } from "h3";
+
+const logger = definePlugin((h3, _options) => {
+  if (h3.config.debug) {
+    h3.use((req) => {
+      console.log(`[${req.method}] ${req.url}`);
+    });
+  }
+});
+```

package/dist/docs/0.guide/3.advanced/1.websocket.md

@@ -0,0 +1,124 @@
+# WebSockets
+
+> H3 has built-in utilities for cross platform WebSocket and Server-Sent Events.
+
+You can add cross platform WebSocket support to H3 servers using [🔌 CrossWS](https://crossws.h3.dev/).
+
+> [!IMPORTANT]
+> Built-in support of WebSockets in h3 version is WIP.
+
+## Usage
+
+WebSocket handlers can be defined using the `defineWebSocketHandler()` utility and registered to any route like event handlers.
+
+You need to register CrossWS as a server plugin in the `serve` function and provide a `resolve` function to resolve the correct hooks from the route.
+
+```js
+import { H3, serve, defineWebSocketHandler } from "h3";
+
+import { plugin as ws } from "crossws/server";
+
+const app = new H3();
+
+app.get("/_ws", defineWebSocketHandler({ message: console.log }));
+
+serve(app, {
+  plugins: [ws({ resolve: async (req) => (await app.fetch(req)).crossws })],
+});
+```
+
+**Full example:**
+
+```js [websocket.mjs]
+import { H3, serve, defineWebSocketHandler } from "h3";
+import { plugin as ws } from "crossws/server";
+
+export const app = new H3();
+
+const demoURL =
+  "https://raw.githubusercontent.com/h3js/crossws/refs/heads/main/playground/public/index.html";
+
+app.get("/", () =>
+  fetch(demoURL).then(
+    (res) => new Response(res.body, { headers: { "Content-Type": "text/html" } }),
+  ),
+);
+
+app.get(
+  "/_ws",
+  defineWebSocketHandler({
+    // upgrade(req) {},
+    open(peer) {
+      console.log("[open]", peer);
+
+      // Send welcome to the new client
+      peer.send("Welcome to the server!");
+
+      // Join new client to the "chat" channel
+      peer.subscribe("chat");
+
+      // Notify every other connected client
+      peer.publish("chat", `[system] ${peer} joined!`);
+    },
+
+    message(peer, message) {
+      console.log("[message]", peer);
+
+      if (message.text() === "ping") {
+        // Reply to the client with a ping response
+        peer.send("pong");
+        return;
+      }
+
+      // The server re-broadcasts incoming messages to everyone
+      peer.publish("chat", `[${peer}] ${message}`);
+
+      // Echo the message back to the sender
+      peer.send(message);
+    },
+
+    close(peer) {
+      console.log("[close]", peer);
+      peer.publish("chat", `[system] ${peer} has left the chat!`);
+      peer.unsubscribe("chat");
+    },
+  }),
+);
+
+serve(app, {
+  plugins: [ws({ resolve: async (req) => (await app.fetch(req)).crossws })],
+});
+```
+
+## Server-Sent Events (SSE)
+
+As an alternative to WebSockets, you can use [Server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events).
+
+H3 has a built-in API to create server-sent events using `createEventStream(event)` utility.
+
+### Example
+
+```js [server-sent-events.mjs]
+import { H3, serve, createEventStream } from "h3";
+
+export const app = new H3();
+
+app.get("/", (event) => {
+  const eventStream = createEventStream(event);
+
+  // Send a message every second
+  const interval = setInterval(async () => {
+    await eventStream.push("Hello world");
+  }, 1000);
+
+  // cleanup the interval when the connection is terminated or the writer is closed
+  eventStream.onClosed(() => {
+    console.log("Connection closed");
+    clearInterval(interval);
+  });
+
+  return eventStream.send();
+});
+
+serve(app);
+```

package/dist/docs/0.guide/3.advanced/2.nightly.md

@@ -0,0 +1,13 @@
+# Nightly Builds
+
+You can opt-in to early test latest H3 changes using automated nightly release channel.
+
+If you are directly using `h3` as a dependency in your project:
+
+```json
+{
+  "dependencies": {
+    "h3": "npm:h3-nightly@latest"
+  }
+}
+```

package/dist/docs/1.utils/0.index/index.md

@@ -0,0 +1,46 @@
+# H3 Utils
+
+H3 is a composable framework. Instead of providing a big core, you start with a lightweight [H3](/guide/api/h3) instance and for every functionality, there is either a built-in utility or you can make yours.
+
+<card-group>
+
+<card>
+
+Utilities for incoming request.
+</card>
+
+<card>
+
+Utilities for preparing and sending response.
+</card>
+
+<card>
+
+Cookie utilities.
+</card>
+
+<card>
+
+Security utilities.
+</card>
+
+<card>
+
+Proxy utilities.
+</card>
+
+<card>
+
+MCP related utilities.
+</card>
+
+<card>
+
+More Utilities.
+</card>
+
+<card>
+
+Community made utilities.
+</card>
+</card-group>

package/dist/docs/1.utils/1.request.md

@@ -0,0 +1,355 @@
+# Request
+
+> H3 request utilities.
+
+## Body
+
+### `assertBodySize(event, limit)`
+
+Asserts that request body size is within the specified limit.
+
+If body size exceeds the limit, throws a `413` Request Entity Too Large response error.
+
+**Example:**
+
+```ts
+app.get("/", async (event) => {
+  await assertBodySize(event, 10 * 1024 * 1024); // 10MB
+  const data = await event.req.formData();
+});
+```
+
+### `readBody(event)`
+
+Reads request body and tries to parse using JSON.parse or URLSearchParams.
+
+**Example:**
+
+```ts
+app.get("/", async (event) => {
+  const body = await readBody(event);
+});
+```
+
+### `readValidatedBody(event, validate)`
+
+Tries to read the request body via `readBody`, then uses the provided validation schema or function and either throws a validation error or returns the result.
+
+You can use a simple function to validate the body or use a Standard-Schema compatible library like `zod` to define a schema.
+
+**Example:**
+
+```ts
+function validateBody(body: any) {
+  return typeof body === "object" && body !== null;
+}
+app.post("/", async (event) => {
+  const body = await readValidatedBody(event, validateBody);
+});
+```
+
+**Example:**
+
+```ts
+import { z } from "zod";
+const objectSchema = z.object({
+  name: z.string().min(3).max(20),
+  age: z.number({ coerce: true }).positive().int(),
+});
+app.post("/", async (event) => {
+  const body = await readValidatedBody(event, objectSchema);
+});
+```
+
+**Example:**
+
+```ts
+import * as v from "valibot";
+app.post("/", async (event) => {
+  const body = await readValidatedBody(
+    event,
+    v.object({
+      name: v.pipe(v.string(), v.minLength(3), v.maxLength(20)),
+      age: v.pipe(v.number(), v.integer(), v.minValue(1)),
+    }),
+    {
+      onError: ({ issues }) => ({
+        statusText: "Custom validation error",
+        message: v.summarize(issues),
+      }),
+    },
+  );
+});
+```
+
+## Cache
+
+### `handleCacheHeaders(event, opts)`
+
+Check request caching headers (`If-Modified-Since`) and add caching headers (Last-Modified, Cache-Control) Note: `public` cache control will be added by default
+
+## More Request Utils
+
+### `assertMethod(event, expected, allowHead?)`
+
+Asserts that the incoming request method is of the expected type using `isMethod`.
+
+If the method is not allowed, it will throw a 405 error and include an `Allow` response header listing the permitted methods, as required by RFC 9110.
+
+If `allowHead` is `true`, it will allow `HEAD` requests to pass if the expected method is `GET`.
+
+**Example:**
+
+```ts
+app.get("/", (event) => {
+  assertMethod(event, "GET");
+  // Handle GET request, otherwise throw 405 error
+});
+```
+
+### `getQuery(event)`
+
+Get parsed query string object from the request URL.
+
+**Example:**
+
+```ts
+app.get("/", (event) => {
+  const query = getQuery(event); // { key: "value", key2: ["value1", "value2"] }
+});
+```
+
+### `getRequestHost(event, opts: { xForwardedHost? })`
+
+Get the request hostname.
+
+If `xForwardedHost` is `true`, it will use the `x-forwarded-host` header if it exists.
+
+If no host header is found, it will return an empty string.
+
+**Example:**
+
+```ts
+app.get("/", (event) => {
+  const host = getRequestHost(event); // "example.com"
+});
+```
+
+### `getRequestIP(event)`
+
+Try to get the client IP address from the incoming request.
+
+If `xForwardedFor` is `true`, it will use the `x-forwarded-for` header if it exists.
+
+If IP cannot be determined, it will default to `undefined`.
+
+**Example:**
+
+```ts
+app.get("/", (event) => {
+  const ip = getRequestIP(event); // "192.0.2.0"
+});
+```
+
+### `getRequestProtocol(event, opts: { xForwardedProto? })`
+
+Get the request protocol.
+
+If `x-forwarded-proto` header is set to "https", it will return "https". You can disable this behavior by setting `xForwardedProto` to `false`.
+
+If protocol cannot be determined, it will default to "http".
+
+**Example:**
+
+```ts
+app.get("/", (event) => {
+  const protocol = getRequestProtocol(event); // "https"
+});
+```
+
+### `getRequestURL(event, opts: { xForwardedHost?, xForwardedProto? })`
+
+Generated the full incoming request URL.
+
+If `xForwardedHost` is `true`, it will use the `x-forwarded-host` header if it exists.
+
+If `xForwardedProto` is `false`, it will not use the `x-forwarded-proto` header.
+
+**Example:**
+
+```ts
+app.get("/", (event) => {
+  const url = getRequestURL(event); // "https://example.com/path"
+});
+```
+
+### `getRouterParam(event, name, opts: { decode? })`
+
+Get a matched route param by name.
+
+If `decode` option is `true`, it will decode the matched route param using `decodeURI`.
+
+**Example:**
+
+```ts
+app.get("/", (event) => {
+  const param = getRouterParam(event, "key");
+});
+```
+
+### `getRouterParams(event, opts: { decode? })`
+
+Get matched route params.
+
+If `decode` option is `true`, it will decode the matched route params using `decodeURIComponent`.
+
+**Example:**
+
+```ts
+app.get("/", (event) => {
+  const params = getRouterParams(event); // { key: "value" }
+});
+```
+
+### `getValidatedQuery(event, validate)`
+
+Get the query param from the request URL validated with validate function.
+
+You can use a simple function to validate the query object or use a Standard-Schema compatible library like `zod` to define a schema.
+
+**Example:**
+
+```ts
+app.get("/", async (event) => {
+  const query = await getValidatedQuery(event, (data) => {
+    return "key" in data && typeof data.key === "string";
+  });
+});
+```
+
+**Example:**
+
+```ts
+import { z } from "zod";
+app.get("/", async (event) => {
+  const query = await getValidatedQuery(
+    event,
+    z.object({
+      key: z.string(),
+    }),
+  );
+});
+```
+
+**Example:**
+
+```ts
+import * as v from "valibot";
+app.get("/", async (event) => {
+  const params = await getValidatedQuery(
+    event,
+    v.object({
+      key: v.string(),
+    }),
+    {
+      onError: ({ issues }) => ({
+        statusText: "Custom validation error",
+        message: v.summarize(issues),
+      }),
+    },
+  );
+});
+```
+
+### `getValidatedRouterParams(event, validate)`
+
+Get matched route params and validate with validate function.
+
+If `decode` option is `true`, it will decode the matched route params using `decodeURI`.
+
+You can use a simple function to validate the params object or use a Standard-Schema compatible library like `zod` to define a schema.
+
+**Example:**
+
+```ts
+app.get("/:key", async (event) => {
+  const params = await getValidatedRouterParams(event, (data) => {
+    return "key" in data && typeof data.key === "string";
+  });
+});
+```
+
+**Example:**
+
+```ts
+import { z } from "zod";
+app.get("/:key", async (event) => {
+  const params = await getValidatedRouterParams(
+    event,
+    z.object({
+      key: z.string(),
+    }),
+  );
+});
+```
+
+**Example:**
+
+```ts
+import * as v from "valibot";
+app.get("/:key", async (event) => {
+  const params = await getValidatedRouterParams(
+    event,
+    v.object({
+      key: v.pipe(v.string(), v.picklist(["route-1", "route-2", "route-3"])),
+    }),
+    {
+      decode: true,
+      onError: ({ issues }) => ({
+        statusText: "Custom validation error",
+        message: v.summarize(issues),
+      }),
+    },
+  );
+});
+```
+
+### `isMethod(event, expected, allowHead?)`
+
+Checks if the incoming request method is of the expected type.
+
+If `allowHead` is `true`, it will allow `HEAD` requests to pass if the expected method is `GET`.
+
+**Example:**
+
+```ts
+app.get("/", (event) => {
+  if (isMethod(event, "GET")) {
+    // Handle GET request
+  } else if (isMethod(event, ["POST", "PUT"])) {
+    // Handle POST or PUT request
+  }
+});
+```
+
+### `requestWithBaseURL(req, base)`
+
+Create a lightweight request proxy with the base path stripped from the URL pathname.
+
+### `requestWithURL(req, url)`
+
+Create a lightweight request proxy that overrides only the URL.
+
+Avoids cloning the original request (no `new Request()` allocation).
+
+### `toRequest(input, options?)`
+
+Convert input into a web [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request).
+
+If input is a relative URL, it will be normalized into a full path based on headers.
+
+If input is already a Request and no options are provided, it will be returned as-is.
+
+### `getRequestFingerprint(event, opts)`
+
+Get a unique fingerprint for the incoming request.