@depup/h3 2.0.1-depup.0

package/dist/docs/1.utils/4.security.md

@@ -0,0 +1,175 @@
+# Security
+
+> H3 security utilities.
+
+## Authentication
+
+### `basicAuth(opts)`
+
+Create a basic authentication middleware.
+
+**Example:**
+
+```ts
+import { H3, serve, basicAuth } from "h3";
+const auth = basicAuth({ password: "test" });
+app.get("/", (event) => `Hello ${event.context.basicAuth?.username}!`, [auth]);
+serve(app, { port: 3000 });
+```
+
+### `requireBasicAuth(event, opts)`
+
+Apply basic authentication for current request.
+
+**Example:**
+
+```ts
+import { defineHandler, requireBasicAuth } from "h3";
+export default defineHandler(async (event) => {
+  await requireBasicAuth(event, { password: "test" });
+  return `Hello, ${event.context.basicAuth.username}!`;
+});
+```
+
+## Session
+
+### `clearSession(event, config)`
+
+Clear the session data for the current request.
+
+### `getSession(event, config)`
+
+Get the session for the current request.
+
+A request without a session gets a new one initialized in memory only — no `Set-Cookie` is issued until something is stored with {@link updateSession}, so reading the session (an auth check, for example) does not start one for anonymous visitors. Its `id` is therefore only stable across requests once the session has been written; use {@link useSession} to start one eagerly.
+
+### `sealSession(event, config)`
+
+Encrypt and sign the session data for the current request.
+
+### `unsealSession(_event, config, sealed)`
+
+Decrypt and verify the session data for the current request.
+
+### `updateSession(event, config, update?)`
+
+Update the session data for the current request.
+
+### `useSession(event, config)`
+
+Create a session manager for the current request.
+
+Starts a session if the request does not carry one, persisting it so its id is stable across requests. Use {@link getSession} to read a session without starting one.
+
+## Fingerprint
+
+### `getRequestFingerprint(event, opts)`
+
+Get a unique fingerprint for the incoming request.
+
+## CORS
+
+### `appendCorsHeaders(event, options)`
+
+Append CORS headers to the response.
+
+### `appendCorsPreflightHeaders(event, options)`
+
+Append CORS preflight headers to the response.
+
+### `handleCors(event, options)`
+
+Handle CORS for the incoming request.
+
+If the incoming request is a CORS preflight request, it will append the CORS preflight headers and send a 204 response.
+
+If return value is not `false`, the request is handled and no further action is needed.
+
+**Example:**
+
+```ts
+const app = new H3();
+app.all("/", async (event) => {
+  const corsRes = handleCors(event, {
+    origin: "*",
+    preflight: {
+      statusCode: 204,
+    },
+    methods: "*",
+  });
+  if (corsRes !== false) {
+    return corsRes;
+  }
+  // Your code here
+});
+```
+
+### `isCorsOriginAllowed(origin, options)`
+
+Check if the origin is allowed.
+
+### `isPreflightRequest(event)`
+
+Check if the incoming request is a CORS preflight request.
+
+## Path
+
+### `isCanonicalPath(path, opts?)`
+
+Whether `path` is already canonical under `opts` — i.e. {@link resolveDotSegments} would return it unchanged. Exact in both directions: `true` if and only if `resolveDotSegments(path, opts) === path`.
+
+This is the resolver's own fast-path guard, exported so a caller that canonicalizes on a hot path (per-request scope or rule matching) can skip the call — and any work derived from it — without keeping its own copy of what the resolver decodes. Such a copy goes stale silently, and a missed canonicalization in a scope check is a bypass, not a perf bug.
+
+Pass the same options as the later {@link resolveDotSegments} call, or stricter ones: `decodeSlashes`/`mergeSlashes` only add triggers, so `true` with both enabled implies `true` in every mode. Checking one mode and resolving in another voids the guarantee.
+
+Takes a bare pathname. Like the resolver, it has no notion of a query or hash and scans one as if it were path, so `/a?next=/../b` is reported non-canonical (and would resolve to `/b`).
+
+### `normalizeRoute(route)`
+
+Normalize a route pattern into the canonical form h3 registers it under — the same shape as the `event.url.pathname` it will be matched against.
+
+`app.on()`, `app.use(route, …)`, `app.mount()` and `removeRoute()` all apply this to the pattern they receive. Use it when registering patterns into a router of your own (e.g. a build-time compiled rou3 router) that is then matched against h3's `event.url.pathname`, so both sides agree on the string — a pattern that normalized differently could leave a route reachable while a guard registered with the same source string matches nothing.
+
+A leading `/` is added if missing (`about` → `/about`), characters a request pathname always carries percent-encoded are encoded (`/café/**` → `/caf%C3%A9/**`), needless escapes are decoded the way h3 decodes them in the request pathname (`/%40handle` → `/@handle`; `%2F` and `%25` stay encoded), and `.`/`..` segments are resolved (`/a/b/../c` → `/a/c`). rou3 pattern syntax (`?`, `{`, `}`, `^`, `\`) is left verbatim — spell one percent-encoded to match it literally.
+
+Idempotent. Throws on an absolute URL (`http://…`): a route pattern is a pathname, never a URL.
+
+**Example:**
+
+```ts
+normalizeRoute("/について/**"); // "/%E3%81%AB%E3%81%A4%E3%81%84%E3%81%A6/**"
+```
+
+### `resolveDotSegments(path, opts?)`
+
+Resolve `.` and `..` segments in a path, without ever escaping above the root `/`. The result is always an absolute path with a single leading `/`, so it can never be protocol-relative (`//host`).
+
+Also decodes percent-encoded dot segments at any `%25`-nesting depth (`%2e`, `%252e`, ...) and normalizes `\` to `/`, so encoded or backslash-based traversal (e.g. `%2e%2e/`, `..\..\`) is caught the same way as a literal `../`.
+
+`%2f`/`%5c` (encoded path separators) are left untouched by default — see {@link ResolveDotSegmentsOptions.decodeSlashes}.
+
+Only `.`/`..` resolution and the decodes above alter the string; every other percent-encoding (`%20`, non-ASCII, `%3A`, and any `%2e` not forming a whole segment) is left intact, so the result stays in the same representation as `event.url.pathname` and matches routes/rules consistently. A trailing `.`/`..` resolves to a directory and keeps its trailing slash (`/a/b/..` -> `/a/`, `/a/.` -> `/a/`), per RFC 3986 §5.2.4 and matching what a WHATWG/nginx downstream resolves — so a scope check sees the directory form, not its file-form sibling. Interior empty segments are preserved (`/a//b` stays `/a//b`) — like WHATWG, this never merges slashes, so empty segments survive rather than collapsing. The one exception is a <u>leading</u> run: it is always clamped to a single `/` (WHATWG would keep `//host`), so only the leading slash is guaranteed single and a consumer doing exact prefix matching should normalize its allowlist the same way. To collapse interior runs too (the reading a slash-merging downstream resolves), see {@link ResolveDotSegmentsOptions.mergeSlashes}.
+
+## Route params
+
+Route params reach your handler in the form they had in the URL path — percent-encoded. `getRouterParams(event, { decode: true })` (and `getValidatedRouterParams` with the same option) applies **one** decode pass, not a full normalization:
+
+- Encoded path separators (`%2f`, `%5c`, at any `%25`-nesting depth: `%252f`, `%25252f`, ...) are **never** decoded. A raw `/` or `\` can never appear in a param that the router matched as one segment, so a param cannot silently gain a path boundary that routing and middleware never saw.
+- Every other escape decodes exactly one level. Because `%25` is itself an escape, `%25XX` decodes to the literal text `%XX` — so the result can still contain percent-escapes.
+
+```ts
+app.get("/files/**:rest", (event) => {
+  // GET /files/%252e%252e/x
+  getRouterParams(event); // { rest: "%252e%252e/x" }
+  getRouterParams(event, { decode: true }); // { rest: "%2e%2e/x" }
+
+  // GET /files/%2500
+  getRouterParams(event, { decode: true }); // { rest: "%00" }
+
+  // GET /files/a%252fb  — separators stay encoded at every depth
+  getRouterParams(event, { decode: true }); // { rest: "a%252fb" }
+});
+```
+
+> [!IMPORTANT]
+Do not decode the returned value again. A second `decodeURIComponent` turns `%2e%2e/x` into `../x` and `%00` into a NUL byte — traversal and control characters that were not visible to routing or to any pathname-based middleware. Validate the value as returned, and if it will be used as a filesystem or upstream path, resolve it with [`resolveDotSegments`](#resolvedotsegmentspath-opts) rather than by decoding further.

package/dist/docs/1.utils/5.proxy.md

@@ -0,0 +1,57 @@
+# Proxy
+
+> H3 proxy utilities.
+
+### `fetchWithEvent(event, url, init?)`
+
+Make a fetch request carrying the event's context.
+
+Behavior depends on the target:
+
+An **internal** `url` (starting with `/`) is dispatched via `event.app.fetch()` (sub-request) and never leaves the process. It inherits the incoming request's filtered headers (via `getProxyRequestHeaders`) and runtime metadata (`ip`, `waitUntil`, ...). It always resolves against the app's own origin: a leading separator run (`//host/x`, `/\host/x`, and C0-interleaved forms like `/\thost/x` that the URL parser strips down to one) is collapsed to a single `/` rather than read as an authority.
+
+An **external** `url` is sent with native `fetch(url, init)` **unchanged** — the event's headers and context are <u>not</u> inherited (forwarding cookies or authorization to arbitrary hosts would be unsafe). A streamed `init.body` is given `duplex: "half"` when unset, which Node's `fetch` requires.
+
+**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).
+
+Upstream 3xx responses are passed through to the client by default rather than followed. Set `fetchOptions: { redirect: "follow" }` to follow them instead — but following a redirect with a streamed request body can fail, since the body cannot be replayed once consumed. (Internal sub-requests via `event.app.fetch()` never follow redirects.)
+
+**Limitations** (inherited from `fetch`): upstream response bodies are always decompressed (compression is not preserved end-to-end), the `host` header is rewritten to the target (preserving it via `forwardHeaders: ["host"]` works on Node.js but may be ignored on other runtimes), and unix sockets, TLS options, or connection agents require a runtime-specific escape hatch (e.g. undici's `dispatcher` in `fetchOptions` on Node.js). On browser and service-worker runtimes, `redirect: "manual"` produces an unrelayable opaque-redirect for external targets (a `502` is returned) — set `fetchOptions: { redirect: "follow" }` there.
+
+**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).
+
+**Credential forwarding:** `proxy` does not forward the incoming request's headers automatically — only headers the caller explicitly passes via `opts.headers` (or `fetchOptions.headers`) are sent, verbatim. Do not pass the client's `Cookie` or `Authorization` headers through to an upstream you do not fully trust. Note that `opts.filterHeaders` has no effect here — it is only applied by `proxyRequest` (which does forward the incoming headers and offers `filterHeaders: ["cookie", "authorization"]` as the mitigation).
+
+### `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. Such a target always resolves against the app's own origin: a leading separator run (`//host/x`, `/\host/x`, and C0-interleaved forms like `/\thost/x` that the URL parser strips down to one) is collapsed to a single `/` rather than read as an authority.
+
+The request body is streamed to the target without buffering. Per the Fetch standard, a request body can only be consumed once, so reading it beforehand (e.g. via `readBody()`, `readFormData()`, or body-reading middleware) locks the stream and proxying fails. If you need to inspect the body and still proxy it, read from a clone and leave the original event untouched.
+
+Upstream 3xx responses are passed through to the client by default rather than followed. Set `fetchOptions: { redirect: "follow" }` to follow them instead — but following a redirect with a streamed request body can fail, since the body cannot be replayed once consumed.
+
+**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.
+
+**Credential forwarding:** the incoming request's `Cookie` and `Authorization` headers are forwarded to the `target` verbatim. This is the correct behavior for a same-trust reverse proxy, but leaks the client's credentials to any upstream you do not fully trust. When proxying to a not-fully-trusted upstream, strip them with `filterHeaders: ["cookie", "authorization"]`. (This differs from `fetchWithEvent`, which never forwards the event's headers to an external URL.)
+
+**Example:**
+
+```ts
+app.all("/proxy", async (event) => {
+  const body = await event.req.clone().json(); // read from the clone
+  // ...inspect body...
+  return proxyRequest(event, "/target"); // original stream still intact
+});
+```

package/dist/docs/1.utils/6.mcp.md

@@ -0,0 +1,75 @@
+# MCP
+
+> H3 MCP related utils.
+
+### `defineJsonRpcHandler()`
+
+Creates an H3 event handler that implements the JSON-RPC 2.0 specification.
+
+**Security defaults:** requests must have a JSON `Content-Type` (CSRF, see `validateContentType`), cross-origin requests are rejected (CSRF and DNS rebinding, see `allowedOrigins`), and batches are capped at 50 requests (fan-out amplification, see `maxBatchSize`).
+
+**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.
+
+**Security:** unlike `defineJsonRpcHandler()`, this does not check the request `Origin`. WebSocket upgrades are not subject to CORS, so a page on any origin can open a connection carrying the visitor's cookies (cross-site WebSocket hijacking). Validate `Origin` in the `upgrade` hook and throw a `Response` to abort the connection.
+
+**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/dist/docs/1.utils/7.more.md

@@ -0,0 +1,117 @@
+# 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 limits the request body size to the specified limit.
+
+The limit is enforced as the body is read (see {@link assertBodySize}), so an oversized body surfaces as a `413` Request Entity Too Large error when the handler consumes it (an honest oversized `Content-Length` is still rejected up-front). A body the handler never reads is not counted. If you need custom handling, use `assertBodySize` directly.
+
+### `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.
+
+**Example:**
+
+```ts
+const hooks = defineWebSocket({
+  open: (peer) => peer.send("Welcome!"),
+  message: (peer, message) => peer.send(message.text()),
+  close: (peer) => console.log("closed", peer),
+});
+```
+
+### `defineWebSocketHandler(http?)`
+
+Define WebSocket event handler.
+
+By default, non-upgrade (plain HTTP) requests receive a `426 Upgrade Required` response. Pass an `http` handler to serve those requests instead, allowing the same route to handle both WebSocket upgrades and regular HTTP requests. WebSocket upgrade requests always go to `hooks`.
+
+Note: the `http` handler only handles non-upgrade requests. To reject or customize the upgrade handshake itself, use the crossws `upgrade` hook instead.
+
+**Example:**
+
+```ts
+// WebSocket-only route (non-upgrade requests get `426 Upgrade Required`)
+app.get(
+  "/_ws",
+  defineWebSocketHandler({
+    message: (peer, message) => peer.send(message.text()),
+  }),
+);
+```
+
+**Example:**
+
+```ts
+// Handle both WebSocket upgrades and plain HTTP on the same route
+app.get(
+  "/_ws",
+  defineWebSocketHandler(
+    { message: (peer, message) => peer.send(message.text()) },
+    () => "Send a WebSocket upgrade request to connect.",
+  ),
+);
+```
+
+## Adapters
+
+### `defineNodeHandler(handler)`
+
+### `defineNodeMiddleware(handler)`
+
+### `fromNodeHandler(handler)`
+
+### `fromWebHandler(handler)`

package/dist/docs/1.utils/8.community.md

@@ -0,0 +1,48 @@
+# Community
+
+> H3 utils from community.
+
+You can use external H3 event utilities made by the community.
+
+This section is placeholder for any new H3 version 2 compatible community library.
+
+
+
+> [!TIP]
+> 💛 PR is more than welcome to list yours.
+
+## `apitally`
+
+[Apitally](https://apitally.io/h3) is a simple API monitoring, analytics, and request logging tool with a plugin for H3. See setup guide [here](https://docs.apitally.io/frameworks/h3).
+
+<read-more></read-more>
+
+## `H3ravel Framework`
+
+[H3ravel Framework](https://h3ravel.toneflix.net) is a modern TypeScript runtime-agnostic web framework built on top of H3, designed to bring the elegance and developer experience of Laravel PHP to the JavaScript ecosystem. See the getting started guide [here](https://h3ravel.toneflix.net/guide/get-started).
+
+<read-more></read-more>
+
+## `Intlify`
+
+[Intlify](https://intlify.dev/) is a project that aims to improve Developer Experience in software internationalization. That project provides server-side frameworks, middleware, and utilities. About those, see the [here](https://github.com/intlify/srvmid)
+
+<read-more></read-more>
+
+## `Clear Router`
+
+Laravel-style routing system for H3 and Express.js. Clean route definitions, middleware support, and controller bindings with full TypeScript support.
+
+<read-more></read-more>
+
+## `unjwt`
+
+`unjwt` is a collection of low-level JWT utilities (JWS, JWE, JWK) built on the Web Crypto API, with zero runtime dependencies. It includes a dedicated H3 v2 adapter for header and cookie-based session management with support for encrypted (JWE) and signed (JWS) tokens.
+
+<read-more></read-more>
+
+## `Arkstack`
+
+[Arkstack](https://arkstack.toneflix.net) is a runtime-agnostic TypeScript backend framework for building structured, production-ready server applications with first-class support for H3.
+
+<read-more></read-more>

package/dist/docs/2.examples/0.index/index.md

@@ -0,0 +1,17 @@
+# Examples
+
+> Common examples for h3.
+
+<read-more>
+
+Check [`examples/` dir](https://github.com/h3js/h3/tree/main/examples) for more examples.
+</read-more>
+
+**Examples:**
+
+- [Cookies](/examples/handle-cookie)
+- [HTTP QUERY Method](/examples/handle-query)
+- [Session](/examples/handle-session)
+- [Static Assets](/examples/serve-static-assets)
+- [Streaming Response](/examples/stream-response)
+- [Validation](/examples/validate-data)

package/dist/docs/2.examples/1.handle-cookie.md

@@ -0,0 +1,67 @@
+# Cookies
+
+> Use cookies to store data on the client.
+
+Handling cookies with H3 is straightforward. There is three utilities to handle cookies:
+
+- `setCookie` to attach a cookie to the response.
+- `getCookie` to get a cookie from the request.
+- `deleteCookie` to clear a cookie from the response.
+
+## Set a Cookie
+To set a cookie, you need to use `setCookie` in an event handler:
+
+```ts
+import { setCookie } from "h3";
+
+app.use(async (event) => {
+  setCookie(event, "name", "value", { maxAge: 60 * 60 * 24 * 7 });
+  return "";
+});
+```
+
+In the options, you can configure the [cookie flags](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie):
+
+- `maxAge` to set the expiration date of the cookie in seconds.
+- `expires` to set the expiration date of the cookie in a `Date` object.
+- `path` to set the path of the cookie.
+- `domain` to set the domain of the cookie.
+- `secure` to set the `Secure` flag of the cookie.
+- `httpOnly` to set the `HttpOnly` flag of the cookie.
+- `sameSite` to set the `SameSite` flag of the cookie.
+<read-more></read-more>
+
+## Get a Cookie
+
+To get a cookie, you need to use `getCookie` in an event handler.
+
+```ts
+import { getCookie } from "h3";
+
+app.use(async (event) => {
+  const name = getCookie(event, "name");
+
+  // do something...
+
+  return "";
+});
+```
+
+This will return the value of the cookie if it exists, or `undefined` otherwise.
+
+## Delete a Cookie
+
+To delete a cookie, you need to use `deleteCookie` in an event handler:
+
+```ts
+import { deleteCookie } from "h3";
+
+app.use(async (event) => {
+  deleteCookie(event, "name");
+  return "";
+});
+```
+
+The utility `deleteCookie` is a wrapper around `setCookie` with the value set to `""` and the `maxAge` set to `0`.
+
+This will erase the cookie from the client.

package/dist/docs/2.examples/2.handle-query.md

@@ -0,0 +1,76 @@
+# HTTP `QUERY` Method
+
+> Accept safe, cacheable requests that carry a query in the body.
+
+The [HTTP `QUERY` method (RFC 10008)](https://www.rfc-editor.org/rfc/rfc10008) is like `GET` — **safe, idempotent, and cacheable** — but carries a query in the request **body** with a `Content-Type`. It's the standard answer to "I need a GET, but my query is too large or too structured for the URL".
+
+H3 supports `QUERY` as a first-class method via [`app.query()`](/guide/basics/routing#http-query-method), plus two helper utilities.
+
+## Register a `QUERY` Handler
+
+Read the request body just like you would for a `POST`:
+
+```ts
+import { readBody } from "h3";
+
+app.query("/books", async (event) => {
+  const query = await readBody(event, { type: "text" });
+  return runSearch(query);
+});
+```
+
+Because `QUERY` carries an attacker-controllable body, [body-size limits](/utils/request#assertbodysizeevent-limit) apply just like `POST`.
+
+## Advertise Accepted Formats
+
+Use [`appendAcceptQuery`](/utils/request#appendacceptqueryevent-mediatypes) to tell clients which query formats a resource understands. It sets the `Accept-Query` response header (a [Structured Fields](https://www.rfc-editor.org/rfc/rfc8941) List), and can be set on a plain `GET` too so clients can discover formats before sending a `QUERY`:
+
+```ts
+import { appendAcceptQuery } from "h3";
+
+app.get("/books", (event) => {
+  appendAcceptQuery(event, ["application/sql", "application/jsonpath"]);
+  // Accept-Query: application/sql, application/jsonpath
+  return "Send a QUERY request with a SQL or JSONPath body.";
+});
+```
+
+## Validate the `Content-Type`
+
+Use [`requireContentType`](/utils/request#requirecontenttypeevent-acceptedtypes) to enforce the RFC's error semantics. It returns the matched media type, or throws `400` (missing), `415` (unsupported), or `422` (malformed):
+
+```ts
+import { requireContentType, readBody } from "h3";
+
+app.query("/books", async (event) => {
+  const type = requireContentType(event, ["application/sql", "application/jsonpath"]);
+  const query = await readBody(event, { type: "text" });
+  return runQuery(type, query);
+});
+```
+
+## Offer a Cacheable `GET` Alternative
+
+A `QUERY` response is not addressable by URL, so browsers and CDNs can't cache it. RFC 10008 suggests pointing clients at an equivalent, cacheable `GET` via the `Content-Location` header. Stash the result under a stable id and let a client repeat the query with an ordinary, HTTP-cacheable `GET`:
+
+```ts
+app.query("/books", async (event) => {
+  const result = runQuery(type, query);
+  const id = queryId(type, query); // stable hash of the query
+  cache.set(id, result);
+  event.res.headers.set("content-location", `/books/${id}`);
+  return result;
+});
+```
+
+## Full Example
+
+A self-contained, runnable demo — a `/books` resource that accepts SQL-ish and JSONPath queries, validates the `Content-Type`, and advertises a cacheable `GET` alternative. It also serves a small interactive page at `/`.
+
+<read-more>
+
+See the full [`examples/query.mjs`](https://github.com/h3js/h3/tree/main/examples/query.mjs) source, or run it locally with `node examples/query.mjs`.
+</read-more>
+
+> [!NOTE]
+> Unlike `GET`, `QUERY` is **not** CORS-safelisted, so browsers send a preflight. If you pass an explicit `methods` allowlist to [`handleCors`](/utils/security#handlecorsevent-options), include `"QUERY"`.