h3 0.3.2 → 0.3.6

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
 
@@ -42,7 +43,19 @@ app.use('/', () => 'Hello world!')
 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
 
@@ -85,6 +98,13 @@ Instead of adding helpers to `req` and `res`, h3 exposes them as composable util
 - `appendHeader(res, name, value)`
 - `createError({ statusCode, statusMessage, data? }`
 - `sendError(res, error, debug?)`
+- `defineHandle(handle)`
+- `defineMiddleware(middlware)`
+- `useMethod(req, default?)`
+- `isMethod(req, expected, allowHead?)`
+- `assertMethod(req, expected, allowHead?)`
+
+👉 You can learn more about usage in [JSDocs Documentation](https://www.jsdocs.io/package/h3#package-functions).
 
 ## How it works?
 

package/dist/index.cjs

@@ -83,8 +83,8 @@ function parseURL(input = "", defaultProto) {
     return defaultProto ? parseURL(defaultProto + input) : parsePath(input);
   }
   const [protocol = "", auth, hostAndPath] = (input.match(/([^:/]+:)?\/\/([^/@]+@)?(.*)/) || []).splice(1);
-  const [host = "", path = ""] = (hostAndPath.match(/([^/]*)(.*)?/) || []).splice(1);
-  const {pathname, search, hash} = parsePath(path);
+  const [host = "", path = ""] = (hostAndPath.match(/([^/?]*)(.*)?/) || []).splice(1);
+  const { pathname, search, hash } = parsePath(path);
   return {
     protocol,
     auth: auth ? auth.substr(0, auth.length - 1) : "",
@@ -103,6 +103,8 @@ function parsePath(input = "") {
   };
 }
 
+const defineHandle = (handler) => handler;
+const defineMiddleware = (middleware) => middleware;
 function promisifyHandle(handle) {
   return function(req, res) {
     return callHandle(handle, req, res);
@@ -193,26 +195,61 @@ function destr(val) {
   }
 }
 
+function useQuery(req) {
+  return getQuery(req.url || "");
+}
+function useMethod(req, defaultMethod = "GET") {
+  return (req.method || defaultMethod).toUpperCase();
+}
+function isMethod(req, expected, allowHead) {
+  const method = useMethod(req);
+  if (allowHead && method === "HEAD") {
+    return true;
+  }
+  if (typeof expected === "string") {
+    if (method === expected) {
+      return true;
+    }
+  } else if (expected.includes(method)) {
+    return true;
+  }
+  return false;
+}
+function assertMethod(req, expected, allowHead) {
+  if (!isMethod(req, expected, allowHead)) {
+    throw createError({
+      statusCode: 405,
+      statusMessage: "HTTP method is not allowed."
+    });
+  }
+}
+
 const RawBodySymbol = Symbol("h3RawBody");
 const ParsedBodySymbol = Symbol("h3RawBody");
+const PayloadMethods = ["PATCH", "POST", "PUT"];
 function useRawBody(req, encoding = "utf-8") {
-  if (req[RawBodySymbol]) {
-    return Promise.resolve(encoding ? req[RawBodySymbol].toString(encoding) : req[RawBodySymbol]);
+  assertMethod(req, PayloadMethods);
+  if (RawBodySymbol in req) {
+    const promise2 = Promise.resolve(req[RawBodySymbol]);
+    return encoding ? promise2.then((buff) => buff.toString(encoding)) : promise2;
   }
-  return new Promise((resolve, reject) => {
+  if ("_body" in req) {
+    return Promise.resolve(req._body);
+  }
+  const promise = req[RawBodySymbol] = new Promise((resolve, reject) => {
     const bodyData = [];
     req.on("error", (err) => {
       reject(err);
     }).on("data", (chunk) => {
       bodyData.push(chunk);
     }).on("end", () => {
-      req[RawBodySymbol] = Buffer.concat(bodyData);
-      resolve(encoding ? req[RawBodySymbol].toString(encoding) : req[RawBodySymbol]);
+      resolve(Buffer.concat(bodyData));
     });
   });
+  return encoding ? promise.then((buff) => buff.toString(encoding)) : promise;
 }
 async function useBody(req) {
-  if (req[ParsedBodySymbol]) {
+  if (ParsedBodySymbol in req) {
     return req[ParsedBodySymbol];
   }
   const body = await useRawBody(req);
@@ -346,11 +383,7 @@ function serialize(name, val, options) {
 
   if (null != opt.maxAge) {
     var maxAge = opt.maxAge - 0;
-
-    if (isNaN(maxAge) || !isFinite(maxAge)) {
-      throw new TypeError('option maxAge is invalid')
-    }
-
+    if (isNaN(maxAge)) throw new Error('maxAge should be a Number');
     str += '; Max-Age=' + Math.floor(maxAge);
   }
 
@@ -472,10 +505,6 @@ function setCookie(res, name, value, serializeOptions) {
   appendHeader(res, "Set-Cookie", cookieStr);
 }
 
-function useQuery(req) {
-  return getQuery(req.url || "");
-}
-
 class H3Error extends Error {
   constructor() {
     super(...arguments);
@@ -609,11 +638,15 @@ function normalizeLayer(layer) {
 exports.H3Error = H3Error;
 exports.MIMES = MIMES;
 exports.appendHeader = appendHeader;
+exports.assertMethod = assertMethod;
 exports.callHandle = callHandle;
 exports.createApp = createApp;
 exports.createError = createError;
 exports.createHandle = createHandle;
 exports.defaultContentType = defaultContentType;
+exports.defineHandle = defineHandle;
+exports.defineMiddleware = defineMiddleware;
+exports.isMethod = isMethod;
 exports.lazyHandle = lazyHandle;
 exports.promisifyHandle = promisifyHandle;
 exports.send = send;
@@ -625,5 +658,6 @@ exports.useBase = useBase;
 exports.useBody = useBody;
 exports.useCookie = useCookie;
 exports.useCookies = useCookies;
+exports.useMethod = useMethod;
 exports.useQuery = useQuery;
 exports.useRawBody = useRawBody;

package/dist/index.d.ts

@@ -7,6 +7,8 @@ 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 const defineHandle: <T>(handler: Handle<T>) => Handle<T>;
+declare const defineMiddleware: (middleware: Middleware) => Middleware;
 declare function promisifyHandle(handle: Handle | Middleware): PHandle;
 declare function callHandle(handle: Middleware, req: IncomingMessage, res: ServerResponse): Promise<unknown>;
 declare function lazyHandle(handle: LazyHandle, promisify?: boolean): PHandle;
@@ -82,24 +84,32 @@ declare function createError(input: Partial<H3Error>): H3Error;
  */
 declare function sendError(res: ServerResponse, error: Error | H3Error, debug?: boolean): void;
 
+declare const RawBodySymbol: unique symbol;
+interface _IncomingMessage extends IncomingMessage {
+    [RawBodySymbol]?: Promise<Buffer>;
+    ParsedBodySymbol?: any;
+    _body?: any;
+}
 /**
  * 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>;
+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>;
+declare function useBody<T = any>(req: _IncomingMessage): Promise<T>;
 
 declare const MIMES: {
     html: string;
@@ -192,15 +202,46 @@ 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 type HTTPMethod = 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'CONNECT' | 'OPTIONS' | 'TRACE';
+declare function useMethod(req: IncomingMessage, defaultMethod?: HTTPMethod): HTTPMethod;
+declare function isMethod(req: IncomingMessage, expected: HTTPMethod | HTTPMethod[], allowHead?: boolean): boolean;
+declare function assertMethod(req: IncomingMessage, expected: HTTPMethod | HTTPMethod[], allowHead?: boolean): void;
 
 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): 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 };
+export { App, AppOptions, AppUse, H3Error, HTTPMethod, Handle, InputLayer, InputStack, Layer, LazyHandle, MIMES, Matcher, Middleware, PHandle, Stack, appendHeader, assertMethod, callHandle, createApp, createError, createHandle, defaultContentType, defineHandle, defineMiddleware, isMethod, lazyHandle, promisifyHandle, send, sendError, sendRedirect, setCookie, use, useBase, useBody, useCookie, useCookies, useMethod, useQuery, useRawBody };

package/dist/index.mjs

@@ -79,8 +79,8 @@ function parseURL(input = "", defaultProto) {
     return defaultProto ? parseURL(defaultProto + input) : parsePath(input);
   }
   const [protocol = "", auth, hostAndPath] = (input.match(/([^:/]+:)?\/\/([^/@]+@)?(.*)/) || []).splice(1);
-  const [host = "", path = ""] = (hostAndPath.match(/([^/]*)(.*)?/) || []).splice(1);
-  const {pathname, search, hash} = parsePath(path);
+  const [host = "", path = ""] = (hostAndPath.match(/([^/?]*)(.*)?/) || []).splice(1);
+  const { pathname, search, hash } = parsePath(path);
   return {
     protocol,
     auth: auth ? auth.substr(0, auth.length - 1) : "",
@@ -99,6 +99,8 @@ function parsePath(input = "") {
   };
 }
 
+const defineHandle = (handler) => handler;
+const defineMiddleware = (middleware) => middleware;
 function promisifyHandle(handle) {
   return function(req, res) {
     return callHandle(handle, req, res);
@@ -189,26 +191,61 @@ function destr(val) {
   }
 }
 
+function useQuery(req) {
+  return getQuery(req.url || "");
+}
+function useMethod(req, defaultMethod = "GET") {
+  return (req.method || defaultMethod).toUpperCase();
+}
+function isMethod(req, expected, allowHead) {
+  const method = useMethod(req);
+  if (allowHead && method === "HEAD") {
+    return true;
+  }
+  if (typeof expected === "string") {
+    if (method === expected) {
+      return true;
+    }
+  } else if (expected.includes(method)) {
+    return true;
+  }
+  return false;
+}
+function assertMethod(req, expected, allowHead) {
+  if (!isMethod(req, expected, allowHead)) {
+    throw createError({
+      statusCode: 405,
+      statusMessage: "HTTP method is not allowed."
+    });
+  }
+}
+
 const RawBodySymbol = Symbol("h3RawBody");
 const ParsedBodySymbol = Symbol("h3RawBody");
+const PayloadMethods = ["PATCH", "POST", "PUT"];
 function useRawBody(req, encoding = "utf-8") {
-  if (req[RawBodySymbol]) {
-    return Promise.resolve(encoding ? req[RawBodySymbol].toString(encoding) : req[RawBodySymbol]);
+  assertMethod(req, PayloadMethods);
+  if (RawBodySymbol in req) {
+    const promise2 = Promise.resolve(req[RawBodySymbol]);
+    return encoding ? promise2.then((buff) => buff.toString(encoding)) : promise2;
   }
-  return new Promise((resolve, reject) => {
+  if ("_body" in req) {
+    return Promise.resolve(req._body);
+  }
+  const promise = req[RawBodySymbol] = new Promise((resolve, reject) => {
     const bodyData = [];
     req.on("error", (err) => {
       reject(err);
     }).on("data", (chunk) => {
       bodyData.push(chunk);
     }).on("end", () => {
-      req[RawBodySymbol] = Buffer.concat(bodyData);
-      resolve(encoding ? req[RawBodySymbol].toString(encoding) : req[RawBodySymbol]);
+      resolve(Buffer.concat(bodyData));
     });
   });
+  return encoding ? promise.then((buff) => buff.toString(encoding)) : promise;
 }
 async function useBody(req) {
-  if (req[ParsedBodySymbol]) {
+  if (ParsedBodySymbol in req) {
     return req[ParsedBodySymbol];
   }
   const body = await useRawBody(req);
@@ -342,11 +379,7 @@ function serialize(name, val, options) {
 
   if (null != opt.maxAge) {
     var maxAge = opt.maxAge - 0;
-
-    if (isNaN(maxAge) || !isFinite(maxAge)) {
-      throw new TypeError('option maxAge is invalid')
-    }
-
+    if (isNaN(maxAge)) throw new Error('maxAge should be a Number');
     str += '; Max-Age=' + Math.floor(maxAge);
   }
 
@@ -468,10 +501,6 @@ function setCookie(res, name, value, serializeOptions) {
   appendHeader(res, "Set-Cookie", cookieStr);
 }
 
-function useQuery(req) {
-  return getQuery(req.url || "");
-}
-
 class H3Error extends Error {
   constructor() {
     super(...arguments);
@@ -602,4 +631,4 @@ function normalizeLayer(layer) {
   };
 }
 
-export { H3Error, MIMES, appendHeader, callHandle, createApp, createError, createHandle, defaultContentType, lazyHandle, promisifyHandle, send, sendError, sendRedirect, setCookie, use, useBase, useBody, useCookie, useCookies, useQuery, useRawBody };
+export { H3Error, MIMES, appendHeader, assertMethod, callHandle, createApp, createError, createHandle, defaultContentType, defineHandle, defineMiddleware, isMethod, lazyHandle, promisifyHandle, send, sendError, sendRedirect, setCookie, use, useBase, useBody, useCookie, useCookies, useMethod, useQuery, useRawBody };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "h3",
-  "version": "0.3.2",
+  "version": "0.3.6",
   "description": "Tiny JavaScript Server",
   "repository": "unjs/h3",
   "license": "MIT",
@@ -21,8 +21,8 @@
     "build": "siroc build",
     "dev": "jiti test/playground",
     "lint": "eslint --ext ts .",
-    "release": "yarn test && yarn build && standard-version && npm publish && git push --follow-tags",
     "profile": "0x -o -D .profile -P 'autocannon -c 100 -p 10 -d 40 http://localhost:$PORT' ./hello.js",
+    "release": "yarn test && yarn build && standard-version && npm publish && git push --follow-tags",
     "test": "yarn lint && jest"
   },
   "devDependencies": {
@@ -35,11 +35,11 @@
     "@types/supertest": "latest",
     "autocannon": "latest",
     "connect": "latest",
-    "cookie": "latest",
+    "cookie-es": "latest",
     "destr": "latest",
     "eslint": "latest",
     "express": "latest",
-    "get-port": "latest",
+    "get-port": "^5.0.0",
     "jest": "latest",
     "jiti": "latest",
     "listhen": "latest",