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

package/skills/h3/docs/utils/cookie.md

@@ -0,0 +1,33 @@
+# Cookie
+
+> H3 cookie utilities.
+
+### `deleteChunkedCookie(event, name, serializeOptions?)`
+
+Remove a set of chunked cookies by name.
+
+### `deleteCookie(event, name, serializeOptions?)`
+
+Remove a cookie by name.
+
+### `getChunkedCookie(event, name)`
+
+Get a chunked cookie value by name. Will join chunks together.
+
+### `getCookie(event, name)`
+
+Get a cookie value by name.
+
+### `getValidatedCookies(event, validate, options?: { onError?: OnValidateError })`
+
+### `parseCookies(event)`
+
+Parse the request to get HTTP Cookie header string and returning an object of all cookie name-value pairs.
+
+### `setChunkedCookie(event, name, value, options?)`
+
+Set a cookie value by name. Chunked cookies will be created as needed.
+
+### `setCookie(event, name, value, options?)`
+
+Set a cookie value by name.

package/skills/h3/docs/utils/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/skills/h3/docs/utils/mcp.md

@@ -0,0 +1,71 @@
+# MCP
+
+> H3 MCP related utils.
+
+### `defineJsonRpcHandler()`
+
+Creates an H3 event handler that implements the JSON-RPC 2.0 specification.
+
+**Example:**
+
+```ts
+app.post(
+  "/rpc",
+  defineJsonRpcHandler({
+    methods: {
+      echo: ({ params }, event) => {
+        return `Received \`${params}\` on path \`${event.url.pathname}\``;
+      },
+      sum: ({ params }, event) => {
+        return params.a + params.b;
+      },
+    },
+  }),
+);
+```
+
+### `defineJsonRpcWebSocketHandler()`
+
+Creates an H3 event handler that implements JSON-RPC 2.0 over WebSocket.
+
+This is an opt-in feature that allows JSON-RPC communication over WebSocket connections for bi-directional messaging. Each incoming WebSocket text message is processed as a JSON-RPC request, and responses are sent back to the peer.
+
+**Example:**
+
+```ts
+app.get(
+  "/rpc/ws",
+  defineJsonRpcWebSocketHandler({
+    methods: {
+      echo: ({ params }) => {
+        return `Received: ${Array.isArray(params) ? params[0] : params?.message}`;
+      },
+      sum: ({ params }) => {
+        return params.a + params.b;
+      },
+    },
+  }),
+);
+```
+
+**Example:**
+
+```ts
+// With additional WebSocket hooks
+app.get(
+  "/rpc/ws",
+  defineJsonRpcWebSocketHandler({
+    methods: {
+      greet: ({ params }) => `Hello, ${params.name}!`,
+    },
+    hooks: {
+      open(peer) {
+        console.log(`Peer connected: ${peer.id}`);
+      },
+      close(peer, details) {
+        console.log(`Peer disconnected: ${peer.id}`, details);
+      },
+    },
+  }),
+);
+```

package/skills/h3/docs/utils/more.md

@@ -0,0 +1,78 @@
+# More utils
+
+> More H3 utilities.
+
+## Base
+
+### `withBase(base, input)`
+
+Returns a new event handler that removes the base url of the event before calling the original handler.
+
+**Example:**
+
+```ts
+const api = new H3()
+ .get("/", () => "Hello API!");
+const app = new H3();
+ .use("/api/**", withBase("/api", api.handler));
+```
+
+## Event
+
+### `getEventContext(event)`
+
+Gets the context of the event, if it does not exists, initializes a new context on `req.context`.
+
+### `isEvent(input)`
+
+Checks if the input is an H3Event object.
+
+### `isHTTPEvent(input)`
+
+Checks if the input is an object with `{ req: Request }` signature.
+
+### `mockEvent(_request, options?)`
+
+## Middleware
+
+### `bodyLimit(limit)`
+
+Define a middleware that checks whether request body size is within specified limit.
+
+If body size exceeds the limit, throws a `413` Request Entity Too Large response error. If you need custom handling for this case, use `assertBodySize` instead.
+
+### `onError(hook)`
+
+Define a middleware that runs when an error occurs.
+
+You can return a new Response from the handler to gracefully handle the error.
+
+### `onRequest(hook)`
+
+Define a middleware that runs on each request.
+
+### `onResponse(hook)`
+
+Define a middleware that runs after Response is generated.
+
+You can return a new Response from the handler to replace the original response.
+
+## WebSocket
+
+### `defineWebSocket(hooks)`
+
+Define WebSocket hooks.
+
+### `defineWebSocketHandler()`
+
+Define WebSocket event handler.
+
+## Adapters
+
+### `defineNodeHandler(handler)`
+
+### `defineNodeMiddleware(handler)`
+
+### `fromNodeHandler(handler)`
+
+### `fromWebHandler(handler)`

package/skills/h3/docs/utils/proxy.md

@@ -0,0 +1,31 @@
+# Proxy
+
+> H3 proxy utilities.
+
+### `fetchWithEvent(event, url, init?)`
+
+Make a fetch request with the event's context and headers.
+
+If the `url` starts with `/`, the request is dispatched internally via `event.app.fetch()` (sub-request) and never leaves the process.
+
+**Security:** Never pass unsanitized user input as the `url`. Callers are responsible for validating and restricting the URL.
+
+### `getProxyRequestHeaders(event)`
+
+Get the request headers object without headers known to cause issues when proxying.
+
+### `proxy(event, target, opts)`
+
+Make a proxy request to a target URL and send the response back to the client.
+
+If the `target` starts with `/`, the request is dispatched internally via `event.app.fetch()` (sub-request) and never leaves the process. This bypasses any external security layer (reverse proxy auth, IP allowlisting, mTLS).
+
+**Security:** Never pass unsanitized user input as the `target`. Callers are responsible for validating and restricting the target URL (e.g. allowlisting hosts, blocking internal paths, enforcing protocol).
+
+### `proxyRequest(event, target, opts)`
+
+Proxy the incoming request to a target URL.
+
+If the `target` starts with `/`, the request is handled internally by the app router via `event.app.fetch()` instead of making an external HTTP request.
+
+**Security:** Never pass unsanitized user input as the `target`. Callers are responsible for validating and restricting the target URL (e.g. allowlisting hosts, blocking internal paths, enforcing protocol). Consider using `bodyLimit()` middleware to prevent large request bodies from consuming excessive resources when proxying untrusted input.

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