@depup/h3 2.0.1-rc.17-depup.0

package/skills/h3/docs/guide/api/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.

package/skills/h3/docs/guide/api/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/skills/h3/docs/guide/basics/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 pbject
+  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/skills/h3/docs/guide/basics/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/skills/h3/docs/guide/basics/lifecycle.md

@@ -0,0 +1,68 @@
+# Request Lifecycle
+
+> H3 dispatches incoming web requests to final web responses.
+
+Below is an overview of what happens in a H3 server from when an HTTP request arrives until a response is generated.
+
+## 1. Incoming Request
+
+When An HTTP request is made by Browser or [fetch()](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API), server fetch handler receives a [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object.
+
+```mermaid
+%%{init: {'theme':'neutral'}}%%
+flowchart LR
+  A1["<code>fetch(request)</code>"] --> A2["<code>server.fetch(request)</code>"]
+
+click A2 "/guide/api/h3#h3fetch"
+```
+
+> [!TIP]
+> ​[💥 Srvx](https://srvx.h3.dev) provides unified `server.fetch` interface and adds [Node.js compatibility](https://srvx.h3.dev/guide/node).
+
+## 2. Accept Request
+
+H3 Initializes an [`H3Event`](/guide/api/h3event) instance from incoming request, calls [`onRequest`](/guide/api/h3#global-hooks) global hook and finally [`H3.handler`](/guide/api/h3#h3handler) with the initialized event.
+
+```mermaid
+%%{init: {'theme':'neutral'}}%%
+flowchart LR
+  B1["<code>new H3Event(request)</code>"] --> B2["<code>onRequest(event)</code>"] --> B3["<code>h3.handler(event)</code>"]
+
+click B1 "/guide/api/h3event"
+click B2 "/guide/api/h3#global-hooks"
+click B3 "/guide/api/h3#apphandler"
+```
+
+## 3. Dispatch Request
+
+H3 [matches route](/guide/basics/routing) based on `request.url` and `request.method`, calls global [middleware](/guide/basics/middleware) and finally matched route handler function with event.
+
+```mermaid
+%%{init: {'theme':'neutral'}}%%
+sequenceDiagram
+    participant MiddlewareA as Middleware1(event, next)
+    participant MiddlewareB as Middleware2(event, next)
+    participant Route as RouteHandler(event)
+
+    MiddlewareA->>+MiddlewareB: await next()
+    MiddlewareB->>+Route: await next()
+    Route-->>-MiddlewareB: rawBody
+    MiddlewareB-->>-MiddlewareA: rawBody
+
+```
+
+> [!TIP]
+> 🚀 Internally, H3 uses srvx `FastURL` instead of `new URL(req.url).pathname`.
+
+## 4. Send Response
+
+H3 [converts](/guide/basics/response#response-types) returned value and [prepared headers](/guide/basics/response#preparing-response) into a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response), calls [`onResponse`](/guide/api/h3#global-hooks) global hook and finally returns response back to the server fetch handler.
+
+```mermaid
+%%{init: {'theme':'neutral'}}%%
+flowchart LR
+ D1["Returned Value => Response"] --> D2["<code>onResponse(response)</code>"] --> D3["Response"]
+
+click D1 "/guide/basics/response"
+click D2 "/guide/api/h3#global-hooks"
+```

package/skills/h3/docs/guide/basics/middleware.md

@@ -0,0 +1,97 @@
+# Middleware
+
+> Intercept request, response and errors using H3 middleware.
+
+> [!IMPORTANT]
+> We recommend using composable utilities whenever possible. Global middleware can complicate application logic, making it less predictable and harder to understand.
+
+Global middleware run on each request before route handler and act as wrappers to intercept request, response and errors.
+
+<read-more></read-more>
+
+You can register global middleware to [app instance](/guide/api/h3) using the [`H3.use`](/guide/api/h3#h3use).
+
+**Example:** Register a global middleware that logs every request.
+
+```js
+app.use((event) => {
+  console.log(event);
+});
+```
+
+**Example:** Register a global middleware that matches certain requests.
+
+```js
+app.use(
+  "/blog/**",
+  (event, next) => {
+    console.log("[alert] POST request on /blog paths!");
+  },
+  {
+    method: "POST",
+    // match: (event) => event.req.method === "POST",
+  },
+);
+```
+
+You can register middleware with `next` argument to intercept return values of next middleware and handler.
+
+```js
+app.use(async (event, next) => {
+  const rawBody = await next();
+  // [intercept response]
+  return rawBody;
+});
+```
+
+Example below, always responds with `Middleware 1`.
+
+```js
+app
+  .use(() => "Middleware 1")
+  .use(() => "Middleware 2")
+  .get("/", "Hello");
+```
+
+> [!IMPORTANT]
+> If middleware returns a value other than `undefined` or the result of `next()`, it immediately intercepts request handling and sends a response.
+
+When adding routes, you can register middleware that only run with them.
+
+```js
+import { basicAuth } from "h3";
+
+app.get(
+  "/secret",
+  (event) => {
+    /* ... */
+  },
+  {
+    middleware: [basicAuth({ password: "test" })],
+  },
+);
+```
+
+For convenience, H3 provides middleware factory functions `onRequest`, `onResponse`, and `onError`:
+
+```js
+import { onRequest, onResponse, onError } from "h3";
+
+app.use(
+  onRequest((event) => {
+    console.log(`[${event.req.method}] ${event.url.pathname}`);
+  }),
+);
+
+app.use(
+  onResponse((response, event) => {
+    console.log(`[${event.req.method}] ${event.url.pathname} ~>`, response.status);
+  }),
+);
+
+app.use(
+  onError((error, event) => {
+    console.log(`[${event.req.method}] ${event.url.pathname} !! ${error.message}`);
+  }),
+);
+```