h3 1.7.1 → 1.8.0-rc.0

package/README.md

@@ -9,6 +9,8 @@
 
 H3 is a minimal h(ttp) framework built for high performance and portability.
 
+👉 [Online Playground](https://stackblitz.com/github/unjs/h3/tree/main/playground?startScript=dev)
+
 ## Features
 
 ✔️  **Portable:** Works perfectly in Serverless, Workers, and Node.js
@@ -36,6 +38,45 @@ yarn add h3
 pnpm add h3
 ```
 
+<details>
+  <summary>Using Nightly Releases</summary>
+
+If you are directly using `h3` as a dependency:
+
+```json
+{
+  "dependencies": {
+    "h3": "npm:h3-nightly@latest"
+  }
+}
+```
+
+If you are using a framework ([Nuxt](https://nuxt.com/) or [Nitro](https://nitro.unjs.io/)) that is using `h3`:
+
+pnpm and yarn:
+
+```json
+{
+  "resolutions": {
+    "h3": "npm:h3-nightly@latest"
+  }
+}
+```
+
+npm:
+
+```json
+{
+  "overrides": {
+    "h3": "npm:h3-nightly@latest"
+  }
+}
+```
+
+**Note:** Make sure to recreate lockfile and `node_modules` after reinstall to avoid hoisting issues.
+
+</details>
+
 ## Usage
 
 ```ts
@@ -94,6 +135,8 @@ app.use(router);
 
 Routes are internally stored in a [Radix Tree](https://en.wikipedia.org/wiki/Radix_tree) and matched using [unjs/radix3](https://github.com/unjs/radix3).
 
+For using nested routers, see [this example](https://stackblitz.com/edit/github-2bmusk?file=app.ts&startScript=dev)
+
 ## More app usage examples
 
 ```js
@@ -158,56 +201,98 @@ app.use("/big", () => import("./big-handler"), { lazy: true });
 
 H3 has a concept of composable utilities that accept `event` (from `eventHandler((event) => {})`) as their first argument. This has several performance benefits over injecting them to `event` or `app` instances in global middleware commonly used in Node.js frameworks, such as Express. This concept means only required code is evaluated and bundled, and the rest of the utilities can be tree-shaken when not used.
 
-### Built-in
+👉 You can check list of exported built-in utils from [JSDocs Documentation](https://www.jsdocs.io/package/h3#package-functions).
+
+#### Body
 
 - `readRawBody(event, encoding?)`
 - `readBody(event)`
-- `parseCookies(event)`
-- `getCookie(event, name)`
-- `setCookie(event, name, value, opts?)`
-- `deleteCookie(event, name, opts?)`
+- `readValidatedBody(event, validate)`
+- `readMultipartFormData(event)`
+
+#### Request
+
 - `getQuery(event)`
+- `getValidatedBody(event, validate)`
 - `getRouterParams(event)`
-- `send(event, data, type?)`
-- `sendRedirect(event, location, code=302)`
+- `getMethod(event, default?)`
+- `isMethod(event, expected, allowHead?)`
+- `assertMethod(event, expected, allowHead?)`
 - `getRequestHeaders(event, headers)` (alias: `getHeaders`)
 - `getRequestHeader(event, name)` (alias: `getHeader`)
+- `getRequestURL(event)`
+- `getRequestHost(event)`
+- `getRequestProtocol(event)`
+- `getRequestPath(event)`
+
+#### Response
+
+- `send(event, data, type?)`
+- `sendNoContent(event, code = 204)`
+- `setResponseStatus(event, status)`
+- `getResponseStatus(event)`
+- `getResponseStatusText(event)`
+- `getResponseHeaders(event)`
+- `getResponseHeader(event, name)`
 - `setResponseHeaders(event, headers)` (alias: `setHeaders`)
 - `setResponseHeader(event, name, value)` (alias: `setHeader`)
 - `appendResponseHeaders(event, headers)` (alias: `appendHeaders`)
 - `appendResponseHeader(event, name, value)` (alias: `appendHeader`)
-- `writeEarlyHints(event, links, callback)`
+- `defaultContentType(event, type)`
+- `sendRedirect(event, location, code=302)`
+- `isStream(data)`
 - `sendStream(event, data)`
+- `writeEarlyHints(event, links, callback)`
+
+#### Sanitize
+
+- `sanitizeStatusMessage(statusMessage)`
+- `sanitizeStatusCode(statusCode, default = 200)`
+
+#### Error
+
 - `sendError(event, error, debug?)`
-- `getMethod(event, default?)`
-- `isMethod(event, expected, allowHead?)`
-- `assertMethod(event, expected, allowHead?)`
 - `createError({ statusCode, statusMessage, data? })`
+
+#### Route
+
+- `useBase(base, handler)`
+
+#### Proxy
+
 - `sendProxy(event, { target, ...options })`
 - `proxyRequest(event, { target, ...options })`
 - `fetchWithEvent(event, req, init, { fetch? }?)`
 - `getProxyRequestHeaders(event)`
-- `sendNoContent(event, code = 204)`
-- `setResponseStatus(event, status)`
-- `getResponseStatus(event)`
-- `getResponseStatusText(event)`
-- `readMultipartFormData(event)`
+
+#### Cookie
+
+- `parseCookies(event)`
+- `getCookie(event, name)`
+- `setCookie(event, name, value, opts?)`
+- `deleteCookie(event, name, opts?)`
+- `splitCookiesString(cookiesString)`
+
+#### Session
+
 - `useSession(event, config = { password, maxAge?, name?, cookie?, seal?, crypto? })`
 - `getSession(event, config)`
 - `updateSession(event, config, update)`
-- `clearSession(event, config)`
 - `sealSession(event, config)`
 - `unsealSession(event, config, sealed)`
+- `clearSession(event, config)`
+
+#### Cache
+
+- `handleCacheHeaders(event, opts)`
+
+#### Cors
+
 - `handleCors(options)` (see [h3-cors](https://github.com/NozomuIkuta/h3-cors) for more detail about options)
 - `isPreflightRequest(event)`
 - `isCorsOriginAllowed(event)`
 - `appendCorsHeaders(event, options)` (see [h3-cors](https://github.com/NozomuIkuta/h3-cors) for more detail about options)
 - `appendCorsPreflightHeaders(event, options)` (see [h3-cors](https://github.com/NozomuIkuta/h3-cors) for more detail about options)
-- `getRequestHost(event)`
-- `getRequestProtocol(event)`
-- `getRequestURL(event)`
-
-👉 You can learn more about usage in [JSDocs Documentation](https://www.jsdocs.io/package/h3#package-functions).
 
 ## Community Packages