h3 0.2.12 → 0.3.3

package/README.md

@@ -1,24 +1,25 @@
-[![d](https://img.shields.io/npm/dm/h3.svg?style=flat-square)](https://npmjs.com/package/h3)
-[![v](https://img.shields.io/npm/v/h3/latest.svg?style=flat-square)](https://npmjs.com/package/h3)
-[![b](https://img.shields.io/bundlephobia/min/h3/latest.svg?style=flat-square)](https://bundlephobia.com/result?p=h3)
-[![a](https://img.shields.io/github/workflow/status/unjs/h3/ci/main?style=flat-square)](https://github.com/unjs/h3/actions)
-[![c](https://img.shields.io/codecov/c/gh/unjs/h3/main?style=flat-square)](https://codecov.io/gh/unjs/h3)
+[![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)
 
 > H3 is a minimal h(ttp) framework built for high performance and portability
 
 <!-- ![h3 - Tiny JavaScript Server](.github/banner.svg) -->
 
-**Features**
+## Features
 
-✔️ **Portable:** Works perfectly in Serverless, Workers, and Node.js
+✔️ &nbsp;**Portable:** Works perfectly in Serverless, Workers, and Node.js
 
-✔️ **Compatible:** Support connect/express middleware
+✔️ &nbsp;**Compatible:** Support connect/express middleware
 
-✔️ **Minimal:** Small, tree-shakable and zero-dependency
+✔️ &nbsp;**Minimal:** Small, tree-shakable and zero-dependency
 
-✔️ **Modern:** Native promise support
+✔️ &nbsp;**Modern:** Native promise support
 
-✔️**Extendable:** Ships with a set of composable utilities but can be extended
+✔️ &nbsp;**Extendable:** Ships with a set of composable utilities but can be extended
 
 ## Install
 
@@ -37,31 +38,46 @@ import { createServer } from 'http'
 import { createApp } from 'h3'
 
 const app = createApp()
-app.useAsync('/', () => 'Hello world!')
+app.use('/', () => 'Hello world!')
 
-listen(app)
+createServer(app).listen(process.env.PORT || 3000)
 ```
 
-**Tip:** you may try [listhen](https://github.com/unjs/listhen) for a more elegant and advanced listener.
+<details>
+ <summary>Example using <a href="https://github.com/unjs/listhen">listhen</a> for an elegant listener.</summary>
+
+```ts
+import { createApp } from 'h3'
+import { listen } from 'listhen'
+
+const app = createApp()
+app.use('/', () => 'Hello world!')
+
+listen(app)
+```
+</details>
 
 ## Examples
 
 ```js
 // Handle can directly return object or Promise<object> for JSON response
-app.useAsync('/api', (req) => ({ url: req.url }))
+app.use('/api', (req) => ({ url: req.url }))
 
 // We can have better matching other than quick prefix match
-app.useAsync('/odd', () => 'Is odd!', { match: url => url.substr(1) % 2 })
+app.use('/odd', () => 'Is odd!', { match: url => url.substr(1) % 2 })
 
 // Handle can directly return string for HTML response
-app.useAsync(() => '<h1>Hello world!</h1>')
+app.use(() => '<h1>Hello world!</h1>')
 
 // We can chain calls to .use()
-app.useAsync('/1', () => '<h1>Hello world!</h1>')
-   .useAsync('/2', () => '<h1>Goodbye!</h1>')
+app.use('/1', () => '<h1>Hello world!</h1>')
+   .use('/2', () => '<h1>Goodbye!</h1>')
 
-// Promisify middleware before register: (supporting (req, res, next) format)
-// app.use(async () => {})
+// Legacy middleware with 3rd argument are automatically promisified
+app.use((req, res, next) => { req.setHeader('X-Foo', 'bar'); next() })
+
+// Force promisify a legacy middleware
+// app.use(someMiddleware, { promisify: true })
 
 // Lazy loaded routes using { lazy: true }
 // app.use('/big', () => import('./big'), { lazy: true })
@@ -75,7 +91,7 @@ Instead of adding helpers to `req` and `res`, h3 exposes them as composable util
 - `useBody(req)`
 - `useCookies(req)`
 - `useCookie(req, name)`
-- `setCookie(req, name, value, opts?)`
+- `setCookie(res, name, value, opts?)`
 - `useQuery(req)`
 - `send(res, data, type?)`
 - `sendRedirect(res, location, code=302)`
@@ -83,18 +99,20 @@ Instead of adding helpers to `req` and `res`, h3 exposes them as composable util
 - `createError({ statusCode, statusMessage, data? }`
 - `sendError(res, error, debug?)`
 
+👉 You can learn more about usage in [JSDocs Documentation](https://www.jsdocs.io/package/h3#package-functions).
+
 ## How it works?
 
-Using `createApp`, it returns a standard `(req, res)` handler function and internally an array called middleware stack. `useAsync()` and `use()` methods are helpers to add an item to this internal stack.
+Using `createApp`, it returns a standard `(req, res)` handler function and internally an array called middleware stack. using`use()` method we can add an item to this internal stack.
 
 When a request comes, each stack item that matches the route will be called and resolved until [`res.writableEnded`](https://nodejs.org/api/http.html#http_response_writableended) flag is set, which means the response is sent. If `writableEnded` is not set after all middleware, a `404` error will be thrown. And if one of the stack items resolves to a value, it will be serialized and sent as response as a shorthand method to sending responses.
 
-For maximum compatibility with connect/express middleware (`req, res, next?` signature), when using `use` instead of `useAsync`, it converts classic middleware into a promisified version ready to use with stack runner:
+For maximum compatibility with connect/express middleware (`req, res, next?` signature), h3 converts classic middleware into a promisified version ready to use with stack runner:
 
-- If middleware has 3rd next/callback param, promise will `resolve/reject` when called
+- If middleware has 3rd next/callback param, the promise will `resolve/reject` when called
 - If middleware returns a promise, it will be **chained** to the main promise
-- If calling middleware throws an immediate error, promise will be rejected
-- On `close` and `error` events of res, promise will `resolve/reject` (to ensure if middleware simply calls `res.end`)
+- If calling middleware throws an immediate error, the promise will be rejected
+- On `close` and `error` events of res, the promise will `resolve/reject` (to ensure if middleware simply calls `res.end`)
 
 ## License
 

package/dist/index.cjs

@@ -124,7 +124,7 @@ function callHandle(handle, req, res) {
     }
   });
 }
-function lazyHandle(handle, promisify = true) {
+function lazyHandle(handle, promisify) {
   let _promise;
   const resolve = () => {
     if (!_promise) {
@@ -447,7 +447,7 @@ function defaultContentType(res, type) {
 function sendRedirect(res, location, code = 302) {
   res.statusCode = code;
   res.setHeader("Location", location);
-  send(res, "Redirecting to " + location, MIMES.html);
+  return send(res, "Redirecting to " + location, MIMES.html);
 }
 function appendHeader(res, name, value) {
   let current = res.getHeader(name);
@@ -528,7 +528,7 @@ function sendError(res, error, debug) {
 
 function createApp(options = {}) {
   const stack = [];
-  const _handle = createHandle(stack);
+  const _handle = createHandle(stack, options);
   const app = function(req, res) {
     return _handle(req, res).catch((error) => {
       if (options.onError) {
@@ -540,7 +540,6 @@ function createApp(options = {}) {
   app.stack = stack;
   app._handle = _handle;
   app.use = (arg1, arg2, arg3) => use(app, arg1, arg2, arg3);
-  app.useAsync = (arg1, arg2, arg3) => use(app, arg1, arg2 !== void 0 ? arg2 : { ...arg3, promisify: false }, { ...arg3, promisify: false });
   return app;
 }
 function use(app, arg1, arg2, arg3) {
@@ -557,7 +556,8 @@ function use(app, arg1, arg2, arg3) {
   }
   return app;
 }
-function createHandle(stack) {
+function createHandle(stack, options) {
+  const spacing = options.debug ? 2 : void 0;
   return async function handle(req, res) {
     req.originalUrl = req.originalUrl || req.url || "/";
     const reqUrl = req.url || "/";
@@ -581,10 +581,12 @@ function createHandle(stack) {
       if (type === "string") {
         return send(res, val, MIMES.html);
       } else if (type === "object" && val !== void 0) {
-        if (val.buffer) {
+        if (val && val.buffer) {
           return send(res, val);
+        } else if (val instanceof Error) {
+          throw createError(val);
         } else {
-          return send(res, JSON.stringify(val, null, 2), MIMES.json);
+          return send(res, JSON.stringify(val, null, spacing), MIMES.json);
         }
       }
     }
@@ -594,10 +596,13 @@ function createHandle(stack) {
   };
 }
 function normalizeLayer(layer) {
+  if (layer.promisify === void 0) {
+    layer.promisify = layer.handle.length > 2;
+  }
   return {
     route: withoutTrailingSlash(layer.route).toLocaleLowerCase(),
     match: layer.match,
-    handle: layer.lazy ? lazyHandle(layer.handle, layer.promisify) : layer.promisify !== false ? promisifyHandle(layer.handle) : layer.handle
+    handle: layer.lazy ? lazyHandle(layer.handle, layer.promisify) : layer.promisify ? promisifyHandle(layer.handle) : layer.handle
   };
 }
 

package/dist/index.d.ts

@@ -3,8 +3,8 @@ import * as ufo from 'ufo';
 
 declare type Encoding = false | 'ascii' | 'utf8' | 'utf-8' | 'utf16le' | 'ucs2' | 'ucs-2' | 'base64' | 'latin1' | 'binary' | 'hex';
 
-declare type Handle = (req: IncomingMessage, res: ServerResponse) => any;
-declare type PHandle = (req: IncomingMessage, res: ServerResponse) => Promise<any>;
+declare type Handle<T = any> = (req: IncomingMessage, res: ServerResponse) => T;
+declare type PHandle = Handle<Promise<any>>;
 declare type Middleware = (req: IncomingMessage, res: ServerResponse, next: (err?: Error) => any) => any;
 declare type LazyHandle = () => Handle | Promise<Handle>;
 declare function promisifyHandle(handle: Handle | Middleware): PHandle;
@@ -28,13 +28,9 @@ interface InputLayer {
 declare type InputStack = InputLayer[];
 declare type Matcher = (url: string, req?: IncomingMessage) => boolean;
 interface AppUse {
-    (route: string | string[], handle: Middleware | Middleware[], options?: Partial<InputLayer & {
-        promisify: true;
-    }>): App;
+    (route: string | string[], handle: Middleware | Middleware[], options?: Partial<InputLayer>): App;
     (route: string | string[], handle: Handle | Handle[], options?: Partial<InputLayer>): App;
-    (handle: Middleware | Middleware[], options?: Partial<InputLayer & {
-        promisify: true;
-    }>): App;
+    (handle: Middleware | Middleware[], options?: Partial<InputLayer>): App;
     (handle: Handle | Handle[], options?: Partial<InputLayer>): App;
     (options: InputLayer): App;
 }
@@ -43,15 +39,14 @@ interface App {
     stack: Stack;
     _handle: PHandle;
     use: AppUse;
-    useAsync: AppUse;
 }
 interface AppOptions {
     debug?: boolean;
     onError?: (error: Error, req: IncomingMessage, res: ServerResponse) => any;
 }
 declare function createApp(options?: AppOptions): App;
-declare function use(app: App, arg1: string | Handle | InputLayer | InputLayer[], arg2?: Handle | Partial<InputLayer> | Handle[], arg3?: Partial<InputLayer>): App;
-declare function createHandle(stack: Stack): PHandle;
+declare function use(app: App, arg1: string | Handle | InputLayer | InputLayer[], arg2?: Handle | Partial<InputLayer> | Handle[] | Middleware | Middleware[], arg3?: Partial<InputLayer>): App;
+declare function createHandle(stack: Stack, options: AppOptions): PHandle;
 
 /**
  * H3 Runtime Error
@@ -89,20 +84,22 @@ declare function sendError(res: ServerResponse, error: Error | H3Error, debug?:
 
 /**
  * Reads body of the request and returns encoded raw string (default) or `Buffer` if encoding if falsy.
- * @param req {IncomingMessage} An IncomingMessage object is created by
- *  <a href="https://nodejs.org/api/http.html#http_class_http_server">http.Server</a>
+ * @param req {IncomingMessage} An IncomingMessage object is created by [http.Server](https://nodejs.org/api/http.html#http_class_http_server)
  * @param encoding {Encoding} encoding="utf-8" - The character encoding to use.
  *
  * @return {String|Buffer} Encoded raw string or raw Buffer of the body
  */
 declare function useRawBody(req: IncomingMessage, encoding?: Encoding): Encoding extends false ? Buffer : Promise<string>;
 /**
- * Reads request body and try to safely parse using {@link https://github.com/unjs/destr destr}
- * @param req {IncomingMessage} An IncomingMessage object is created by
- *  <a href="https://nodejs.org/api/http.html#http_class_http_server">http.Server</a>
+ * Reads request body and try to safely parse using [destr](https://github.com/unjs/destr)
+ * @param req {IncomingMessage} An IncomingMessage object created by [http.Server](https://nodejs.org/api/http.html#http_class_http_server)
  * @param encoding {Encoding} encoding="utf-8" - The character encoding to use.
  *
- * @return {*} The Object, Array, string, number, boolean, or null value corresponding to the request JSON body
+ * @return {*} The `Object`, `Array`, `String`, `Number`, `Boolean`, or `null` value corresponding to the request JSON body
+ *
+ * ```ts
+ * const body = await useBody(req)
+ * ```
  */
 declare function useBody<T = any>(req: IncomingMessage): Promise<T>;
 
@@ -197,15 +194,42 @@ interface CookieSerializeOptions {
     secure?: boolean;
 }
 
+/**
+ * Parse the request to get HTTP Cookie header string and returning an object of all cookie name-value pairs.
+ * @param req {IncomingMessage} An IncomingMessage object created by [http.Server](https://nodejs.org/api/http.html#http_class_http_server)
+ * @returns Object of cookie name-value pairs
+ * ```ts
+ * const cookies = useCookies(req)
+ * ```
+ */
 declare function useCookies(req: IncomingMessage): Record<string, string>;
+/**
+ * Get a cookie value by name.
+ * @param req {IncomingMessage} An IncomingMessage object created by [http.Server](https://nodejs.org/api/http.html#http_class_http_server)
+ * @param name Name of the cookie to get
+ * @returns {*} Value of the cookie (String or undefined)
+ * ```ts
+ * const authorization = useCookie(request, 'Authorization')
+ * ```
+ */
 declare function useCookie(req: IncomingMessage, name: string): string | undefined;
-declare function setCookie(res: ServerResponse, name: string, value: string, serializeOptions: CookieSerializeOptions): void;
+/**
+ * Set a cookie value by name.
+ * @param res {ServerResponse} A ServerResponse object created by [http.Server](https://nodejs.org/api/http.html#http_class_http_server)
+ * @param name Name of the cookie to set
+ * @param value Value of the cookie to set
+ * @param serializeOptions {CookieSerializeOptions} Options for serializing the cookie
+ * ```ts
+ * setCookie(res, 'Authorization', '1234567')
+ * ```
+ */
+declare function setCookie(res: ServerResponse, name: string, value: string, serializeOptions?: CookieSerializeOptions): void;
 
 declare function useQuery(req: IncomingMessage): ufo.QueryObject;
 
 declare function send(res: ServerResponse, data: any, type?: string): Promise<unknown>;
 declare function defaultContentType(res: ServerResponse, type?: string): void;
-declare function sendRedirect(res: ServerResponse, location: string, code?: number): void;
+declare function sendRedirect(res: ServerResponse, location: string, code?: number): Promise<unknown>;
 declare function appendHeader(res: ServerResponse, name: string, value: string): void;
 
 export { App, AppOptions, AppUse, H3Error, Handle, InputLayer, InputStack, Layer, LazyHandle, MIMES, Matcher, Middleware, PHandle, Stack, appendHeader, callHandle, createApp, createError, createHandle, defaultContentType, lazyHandle, promisifyHandle, send, sendError, sendRedirect, setCookie, use, useBase, useBody, useCookie, useCookies, useQuery, useRawBody };

package/dist/index.mjs

@@ -120,7 +120,7 @@ function callHandle(handle, req, res) {
     }
   });
 }
-function lazyHandle(handle, promisify = true) {
+function lazyHandle(handle, promisify) {
   let _promise;
   const resolve = () => {
     if (!_promise) {
@@ -443,7 +443,7 @@ function defaultContentType(res, type) {
 function sendRedirect(res, location, code = 302) {
   res.statusCode = code;
   res.setHeader("Location", location);
-  send(res, "Redirecting to " + location, MIMES.html);
+  return send(res, "Redirecting to " + location, MIMES.html);
 }
 function appendHeader(res, name, value) {
   let current = res.getHeader(name);
@@ -524,7 +524,7 @@ function sendError(res, error, debug) {
 
 function createApp(options = {}) {
   const stack = [];
-  const _handle = createHandle(stack);
+  const _handle = createHandle(stack, options);
   const app = function(req, res) {
     return _handle(req, res).catch((error) => {
       if (options.onError) {
@@ -536,7 +536,6 @@ function createApp(options = {}) {
   app.stack = stack;
   app._handle = _handle;
   app.use = (arg1, arg2, arg3) => use(app, arg1, arg2, arg3);
-  app.useAsync = (arg1, arg2, arg3) => use(app, arg1, arg2 !== void 0 ? arg2 : { ...arg3, promisify: false }, { ...arg3, promisify: false });
   return app;
 }
 function use(app, arg1, arg2, arg3) {
@@ -553,7 +552,8 @@ function use(app, arg1, arg2, arg3) {
   }
   return app;
 }
-function createHandle(stack) {
+function createHandle(stack, options) {
+  const spacing = options.debug ? 2 : void 0;
   return async function handle(req, res) {
     req.originalUrl = req.originalUrl || req.url || "/";
     const reqUrl = req.url || "/";
@@ -577,10 +577,12 @@ function createHandle(stack) {
       if (type === "string") {
         return send(res, val, MIMES.html);
       } else if (type === "object" && val !== void 0) {
-        if (val.buffer) {
+        if (val && val.buffer) {
           return send(res, val);
+        } else if (val instanceof Error) {
+          throw createError(val);
         } else {
-          return send(res, JSON.stringify(val, null, 2), MIMES.json);
+          return send(res, JSON.stringify(val, null, spacing), MIMES.json);
         }
       }
     }
@@ -590,10 +592,13 @@ function createHandle(stack) {
   };
 }
 function normalizeLayer(layer) {
+  if (layer.promisify === void 0) {
+    layer.promisify = layer.handle.length > 2;
+  }
   return {
     route: withoutTrailingSlash(layer.route).toLocaleLowerCase(),
     match: layer.match,
-    handle: layer.lazy ? lazyHandle(layer.handle, layer.promisify) : layer.promisify !== false ? promisifyHandle(layer.handle) : layer.handle
+    handle: layer.lazy ? lazyHandle(layer.handle, layer.promisify) : layer.promisify ? promisifyHandle(layer.handle) : layer.handle
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "h3",
-  "version": "0.2.12",
+  "version": "0.3.3",
   "description": "Tiny JavaScript Server",
   "repository": "unjs/h3",
   "license": "MIT",