h3 0.4.2 → 0.5.0

package/dist/index.mjs

@@ -3,34 +3,30 @@ import { createRouter as createRouter$1 } from 'radix3';
 import destr from 'destr';
 import { parse, serialize } from 'cookie-es';
 
-const defineHandle = (handler) => handler;
+const defineHandler = (handler) => handler;
+const defineHandle = defineHandler;
 const defineMiddleware = (middleware) => middleware;
-function promisifyHandle(handle) {
+function promisifyHandler(handler) {
   return function(req, res) {
-    return callHandle(handle, req, res);
+    return callHandler(handler, req, res);
   };
 }
-function callHandle(handle, req, res) {
+const promisifyHandle = promisifyHandler;
+function callHandler(handler, req, res) {
   return new Promise((resolve, reject) => {
     const next = (err) => err ? reject(err) : resolve(void 0);
     try {
-      const returned = handle(req, res, next);
-      if (returned !== void 0) {
-        resolve(returned);
-      } else {
-        res.once("close", next);
-        res.once("error", next);
-      }
+      return resolve(handler(req, res, next));
     } catch (err) {
       next(err);
     }
   });
 }
-function lazyHandle(handle, promisify) {
+function defineLazyHandler(handler, promisify) {
   let _promise;
   const resolve = () => {
     if (!_promise) {
-      _promise = Promise.resolve(handle()).then((r) => promisify ? promisifyHandle(r.default || r) : r.default || r);
+      _promise = Promise.resolve(handler()).then((r) => promisify ? promisifyHandler(r.default || r) : r.default || r);
     }
     return _promise;
   };
@@ -38,26 +34,84 @@ function lazyHandle(handle, promisify) {
     return resolve().then((h) => h(req, res));
   };
 }
-function useBase(base, handle) {
+const lazyHandle = defineLazyHandler;
+function useBase(base, handler) {
   base = withoutTrailingSlash(base);
   if (!base) {
-    return handle;
+    return handler;
   }
   return function(req, res) {
     req.originalUrl = req.originalUrl || req.url || "/";
     req.url = withoutBase(req.url || "/", base);
-    return handle(req, res);
+    return handler(req, res);
   };
 }
 
-function useQuery(req) {
-  return getQuery(req.url || "");
+function defineEventHandler(handler) {
+  handler.__is_handler__ = true;
+  return handler;
+}
+function defineLazyEventHandler(factory) {
+  let _promise;
+  let _resolved;
+  const resolveHandler = () => {
+    if (_resolved) {
+      return Promise.resolve(_resolved);
+    }
+    if (!_promise) {
+      _promise = Promise.resolve(factory()).then((r) => {
+        _resolved = r.default || r;
+        return _resolved;
+      });
+    }
+    return _promise;
+  };
+  return defineEventHandler((event) => {
+    if (_resolved) {
+      return _resolved(event);
+    }
+    return resolveHandler().then((handler) => handler(event));
+  });
+}
+function isEventHandler(input) {
+  return "__is_handler__" in input;
 }
-function useMethod(req, defaultMethod = "GET") {
-  return (req.method || defaultMethod).toUpperCase();
+function toEventHandler(handler) {
+  if (isEventHandler(handler)) {
+    return handler;
+  }
+  return defineEventHandler((event) => {
+    return callHandler(handler, event.req, event.res);
+  });
+}
+function createEvent(req, res) {
+  const event = {
+    __is_event__: true,
+    req,
+    res
+  };
+  event.event = event;
+  req.event = event;
+  req.req = req;
+  req.res = res;
+  res.event = event;
+  res.res = res;
+  res.req.res = res;
+  res.req.req = req;
+  return event;
 }
-function isMethod(req, expected, allowHead) {
-  const method = useMethod(req);
+function isEvent(input) {
+  return "__is_event__" in input;
+}
+
+function useQuery(event) {
+  return getQuery(event.req.url || "");
+}
+function useMethod(event, defaultMethod = "GET") {
+  return (event.req.method || defaultMethod).toUpperCase();
+}
+function isMethod(event, expected, allowHead) {
+  const method = useMethod(event);
   if (allowHead && method === "HEAD") {
     return true;
   }
@@ -70,8 +124,8 @@ function isMethod(req, expected, allowHead) {
   }
   return false;
 }
-function assertMethod(req, expected, allowHead) {
-  if (!isMethod(req, expected, allowHead)) {
+function assertMethod(event, expected, allowHead) {
+  if (!isMethod(event, expected, allowHead)) {
     throw createError({
       statusCode: 405,
       statusMessage: "HTTP method is not allowed."
@@ -82,18 +136,18 @@ function assertMethod(req, expected, allowHead) {
 const RawBodySymbol = Symbol("h3RawBody");
 const ParsedBodySymbol = Symbol("h3RawBody");
 const PayloadMethods = ["PATCH", "POST", "PUT", "DELETE"];
-function useRawBody(req, encoding = "utf-8") {
-  assertMethod(req, PayloadMethods);
-  if (RawBodySymbol in req) {
-    const promise2 = Promise.resolve(req[RawBodySymbol]);
+function useRawBody(event, encoding = "utf-8") {
+  assertMethod(event, PayloadMethods);
+  if (RawBodySymbol in event.req) {
+    const promise2 = Promise.resolve(event.req[RawBodySymbol]);
     return encoding ? promise2.then((buff) => buff.toString(encoding)) : promise2;
   }
-  if ("body" in req) {
-    return Promise.resolve(req.body);
+  if ("body" in event.req) {
+    return Promise.resolve(event.req.body);
   }
-  const promise = req[RawBodySymbol] = new Promise((resolve, reject) => {
+  const promise = event.req[RawBodySymbol] = new Promise((resolve, reject) => {
     const bodyData = [];
-    req.on("error", (err) => {
+    event.req.on("error", (err) => {
       reject(err);
     }).on("data", (chunk) => {
       bodyData.push(chunk);
@@ -103,13 +157,13 @@ function useRawBody(req, encoding = "utf-8") {
   });
   return encoding ? promise.then((buff) => buff.toString(encoding)) : promise;
 }
-async function useBody(req) {
-  if (ParsedBodySymbol in req) {
-    return req[ParsedBodySymbol];
+async function useBody(event) {
+  if (ParsedBodySymbol in event.req) {
+    return event.req[ParsedBodySymbol];
   }
-  const body = await useRawBody(req);
+  const body = await useRawBody(event);
   const json = destr(body);
-  req[ParsedBodySymbol] = json;
+  event.req[ParsedBodySymbol] = json;
   return json;
 }
 
@@ -119,61 +173,61 @@ const MIMES = {
 };
 
 const defer = typeof setImmediate !== "undefined" ? setImmediate : (fn) => fn();
-function send(res, data, type) {
+function send(event, data, type) {
   if (type) {
-    defaultContentType(res, type);
+    defaultContentType(event, type);
   }
   return new Promise((resolve) => {
     defer(() => {
-      res.end(data);
+      event.res.end(data);
       resolve(void 0);
     });
   });
 }
-function defaultContentType(res, type) {
-  if (type && !res.getHeader("Content-Type")) {
-    res.setHeader("Content-Type", type);
+function defaultContentType(event, type) {
+  if (type && !event.res.getHeader("Content-Type")) {
+    event.res.setHeader("Content-Type", type);
   }
 }
-function sendRedirect(res, location, code = 302) {
-  res.statusCode = code;
-  res.setHeader("Location", location);
-  return send(res, "Redirecting to " + location, MIMES.html);
+function sendRedirect(event, location, code = 302) {
+  event.res.statusCode = code;
+  event.res.setHeader("Location", location);
+  return send(event, "Redirecting to " + location, MIMES.html);
 }
-function appendHeader(res, name, value) {
-  let current = res.getHeader(name);
+function appendHeader(event, name, value) {
+  let current = event.res.getHeader(name);
   if (!current) {
-    res.setHeader(name, value);
+    event.res.setHeader(name, value);
     return;
   }
   if (!Array.isArray(current)) {
     current = [current.toString()];
   }
-  res.setHeader(name, current.concat(value));
+  event.res.setHeader(name, current.concat(value));
 }
 function isStream(data) {
-  return typeof data === "object" && typeof data.pipe === "function" && typeof data.on === "function";
+  return data && typeof data === "object" && typeof data.pipe === "function" && typeof data.on === "function";
 }
-function sendStream(res, data) {
+function sendStream(event, data) {
   return new Promise((resolve, reject) => {
-    data.pipe(res);
+    data.pipe(event.res);
     data.on("end", () => resolve(void 0));
     data.on("error", (error) => reject(createError(error)));
   });
 }
 
-function useCookies(req) {
-  return parse(req.headers.cookie || "");
+function useCookies(event) {
+  return parse(event.req.headers.cookie || "");
 }
-function useCookie(req, name) {
-  return useCookies(req)[name];
+function useCookie(event, name) {
+  return useCookies(event)[name];
 }
-function setCookie(res, name, value, serializeOptions) {
+function setCookie(event, name, value, serializeOptions) {
   const cookieStr = serialize(name, value, serializeOptions);
-  appendHeader(res, "Set-Cookie", cookieStr);
+  appendHeader(event, "Set-Cookie", cookieStr);
 }
-function deleteCookie(res, name, serializeOptions) {
-  setCookie(res, name, "", {
+function deleteCookie(event, name, serializeOptions) {
+  setCookie(event, name, "", {
     ...serializeOptions,
     maxAge: 0
   });
@@ -202,7 +256,7 @@ function createError(input) {
   }
   return err;
 }
-function sendError(res, error, debug) {
+function sendError(event, error, debug) {
   let h3Error;
   if (error instanceof H3Error) {
     h3Error = error;
@@ -210,37 +264,41 @@ function sendError(res, error, debug) {
     console.error(error);
     h3Error = createError(error);
   }
-  if (res.writableEnded) {
+  if (event.res.writableEnded) {
     return;
   }
-  res.statusCode = h3Error.statusCode;
-  res.statusMessage = h3Error.statusMessage;
+  event.res.statusCode = h3Error.statusCode;
+  event.res.statusMessage = h3Error.statusMessage;
   const responseBody = {
-    statusCode: res.statusCode,
-    statusMessage: res.statusMessage,
+    statusCode: event.res.statusCode,
+    statusMessage: event.res.statusMessage,
     stack: [],
     data: h3Error.data
   };
   if (debug) {
     responseBody.stack = (h3Error.stack || "").split("\n").map((l) => l.trim());
   }
-  res.setHeader("Content-Type", MIMES.json);
-  res.end(JSON.stringify(responseBody, null, 2));
+  event.res.setHeader("Content-Type", MIMES.json);
+  event.res.end(JSON.stringify(responseBody, null, 2));
 }
 
 function createApp(options = {}) {
   const stack = [];
-  const _handle = createHandle(stack, options);
-  const app = function(req, res) {
-    return _handle(req, res).catch((error) => {
+  const handler = createAppEventHandler(stack, options);
+  const nodeHandler = async function(req, res) {
+    const event = createEvent(req, res);
+    try {
+      await handler(event);
+    } catch (err) {
       if (options.onError) {
-        return options.onError(error, req, res);
+        await options.onError(err, event);
       }
-      return sendError(res, error, !!options.debug);
-    });
+      await sendError(event, err, !!options.debug);
+    }
   };
+  const app = nodeHandler;
   app.stack = stack;
-  app._handle = _handle;
+  app.handler = handler;
   app.use = (arg1, arg2, arg3) => use(app, arg1, arg2, arg3);
   return app;
 }
@@ -250,63 +308,70 @@ function use(app, arg1, arg2, arg3) {
   } else if (Array.isArray(arg2)) {
     arg2.forEach((i) => use(app, arg1, i, arg3));
   } else if (typeof arg1 === "string") {
-    app.stack.push(normalizeLayer({ ...arg3, route: arg1, handle: arg2 }));
+    app.stack.push(normalizeLayer({ ...arg3, route: arg1, handler: arg2 }));
   } else if (typeof arg1 === "function") {
-    app.stack.push(normalizeLayer({ ...arg2, route: "/", handle: arg1 }));
+    app.stack.push(normalizeLayer({ ...arg2, route: "/", handler: arg1 }));
   } else {
     app.stack.push(normalizeLayer({ ...arg1 }));
   }
   return app;
 }
-function createHandle(stack, options) {
+function createAppEventHandler(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 || "/";
+  return defineEventHandler(async (event) => {
+    event.req.originalUrl = event.req.originalUrl || event.req.url || "/";
+    const reqUrl = event.req.url || "/";
     for (const layer of stack) {
       if (layer.route.length > 1) {
         if (!reqUrl.startsWith(layer.route)) {
           continue;
         }
-        req.url = reqUrl.slice(layer.route.length) || "/";
+        event.req.url = reqUrl.slice(layer.route.length) || "/";
       } else {
-        req.url = reqUrl;
+        event.req.url = reqUrl;
       }
-      if (layer.match && !layer.match(req.url, req)) {
+      if (layer.match && !layer.match(event.req.url, event)) {
         continue;
       }
-      const val = await layer.handle(req, res);
-      if (res.writableEnded) {
+      const val = await layer.handler(event);
+      if (event.res.writableEnded) {
         return;
       }
       const type = typeof val;
       if (type === "string") {
-        return send(res, val, MIMES.html);
+        return send(event, val, MIMES.html);
       } else if (isStream(val)) {
-        return sendStream(res, val);
+        return sendStream(event, val);
       } else if (type === "object" || type === "boolean" || type === "number") {
         if (val && val.buffer) {
-          return send(res, val);
+          return send(event, val);
         } else if (val instanceof Error) {
           throw createError(val);
         } else {
-          return send(res, JSON.stringify(val, null, spacing), MIMES.json);
+          return send(event, JSON.stringify(val, null, spacing), MIMES.json);
         }
       }
     }
-    if (!res.writableEnded) {
+    if (!event.res.writableEnded) {
       throw createError({ statusCode: 404, statusMessage: "Not Found" });
     }
-  };
+  });
 }
-function normalizeLayer(layer) {
-  if (layer.promisify === void 0) {
-    layer.promisify = layer.handle.length > 2;
+function normalizeLayer(input) {
+  let handler = input.handler;
+  if (handler.handler) {
+    handler = handler.handler;
+  }
+  if (!isEventHandler(handler)) {
+    if (input.lazy) {
+      handler = defineLazyHandler(handler);
+    }
+    handler = toEventHandler(handler);
   }
   return {
-    route: withoutTrailingSlash(layer.route),
-    match: layer.match,
-    handle: layer.lazy ? lazyHandle(layer.handle, layer.promisify) : layer.promisify ? promisifyHandle(layer.handle) : layer.handle
+    route: withoutTrailingSlash(input.route),
+    match: input.match,
+    handler
   };
 }
 
@@ -315,28 +380,34 @@ function createRouter() {
   const _router = createRouter$1({});
   const routes = {};
   const router = {};
-  router.add = (path, handle, method = "all") => {
+  const addRoute = (path, handler, method) => {
     let route = routes[path];
     if (!route) {
       routes[path] = route = { handlers: {} };
       _router.insert(path, route);
     }
-    route.handlers[method] = handle;
+    route.handlers[method] = toEventHandler(handler);
     return router;
   };
+  router.use = router.add = (path, handler, method) => addRoute(path, handler, method || "all");
   for (const method of RouterMethods) {
     router[method] = (path, handle) => router.add(path, handle, method);
   }
-  router.handle = (req, res) => {
-    const matched = _router.lookup(req.url || "/");
+  router.handler = defineEventHandler((event) => {
+    let path = event.req.url || "/";
+    const queryUrlIndex = path.lastIndexOf("?");
+    if (queryUrlIndex > -1) {
+      path = path.substring(0, queryUrlIndex);
+    }
+    const matched = _router.lookup(path);
     if (!matched) {
       throw createError({
         statusCode: 404,
         name: "Not Found",
-        statusMessage: `Cannot find any route matching ${req.url || "/"}.`
+        statusMessage: `Cannot find any route matching ${event.req.url || "/"}.`
       });
     }
-    const method = (req.method || "get").toLowerCase();
+    const method = (event.req.method || "get").toLowerCase();
     const handler = matched.handlers[method] || matched.handlers.all;
     if (!handler) {
       throw createError({
@@ -345,10 +416,11 @@ function createRouter() {
         statusMessage: `Method ${method} is not allowed on this route.`
       });
     }
-    req.params = matched.params || {};
-    return handler(req, res);
-  };
+    event.event.params = matched.params || {};
+    event.req.params = event.event.params;
+    return handler(event);
+  });
   return router;
 }
 
-export { H3Error, MIMES, appendHeader, assertMethod, callHandle, createApp, createError, createHandle, createRouter, defaultContentType, defineHandle, defineMiddleware, deleteCookie, isMethod, isStream, lazyHandle, promisifyHandle, send, sendError, sendRedirect, sendStream, setCookie, use, useBase, useBody, useCookie, useCookies, useMethod, useQuery, useRawBody };
+export { H3Error, MIMES, appendHeader, assertMethod, callHandler, createApp, createAppEventHandler, createError, createEvent, createRouter, defaultContentType, defineEventHandler, defineHandle, defineHandler, defineLazyEventHandler, defineLazyHandler, defineMiddleware, deleteCookie, isEvent, isEventHandler, isMethod, isStream, lazyHandle, promisifyHandle, promisifyHandler, send, sendError, sendRedirect, sendStream, setCookie, toEventHandler, use, useBase, useBody, useCookie, useCookies, useMethod, useQuery, useRawBody };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "h3",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Tiny JavaScript Server",
   "repository": "unjs/h3",
   "license": "MIT",
@@ -47,11 +47,12 @@
   "packageManager": "pnpm@6.32.3",
   "scripts": {
     "build": "unbuild",
-    "dev": "jiti ./playground/index.ts",
+    "dev": "vitest",
     "lint": "eslint --ext ts,mjs,cjs .",
+    "play": "jiti ./playground/index.ts",
     "profile": "0x -o -D .profile -P 'autocannon -c 100 -p 10 -d 40 http://localhost:$PORT' ./playground/server.cjs",
     "release": "pnpm lint && pnpm test && pnpm build && standard-version && pnpm publish && git push --follow-tags",
     "test": "vitest run"
   },
-  "readme": "[![npm downloads](https://img.shields.io/npm/dm/h3.svg?style=flat-square)](https://npmjs.com/package/h3)\n[![version](https://img.shields.io/npm/v/h3/latest.svg?style=flat-square)](https://npmjs.com/package/h3)\n[![bundlephobia](https://img.shields.io/bundlephobia/min/h3/latest.svg?style=flat-square)](https://bundlephobia.com/result?p=h3)\n[![build status](https://img.shields.io/github/workflow/status/unjs/h3/ci/main?style=flat-square)](https://github.com/unjs/h3/actions)\n[![coverage](https://img.shields.io/codecov/c/gh/unjs/h3/main?style=flat-square)](https://codecov.io/gh/unjs/h3)\n[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue?style=flat-square)](https://www.jsdocs.io/package/h3)\n\n> H3 is a minimal h(ttp) framework built for high performance and portability\n\n<!-- ![h3 - Tiny JavaScript Server](.github/banner.svg) -->\n\n## Features\n\n✔️ &nbsp;**Portable:** Works perfectly in Serverless, Workers, and Node.js\n\n✔️ &nbsp;**Compatible:** Support connect/express middleware\n\n✔️ &nbsp;**Minimal:** Small, tree-shakable and zero-dependency\n\n✔️ &nbsp;**Modern:** Native promise support\n\n✔️ &nbsp;**Extendable:** Ships with a set of composable utilities but can be extended\n\n✔️ &nbsp;**Router:** Super fast route matching using [unjs/radix3](https://github.com/unjs/radix3)\n\n## Install\n\n```bash\n# Using npm\nnpm install h3\n\n# Using pnpm\npnpm add h3\n\n# Using pnpm\npnpm add h3\n```\n\n## Usage\n\n```ts\nimport { createServer } from 'http'\nimport { createApp } from 'h3'\n\nconst app = createApp()\napp.use('/', () => 'Hello world!')\n\ncreateServer(app).listen(process.env.PORT || 3000)\n```\n\n<details>\n <summary>Example using <a href=\"https://github.com/unjs/listhen\">listhen</a> for an elegant listener.</summary>\n\n```ts\nimport { createApp } from 'h3'\nimport { listen } from 'listhen'\n\nconst app = createApp()\napp.use('/', () => 'Hello world!')\n\nlisten(app)\n```\n</details>\n\n## Router\n\nThe `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.\n\nTo opt-in using a more advanced and convenient routing system, we can create a router instance and register it to app instance.\n\n```ts\nimport { createApp, createRouter } from 'h3'\n\nconst app = createApp()\n\nconst router = createRouter()\n .get('/', () => 'Hello World!')\n .get('/hello/:name', req => `Hello ${req.params.name}!`)\n\napp.use(router)\n```\n\n**Tip:** We can register same route more than once with different methods.\n\nRoutes are internally stored in a [Radix Tree](https://en.wikipedia.org/wiki/Radix_tree) and matched using [unjs/radix3](https://github.com/unjs/radix3).\n\n## More usage examples\n\n```js\n// Handle can directly return object or Promise<object> for JSON response\napp.use('/api', (req) => ({ url: req.url }))\n\n// We can have better matching other than quick prefix match\napp.use('/odd', () => 'Is odd!', { match: url => url.substr(1) % 2 })\n\n// Handle can directly return string for HTML response\napp.use(() => '<h1>Hello world!</h1>')\n\n// We can chain calls to .use()\napp.use('/1', () => '<h1>Hello world!</h1>')\n   .use('/2', () => '<h1>Goodbye!</h1>')\n\n// Legacy middleware with 3rd argument are automatically promisified\napp.use((req, res, next) => { req.setHeader('X-Foo', 'bar'); next() })\n\n// Force promisify a legacy middleware\n// app.use(someMiddleware, { promisify: true })\n\n// Lazy loaded routes using { lazy: true }\n// app.use('/big', () => import('./big'), { lazy: true })\n```\n\n## Utilities\n\nInstead of adding helpers to `req` and `res`, h3 exposes them as composable utilities.\n\n- `useRawBody(req, encoding?)`\n- `useBody(req)`\n- `useCookies(req)`\n- `useCookie(req, name)`\n- `setCookie(res, name, value, opts?)`\n- `deleteCookie(res, name, opts?)`\n- `useQuery(req)`\n- `send(res, data, type?)`\n- `sendRedirect(res, location, code=302)`\n- `appendHeader(res, name, value)`\n- `createError({ statusCode, statusMessage, data? })`\n- `sendError(res, error, debug?)`\n- `defineHandle(handle)`\n- `defineMiddleware(middlware)`\n- `useMethod(req, default?)`\n- `isMethod(req, expected, allowHead?)`\n- `assertMethod(req, expected, allowHead?)`\n\n👉 You can learn more about usage in [JSDocs Documentation](https://www.jsdocs.io/package/h3#package-functions).\n\n## How it works?\n\nUsing `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.\n\nWhen 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.\n\nFor maximum compatibility with connect/express middleware (`req, res, next?` signature), h3 converts classic middleware into a promisified version ready to use with stack runner:\n\n- If middleware has 3rd next/callback param, the promise will `resolve/reject` when called\n- If middleware returns a promise, it will be **chained** to the main promise\n- If calling middleware throws an immediate error, the promise will be rejected\n- On `close` and `error` events of res, the promise will `resolve/reject` (to ensure if middleware simply calls `res.end`)\n\n## License\n\nMIT\n"
+  "readme": "[![npm downloads](https://img.shields.io/npm/dm/h3.svg?style=flat-square)](https://npmjs.com/package/h3)\n[![version](https://img.shields.io/npm/v/h3/latest.svg?style=flat-square)](https://npmjs.com/package/h3)\n[![bundlephobia](https://img.shields.io/bundlephobia/min/h3/latest.svg?style=flat-square)](https://bundlephobia.com/result?p=h3)\n[![build status](https://img.shields.io/github/workflow/status/unjs/h3/ci/main?style=flat-square)](https://github.com/unjs/h3/actions)\n[![coverage](https://img.shields.io/codecov/c/gh/unjs/h3/main?style=flat-square)](https://codecov.io/gh/unjs/h3)\n[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue?style=flat-square)](https://www.jsdocs.io/package/h3)\n\n> H3 is a minimal h(ttp) framework built for high performance and portability\n\n<!-- ![h3 - Tiny JavaScript Server](.github/banner.svg) -->\n\n## Features\n\n✔️ &nbsp;**Portable:** Works perfectly in Serverless, Workers, and Node.js\n\n✔️ &nbsp;**Compatible:** Support connect/express middleware\n\n✔️ &nbsp;**Minimal:** Small, tree-shakable and zero-dependency\n\n✔️ &nbsp;**Modern:** Native promise support\n\n✔️ &nbsp;**Extendable:** Ships with a set of composable utilities but can be extended\n\n✔️ &nbsp;**Router:** Super fast route matching using [unjs/radix3](https://github.com/unjs/radix3)\n\n## Install\n\n```bash\n# Using npm\nnpm install h3\n\n# Using yarn\nyarn add h3\n\n# Using pnpm\npnpm add h3\n```\n\n## Usage\n\n```ts\nimport { createServer } from 'http'\nimport { createApp } from 'h3'\n\nconst app = createApp()\napp.use('/', () => 'Hello world!')\n\ncreateServer(app).listen(process.env.PORT || 3000)\n```\n\n<details>\n <summary>Example using <a href=\"https://github.com/unjs/listhen\">listhen</a> for an elegant listener.</summary>\n\n```ts\nimport { createApp } from 'h3'\nimport { listen } from 'listhen'\n\nconst app = createApp()\napp.use('/', () => 'Hello world!')\n\nlisten(app)\n```\n</details>\n\n## Router\n\nThe `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.\n\nTo opt-in using a more advanced and convenient routing system, we can create a router instance and register it to app instance.\n\n```ts\nimport { createApp, createRouter } from 'h3'\n\nconst app = createApp()\n\nconst router = createRouter()\n .get('/', () => 'Hello World!')\n .get('/hello/:name', req => `Hello ${req.params.name}!`)\n\napp.use(router)\n```\n\n**Tip:** We can register same route more than once with different methods.\n\nRoutes are internally stored in a [Radix Tree](https://en.wikipedia.org/wiki/Radix_tree) and matched using [unjs/radix3](https://github.com/unjs/radix3).\n\n## More usage examples\n\n```js\n// Handle can directly return object or Promise<object> for JSON response\napp.use('/api', (req) => ({ url: req.url }))\n\n// We can have better matching other than quick prefix match\napp.use('/odd', () => 'Is odd!', { match: url => url.substr(1) % 2 })\n\n// Handle can directly return string for HTML response\napp.use(() => '<h1>Hello world!</h1>')\n\n// We can chain calls to .use()\napp.use('/1', () => '<h1>Hello world!</h1>')\n   .use('/2', () => '<h1>Goodbye!</h1>')\n\n// Legacy middleware with 3rd argument are automatically promisified\napp.use((req, res, next) => { req.setHeader('X-Foo', 'bar'); next() })\n\n// Force promisify a legacy middleware\n// app.use(someMiddleware, { promisify: true })\n\n// Lazy loaded routes using { lazy: true }\n// app.use('/big', () => import('./big'), { lazy: true })\n```\n\n## Utilities\n\nInstead of adding helpers to `req` and `res`, h3 exposes them as composable utilities.\n\n- `useRawBody(req, encoding?)`\n- `useBody(req)`\n- `useCookies(req)`\n- `useCookie(req, name)`\n- `setCookie(res, name, value, opts?)`\n- `deleteCookie(res, name, opts?)`\n- `useQuery(req)`\n- `send(res, data, type?)`\n- `sendRedirect(res, location, code=302)`\n- `appendHeader(res, name, value)`\n- `createError({ statusCode, statusMessage, data? })`\n- `sendError(res, error, debug?)`\n- `defineHandle(handle)`\n- `defineMiddleware(middlware)`\n- `useMethod(req, default?)`\n- `isMethod(req, expected, allowHead?)`\n- `assertMethod(req, expected, allowHead?)`\n\n👉 You can learn more about usage in [JSDocs Documentation](https://www.jsdocs.io/package/h3#package-functions).\n\n## How it works?\n\nUsing `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.\n\nWhen 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.\n\nFor maximum compatibility with connect/express middleware (`req, res, next?` signature), h3 converts classic middleware into a promisified version ready to use with stack runner:\n\n- If middleware has 3rd next/callback param, the promise will `resolve/reject` when called\n- If middleware returns a promise, it will be **chained** to the main promise\n- If calling middleware throws an immediate error, the promise will be rejected\n- On `close` and `error` events of res, the promise will `resolve/reject` (to ensure if middleware simply calls `res.end`)\n\n## License\n\nMIT\n"
 }