@depup/h3 2.0.1-depup.0

package/dist/docs/3.migration/0.index/index.md

@@ -0,0 +1,204 @@
+# Migration guide for v1 to v2
+
+H3 version 2 includes some behavior and API changes that you need to consider applying when migrating.
+
+> [!NOTE]
+> Currently H3 v2 in beta stage. You can try with [nightly channel](/guide/advanced/nightly).
+
+> [!NOTE]
+> This is an undergoing migration guide and might be updated.
+
+> [!TIP]
+> H3 has a brand new documentation rewrite. Head to the new [Guide](/guide) section to learn more!
+
+## Latest Node.js and ESM-only
+
+> [!TIP]
+> H3 v2 requires Node.js >= 20.19 (latest LTS recommended) .
+
+If your application is currently using CommonJS modules (`require` and `module.exports`), You can still use `require("h3")` thanks to `require(esm)` supported in latest Node.js versions.
+
+You can alternatively use other compatible runtimes [Bun](https://bun.sh/) or [Deno](https://deno.com/).
+
+## Web Standards
+
+> [!TIP]
+> H3 v2 is rewritten based on web standard primitives ([`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL), [`Headers`](https://developer.mozilla.org/en-US/docs/Web/API/Headers), [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request), and [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response)).
+
+When using Node.js, H3 uses a compatibility layer ([💥 srvx](https://srvx.h3.dev/guide/node)) and in other runtimes uses native web compatibility APIs.
+
+Access to the native `event.node.{req,res}` is only available when running server in Node.js runtime.
+
+`event.web` is renamed to `event.req` (instance of web [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request)).
+
+## Response Handling
+
+> [!TIP]
+> You should always explicitly **return** the response body or **throw** an error.
+
+If you were previously using methods below, you can replace them with `return` statements returning a text, JSON, stream, or web `Response` (h3 smartly detects and handles each):
+
+- `send(event, value)`: Migrate to `return <value>`.
+- `sendError(event, <error>)`: Migrate to `throw createError(<error>)`.
+- `sendStream(event, <stream>)`: Migrate to `return <stream>`.
+- `sendWebResponse(event, <response>)`: Migrate to `return <response>`.
+Other send utils that are renamed and need explicit `return`:
+
+- `sendNoContent(event)` / `return null`: Migrate to `return noContent()`.
+- `sendIterable(event, <value>)`: Migrate to `return iterable(<value>)`.
+- `sendProxy(event, target)`: Migrate to `return proxy(event, target)`.
+- `handleCors(event)`: Check return value and early `return` if handled(not `false`).
+- `serveStatic(event, content)`: Make sure to add `return` before.
+- `sendRedirect(event, location, code)`: Migrate to `return redirect(location, code)`.
+<read-more></read-more>
+
+## H3 and Router
+
+> [!TIP]
+> Router function is now integrated into the H3 core.
+>  Instead of `createApp()` and `createRouter()` you can use [`new H3()`](/guide/api/h3).
+
+Any handler can return a response. If middleware don't return a response, next handlers will be tried and finally make a 404 if neither responses. Router handlers can return or not return any response, in this case, H3 will send a simple 200 with empty content.
+
+<read-more></read-more>
+
+H3 migrated to a brand new route-matching engine ([🌳 rou3](https://rou3.h3.dev/)). You might experience slight (but more intuitive) behavior changes for matching patterns.
+
+**Other changes from v1:**
+
+- Middleware added with `app.use("/path", handler)` only matches `/path` (not `/path/foo/bar`). For matching all subpaths like before, it should be updated to `app.use("/path/**", handler)`.
+- The `event.path` received in each handler will have a full path without omitting the prefixes. use `withBase(base, handler)` utility to make prefixed app. (example: `withBase("/api", app.handler)`).
+- **`router.add(path, method: Method | Method[]` signature is changed to `router.add(method: Method, path)`**
+- `router.use(path, handler)` is deprecated. Use `router.all(path, handler)` instead.
+- `app.use(() => handler, { lazy: true })` is no supported anymore. Instead you can use `app.use(defineLazyEventHandler(() => handler), { lazy: true })`.
+- `app.use(["/path1", "/path2"], ...)` and `app.use("/path", [handler1, handler2])` are not supported anymore. Instead, use multiple `app.use()` calls.
+- `app.resolve(path)` removed.
+<read-more></read-more>
+
+<read-more></read-more>
+
+## Request Body
+
+> [!TIP]
+> Most of request body utilities can now be replaced with native `event.req.*` methods which is based on web [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Response) interface.
+
+`readBody(event)` utility will use [`JSON.parse`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse) or [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) for parsing requests with `application/x-www-form-urlencoded` content-type.
+
+- For text: Use [event.req.text()](https://developer.mozilla.org/en-US/docs/Web/API/Request/text).
+- For json: Use [event.req.json()](https://developer.mozilla.org/en-US/docs/Web/API/Request/json).
+- For formData: Use [event.req.formData()](https://developer.mozilla.org/en-US/docs/Web/API/Request/formData).
+- For stream: Use [event.req.body](https://developer.mozilla.org/en-US/docs/Web/API/Request/body).
+**Behavior changes:**
+
+- Body utils won't throw an error if the incoming request has no body (or is a `GET` method for example) but instead, return empty values.
+- Native `request.json` and `readBody` does not use [unjs/destr](https://destr.unjs.io) anymore. You should always filter and sanitize data coming from user to avoid [prototype-poisoning](https://medium.com/intrinsic-blog/javascript-prototype-poisoning-vulnerabilities-in-the-wild-7bc15347c96).
+
+## Cookie and Headers
+
+> [!TIP]
+H3 now natively uses standard web [`Headers`](https://developer.mozilla.org/en-US/docs/Web/API/Headers) for all utils.
+
+Header values are always a plain `string` now (no `null` or `undefined` or `number` or `string[]`).
+
+For the [`Set-Cookie`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie) header, you can use [`headers.getSetCookie`](https://developer.mozilla.org/en-US/docs/Web/API/Headers/getSetCookie) that always returns a string array.
+
+## Other Deprecations
+
+H3 v2 deprecated some legacy and aliased utilities.
+
+### App and router utils
+
+- `createApp` / `createRouter`: Migrate to `new H3()`.
+
+### Error utils
+
+- `createError`/`H3Error`: Migrate to `HTTPError`
+- `isError`: Migrate to `HTTPError.isError`
+
+### Handler utils
+
+- `eventHandler`/`defineEventHandler`: Migrate to `defineHandler` (you can also directly use a function!).
+- `lazyEventHandler`: Migrate to `defineLazyEventHandler`.
+- `isEventHandler`: (removed) Any function can be an event handler.
+- `useBase`: Migrate to `withBase`.
+- `defineRequestMiddleware` and `defineResponseMiddleware` removed.
+
+### Request utils
+
+- `getHeader` / `getRequestHeader`: Migrate to `event.req.headers.get(name)`.
+- `getHeaders` / `getRequestHeaders`: Migrate to `Object.fromEntries(event.req.headers.entries())`.
+- `getRequestPath`: Migrate to `event.url.pathname`.
+- `getMethod`: Migrate to `event.req.method`.
+
+> [!IMPORTANT]
+`getRequestProtocol` (and `getRequestURL`) no longer trust the `x-forwarded-proto` header by default. To honor it (only behind a trusted reverse proxy or CDN), opt in with `{ xForwardedProto: true }`. This matches the existing opt-in behavior of `getRequestHost` (`xForwardedHost`) and `getRequestIP` (`xForwardedFor`).
+
+> [!NOTE]
+> The following `H3Event` properties are deprecated in v2 and might be removed in a future version:
+
+> - `event.path` → use `event.url.pathname + event.url.search`
+> - `event.method` → use `event.req.method`
+> - `event.headers` → use `event.req.headers`
+> - `event.node` → use `event.runtime.node`
+
+### Response utils
+
+- `getResponseHeader` / `getResponseHeaders`: Migrate to `event.res.headers.get(name)`
+- `setHeader` / `setResponseHeader` / `setHeaders` / `setResponseHeaders`: Migrate to `event.res.headers.set(name, value)`.
+- `appendHeader` / `appendResponseHeader` / `appendResponseHeaders`: Migrate to `event.res.headers.append(name, value)`.
+- `removeResponseHeader` / `clearResponseHeaders`: Migrate to `event.res.headers.delete(name)`
+- `appendHeaders`: Migrate to `appendResponseHeaders`.
+- `defaultContentType`: Migrate to `event.res.headers.set("content-type", type)`
+- `getResponseStatus` / `getResponseStatusText` / `setResponseStatus`: Use `event.res.status` and `event.res.statusText`.
+
+### Node.js utils
+
+- `defineNodeListener`: Migrate to `defineNodeHandler`.
+- `fromNodeMiddleware`: Migrate to `fromNodeHandler`.
+- `toNodeListener`: Migrate to `toNodeHandler`.
+- `createEvent`: (removed): Use Node.js adapter (`toNodeHandler(app)`).
+- `fromNodeRequest`: (removed): Use Node.js adapter (`toNodeHandler(app)`).
+- `promisifyNodeListener` (removed).
+- `callNodeListener`: (removed).
+
+### Web Utils
+
+- `fromPlainHandler`: (removed) Migrate to Web API.
+- `toPlainHandler`: (removed) Migrate to Web API.
+- `fromPlainRequest` (removed) Migrate to Web API or use `mockEvent` util for testing.
+- `callWithPlainRequest` (removed) Migrate to Web API.
+- `fromWebRequest`: (removed) Migrate to Web API.
+- `callWithWebRequest`: (removed).
+
+### Body Utils
+
+- `readRawBody`: Migrate to `event.req.text()` or `event.req.arrayBuffer()`.
+- `getBodyStream` / `getRequestWebStream`: Migrate to `event.req.body`.
+- `readFormData` / `readMultipartFormData` / `readFormDataBody`: Migrate to `event.req.formData()`.
+
+### Other Utils
+
+- `createEventStream`: Migrate to `new EventStream(event)`.
+- `isStream`: Migrate to `instanceof ReadableStream`.
+- `isWebResponse`: Migrate to `instanceof Response`.
+- `splitCookiesString`: Use `splitSetCookieString` from [cookie-es](https://github.com/unjs/cookie-es).
+- `MIMES`: (removed).
+
+### Type Exports
+
+> [!NOTE]
+There might be more type changes.
+
+- `App`: Migrate to `H3`.
+- `AppOptions`: Migrate to `H3Config`.
+- `_RequestMiddleware`: Migrate to `RequestMiddleware`.
+- `_ResponseMiddleware`: Migrate to `ResponseMiddleware`.
+- `NodeListener`: Migrate to `NodeHandler`.
+- `TypedHeaders`: Migrate to `RequestHeaders` and `ResponseHeaders`.
+- `HTTPHeaderName`: Migrate to `RequestHeaderName` and `ResponseHeaderName`.
+- `H3Headers`: Migrate to native `Headers`.
+- `H3Response`: Migrate to native `Response`.
+- `MultiPartData`: Migrate to native `FormData`.
+- `RouteNode`: Migrate to `RouterEntry`.
+  `CreateRouterOptions`: Migrate to `RouterOptions`.
+Removed type exports: `WebEventContext`, `NodeEventContext`, `NodePromisifiedHandler`, `AppUse`, `Stack`, `InputLayer`, `InputStack`, `Layer`, `Matcher`, `PlainHandler`, `PlainRequest`, `PlainResponse`, `WebHandler`.

package/dist/docs/README.md

@@ -0,0 +1,37 @@
+# H3 Documentation
+
+- [Guide](./0.guide/0.index/index.md)
+  - [Getting Started](./0.guide/0.index/index.md)
+    - [Request Lifecycle](./0.guide/1.basics/0.lifecycle.md)
+    - [Routing](./0.guide/1.basics/1.routing.md)
+    - [Middleware](./0.guide/1.basics/2.middleware.md)
+    - [Event Handlers](./0.guide/1.basics/3.handler.md)
+    - [Sending Response](./0.guide/1.basics/4.response.md)
+    - [Error Handling](./0.guide/1.basics/5.error.md)
+    - [Nested Apps](./0.guide/1.basics/6.nested-apps.md)
+  - [Route Rules](./0.guide/2.rules.md)
+    - [H3](./0.guide/3.api/0.h3.md)
+    - [H3Event](./0.guide/3.api/1.h3event.md)
+    - [Plugins](./0.guide/4.advanced/0.plugins.md)
+    - [WebSockets](./0.guide/4.advanced/1.websocket.md)
+    - [Nightly Builds](./0.guide/4.advanced/2.nightly.md)
+- [Utils](./1.utils/0.index/index.md)
+  - [Community](./1.utils/0.index/index.md)
+  - [Request](./1.utils/1.request.md)
+  - [Response](./1.utils/2.response.md)
+  - [Cookie](./1.utils/3.cookie.md)
+  - [Security](./1.utils/4.security.md)
+  - [Proxy](./1.utils/5.proxy.md)
+  - [MCP](./1.utils/6.mcp.md)
+  - [More utils](./1.utils/7.more.md)
+  - [Community](./1.utils/8.community.md)
+- [Examples](./2.examples/0.index/index.md)
+  - [Examples](./2.examples/0.index/index.md)
+  - [Cookies](./2.examples/1.handle-cookie.md)
+  - [HTTP QUERY Method](./2.examples/2.handle-query.md)
+  - [Sessions](./2.examples/3.handle-session.md)
+  - [Static Assets](./2.examples/4.serve-static-assets.md)
+  - [Stream Response](./2.examples/5.stream-response.md)
+  - [Validate Data](./2.examples/6.validate-data.md)
+- [Migration](./3.migration/0.index/index.md)
+  - [Migration](./3.migration/0.index/index.md)