h3 1.0.0 → 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Pooya Parsa <pooya@pi0.io>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,38 +1,164 @@
-# h3-js
+[![npm downloads](https://img.shields.io/npm/dm/h3.svg?style=flat-square)](https://npmjs.com/package/h3)
+[![version](https://img.shields.io/npm/v/h3/latest.svg?style=flat-square)](https://npmjs.com/package/h3)
+[![bundlephobia](https://img.shields.io/bundlephobia/min/h3/latest.svg?style=flat-square)](https://bundlephobia.com/result?p=h3)
+[![build status](https://img.shields.io/github/workflow/status/unjs/h3/ci/main?style=flat-square)](https://github.com/unjs/h3/actions)
+[![coverage](https://img.shields.io/codecov/c/gh/unjs/h3/main?style=flat-square)](https://codecov.io/gh/unjs/h3)
+[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue?style=flat-square)](https://www.jsdocs.io/package/h3)
 
-A better HTMLElement constructor
+> H3 is a minimal h(ttp) framework built for high performance and portability
 
-## Example
+<!-- ![h3 - Tiny JavaScript Server](.github/banner.svg) -->
 
-```javascript
-var body = h('div', 'example',
-  h('h1', null, 'Example'),
-  h('label', {htmlFor: 'task'},
-    h('input', {id: 'task', type: 'checkbox', checked: true}),
-    'Check out h3-js'
-  )
-);
+## Features
+
+✔️ &nbsp;**Portable:** Works perfectly in Serverless, Workers, and Node.js
+
+✔️ &nbsp;**Minimal:** Small and tree-shakable
+
+✔️ &nbsp;**Modern:** Native promise support
+
+✔️ &nbsp;**Extendable:** Ships with a set of composable utilities but can be extended
+
+✔️ &nbsp;**Router:** Super fast route matching using [unjs/radix3](https://github.com/unjs/radix3)
+
+✔️ &nbsp;**Compatible:** Compatibility layer with node/connect/express middleware
+
+## Install
+
+```bash
+# Using npm
+npm install h3
+
+# Using yarn
+yarn add h3
+
+# Using pnpm
+pnpm add h3
 ```
 
-## API
+## Usage
+
+```ts
+import { createServer } from 'http'
+import { createApp, eventHandler, toNodeListener } from 'h3'
+
+const app = createApp()
+app.use('/', eventHandler(() => 'Hello world!'))
+
+createServer(toNodeListener(app)).listen(process.env.PORT || 3000)
+```
+
+<details>
+ <summary>Example using <a href="https://github.com/unjs/listhen">listhen</a> for an elegant listener.</summary>
+
+```ts
+import { createApp, toNodeListener } from 'h3'
+import { listen } from 'listhen'
+
+const app = createApp()
+app.use('/', eventHandler(() => 'Hello world!'))
+
+listen(toNodeListener(app))
+```
+</details>
+
+## Router
+
+The `app` instance created by `h3` uses a middleware stack (see [how it works](#how-it-works)) with the ability to match route prefix and apply matched middleware.
+
+To opt-in using a more advanced and convenient routing system, we can create a router instance and register it to app instance.
+
+```ts
+import { createApp, eventHandler, createRouter } from 'h3'
+
+const app = createApp()
+
+const router = createRouter()
+ .get('/', eventHandler(() => 'Hello World!'))
+ .get('/hello/:name', eventHandler(event => `Hello ${event.context.params.name}!`))
+
+app.use(router)
+```
+
+**Tip:** We can register same route more than once with different methods.
+
+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).
+
+## More app usage examples
+
+```js
+// Handle can directly return object or Promise<object> for JSON response
+app.use('/api', eventHandler((event) => ({ url: event.node.req.url }))
+
+// We can have better matching other than quick prefix match
+app.use('/odd', eventHandler(() => 'Is odd!'), { match: url => url.substr(1) % 2 })
+
+// Handle can directly return string for HTML response
+app.use(eventHandler(() => '<h1>Hello world!</h1>'))
+
+// We can chain calls to .use()
+app.use('/1', eventHandler(() => '<h1>Hello world!</h1>'))
+   .use('/2', eventHandler(() => '<h1>Goodbye!</h1>'))
+
+// Legacy middleware with 3rd argument are automatically promisified
+app.use(fromNodeMiddleware((req, res, next) => { req.setHeader('x-foo', 'bar'); next() }))
+
+// Lazy loaded routes using { lazy: true }
+app.use('/big', () => import('./big-handler'), { lazy: true })
+```
+
+## Utilities
+
+H3 has concept of compasable utilities that accept `event` (from `eventHandler((event) => {})`) as their first argument. This has several performance benefits over injecting them to `event` or `app` instances and global middleware commonly used in Node.js frameworks such as Express, which Only required code is evaluated and bundled and rest of utils can be tree-shaken when not used.
+
+### Built-in
+
+- `readRawBody(event, encoding?)`
+- `readBody(event)`
+- `parseCookies(event)`
+- `getCookie(event, name)`
+- `setCookie(event, name, value, opts?)`
+- `deleteCookie(event, name, opts?)`
+- `getQuery(event)`
+- `getRouterParams(event)`
+- `send(event, data, type?)`
+- `sendRedirect(event, location, code=302)`
+- `getRequestHeaders(event, headers)` (alias: `getHeaders`)
+- `getRequestHeader(event, name)` (alias: `getHeader`)
+- `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)`
+- `sendStream(event, data)`
+- `sendError(event, error, debug?)`
+- `getMethod(event, default?)`
+- `isMethod(event, expected, allowHead?)`
+- `assertMethod(event, expected, allowHead?)`
+- `createError({ statusCode, statusMessage, data? })`
+- `sendProxy(event, { target, headers?, fetchOptions?, fetch?, sendStream? })`
+- `proxyRequest(event, { target, headers?, fetchOptions?, fetch?, sendStream? })`
 
-### h(tagName, props, ...children)
+👉 You can learn more about usage in [JSDocs Documentation](https://www.jsdocs.io/package/h3#package-functions).
 
-Creates and returns a new HTMLElement.
+## Community Packages
 
-Primary interface: `tagName` sets the tag name, each key-value pair of `props` is copied onto the result, and each of `children` is appended to the result.
+You can use more h3 event utilities made by the community.
 
-Conveniences:
+Please check their READMEs for more details.
 
-- `props.style` sets `result.style.cssText`
-- If `props` is falsy then it is ignored
-- If `props` is a string then it instead sets `result.className`
-- Children that are falsy are ignored
-- Children that are strings are converted to `Text` instances
-- Children that are Arrays are flattened into `children`
+PRs are welcome to add your packages.
 
-## Setup
+- [h3-cors](https://github.com/NozomuIkuta/h3-cors)
+  - `defineCorsEventHandler(options)`
+  - `isPreflight(event)`
+- [h3-typebox](https://github.com/kevinmarrec/h3-typebox)
+  - `validateBody(event, schema)`
+  - `validateQuery(event, schema)`
+- [h3-zod](https://github.com/wobsoriano/h3-zod)
+  - `useValidatedBody(event, schema)`
+  - `useValidatedQuery(event, schema)`
 
-Install: `npm install h3`
+## License
 
-Import: `const h = require('h3');`
+MIT