h3 0.7.21 → 0.8.1

package/README.md

@@ -13,9 +13,7 @@
 
 ✔️  **Portable:** Works perfectly in Serverless, Workers, and Node.js
 
-✔️  **Compatible:** Support connect/express middleware
-
-✔️  **Minimal:** Small, tree-shakable and zero-dependency
+✔️  **Minimal:** Small and tree-shakable
 
 ✔️  **Modern:** Native promise support
 
@@ -23,6 +21,8 @@
 
 ✔️  **Router:** Super fast route matching using [unjs/radix3](https://github.com/unjs/radix3)
 
+✔️  **Compatible:** Compatibility layer with node/connect/express middleware
+
 ## Install
 
 ```bash
@@ -40,25 +40,25 @@ pnpm add h3
 
 ```ts
 import { createServer } from 'http'
-import { createApp } from 'h3'
+import { createApp, eventHandler } from 'h3'
 
 const app = createApp()
-app.use('/', () => 'Hello world!')
+app.use('/', eventHandler(() => 'Hello world!'))
 
-createServer(app).listen(process.env.PORT || 3000)
+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 } from 'h3'
+import { createApp, toNodeListener } from 'h3'
 import { listen } from 'listhen'
 
 const app = createApp()
-app.use('/', () => 'Hello world!')
+app.use('/', eventHandler(() => 'Hello world!'))
 
-listen(app)
+listen(toNodeListener(app))
 ```
 </details>
 
@@ -69,13 +69,13 @@ The `app` instance created by `h3` uses a middleware stack (see [how it works](#
 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, createRouter } from 'h3'
+import { createApp, eventHandler, createRouter } from 'h3'
 
 const app = createApp()
 
 const router = createRouter()
- .get('/', () => 'Hello World!')
- .get('/hello/:name', req => `Hello ${req.context.params.name}!`)
+ .get('/', eventHandler(() => 'Hello World!'))
+ .get('/hello/:name', eventHandler(event => `Hello ${event.context.params.name}!`))
 
 app.use(router)
 ```
@@ -84,61 +84,58 @@ 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).
 
-## More usage examples
+## More app usage examples
 
 ```js
 // Handle can directly return object or Promise<object> for JSON response
-app.use('/api', (req) => ({ url: req.url }))
+app.use('/api', eventHandler((event) => ({ url: event.req.url }))
 
 // We can have better matching other than quick prefix match
-app.use('/odd', () => 'Is odd!', { match: url => url.substr(1) % 2 })
+app.use('/odd', eventHandler(() => 'Is odd!'), { match: url => url.substr(1) % 2 })
 
 // Handle can directly return string for HTML response
-app.use(() => '<h1>Hello world!</h1>')
+app.use(eventHandler(() => '<h1>Hello world!</h1>'))
 
 // We can chain calls to .use()
-app.use('/1', () => '<h1>Hello world!</h1>')
-   .use('/2', () => '<h1>Goodbye!</h1>')
+app.use('/1', eventHandler(() => '<h1>Hello world!</h1>'))
+   .use('/2', eventHandler(() => '<h1>Goodbye!</h1>'))
 
 // 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 })
+app.use(fromNodeMiddleware((req, res, next) => { req.setHeader('X-Foo', 'bar'); next() }))
 
 // Lazy loaded routes using { lazy: true }
-// app.use('/big', () => import('./big'), { lazy: true })
+app.use('/big', () => import('./big-handler'), { lazy: true })
 ```
 
 ## Utilities
 
-### Built-in
+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.
 
-Instead of adding helpers to `req` and `res`, h3 exposes them as composable utilities.
+### Built-in
 
-- `useRawBody(req, encoding?)`
-- `useBody(req)`
-- `useCookies(req)`
-- `useCookie(req, name)`
-- `setCookie(res, name, value, opts?)`
-- `deleteCookie(res, name, opts?)`
-- `useQuery(req)`
+- `useRawBody(event, encoding?)`
+- `useBody(event)`
+- `useCookies(event)`
+- `useCookie(event, name)`
+- `setCookie(event, name, value, opts?)`
+- `deleteCookie(event, name, opts?)`
+- `useQuery(event)`
 - `getRouterParams(event)`
-- `send(res, data, type?)`
-- `sendRedirect(res, location, code=302)`
+- `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?)`
+- `useMethod(event, default?)`
+- `isMethod(event, expected, allowHead?)`
+- `assertMethod(event, expected, allowHead?)`
 - `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).
 
@@ -149,19 +146,6 @@ More composable utilities can be found in community packages.
 - `validateBody(event, schema)` from [h3-typebox](https://github.com/kevinmarrec/h3-typebox)
 - `validateQuery(event, schema)` from [h3-typebox](https://github.com/kevinmarrec/h3-typebox)
 
-## How it works?
-
-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), h3 converts classic middleware into a promisified version ready to use with stack runner:
-
-- 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, 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
 
 MIT

package/dist/index.cjs

@@ -1,15 +1,21 @@
 'use strict';
 
-Object.defineProperty(exports, '__esModule', { value: true });
-
 const ufo = require('ufo');
+const radix3 = require('radix3');
 const destr = require('destr');
 const cookieEs = require('cookie-es');
-const radix3 = require('radix3');
 
-function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e["default"] : e; }
-
-const destr__default = /*#__PURE__*/_interopDefaultLegacy(destr);
+function useBase(base, handler) {
+  base = ufo.withoutTrailingSlash(base);
+  if (!base) {
+    return handler;
+  }
+  return eventHandler((event) => {
+    event.req.originalUrl = event.req.originalUrl || event.req.url || "/";
+    event.req.url = ufo.withoutBase(event.req.url || "/", base);
+    return handler(event);
+  });
+}
 
 class H3Error extends Error {
   constructor() {
@@ -17,7 +23,7 @@ class H3Error extends Error {
     this.statusCode = 500;
     this.fatal = false;
     this.unhandled = false;
-    this.statusMessage = "Internal Server Error";
+    this.statusMessage = void 0;
   }
 }
 H3Error.__h3_error__ = true;
@@ -75,8 +81,13 @@ function sendError(event, error, debug) {
   if (event.res.writableEnded) {
     return;
   }
-  event.res.statusCode = h3Error.statusCode;
-  event.res.statusMessage = h3Error.statusMessage;
+  const _code = parseInt(h3Error.statusCode);
+  if (_code) {
+    event.res.statusCode = _code;
+  }
+  if (h3Error.statusMessage) {
+    event.res.statusMessage = h3Error.statusMessage;
+  }
   event.res.setHeader("Content-Type", MIMES.json);
   event.res.end(JSON.stringify(responseBody, null, 2));
 }
@@ -166,7 +177,7 @@ async function readBody(event) {
     const parsedForm = Object.fromEntries(new URLSearchParams(body));
     return parsedForm;
   }
-  const json = destr__default(body);
+  const json = destr(body);
   event.req[ParsedBodySymbol] = json;
   return json;
 }
@@ -273,6 +284,22 @@ function sendStream(event, data) {
     data.on("error", (error) => reject(createError(error)));
   });
 }
+function writeEarlyHints(event, links, callback) {
+  if (!event.res.socket && !("writeEarlyHints" in event.res)) {
+    if (callback) {
+      callback();
+    }
+    return;
+  }
+  if ("writeEarlyHints" in event.res) {
+    return event.res.writeEarlyHints(links, callback);
+  }
+  const _links = Array.isArray(links) ? links : [links];
+  event.res.socket.write(`HTTP/1.1 103 Early Hints\r
+Link: ${_links.join("\r\n")}\r
+\r
+`, "utf-8", callback);
+}
 
 function parseCookies(event) {
   return cookieEs.parse(event.req.headers.cookie || "");
@@ -372,16 +399,6 @@ class H3Event {
     this.context = {};
     this.req = req;
     this.res = res;
-    this.event = this;
-    req.event = this;
-    req.context = this.context;
-    req.req = req;
-    req.res = res;
-    res.event = this;
-    res.res = res;
-    res.req = res.req || {};
-    res.req.res = res;
-    res.req.req = req;
   }
   respondWith(r) {
     Promise.resolve(r).then((_response) => {
@@ -421,63 +438,6 @@ function createEvent(req, res) {
   return new H3Event(req, res);
 }
 
-const defineHandler = (handler) => handler;
-const defineHandle = defineHandler;
-const defineMiddleware = (middleware) => middleware;
-function promisifyHandler(handler) {
-  return function(req, res) {
-    return callHandler(handler, req, res);
-  };
-}
-const promisifyHandle = promisifyHandler;
-function callHandler(handler, req, res) {
-  const isMiddleware = handler.length > 2;
-  return new Promise((resolve, reject) => {
-    const next = (err) => {
-      if (isMiddleware) {
-        res.off("close", next);
-        res.off("error", next);
-      }
-      return err ? reject(createError(err)) : resolve(void 0);
-    };
-    try {
-      const returned = handler(req, res, next);
-      if (isMiddleware && returned === void 0) {
-        res.once("close", next);
-        res.once("error", next);
-      } else {
-        resolve(returned);
-      }
-    } catch (err) {
-      next(err);
-    }
-  });
-}
-function defineLazyHandler(handler, promisify) {
-  let _promise;
-  const resolve = () => {
-    if (!_promise) {
-      _promise = Promise.resolve(handler()).then((r) => promisify ? promisifyHandler(r.default || r) : r.default || r);
-    }
-    return _promise;
-  };
-  return function(req, res) {
-    return resolve().then((h) => h(req, res));
-  };
-}
-const lazyHandle = defineLazyHandler;
-function useBase(base, handler) {
-  base = ufo.withoutTrailingSlash(base);
-  if (!base) {
-    return handler;
-  }
-  return function(req, res) {
-    req.originalUrl = req.originalUrl || req.url || "/";
-    req.url = ufo.withoutBase(req.url || "/", base);
-    return handler(req, res);
-  };
-}
-
 function defineEventHandler(handler) {
   handler.__is_handler__ = true;
   return handler;
@@ -486,16 +446,17 @@ const eventHandler = defineEventHandler;
 function isEventHandler(input) {
   return "__is_handler__" in input;
 }
-function toEventHandler(handler) {
-  if (isEventHandler(handler)) {
-    return handler;
+function toEventHandler(input, _, _route) {
+  if (!isEventHandler(input)) {
+    console.warn(
+      "[h3] Implicit event handler conversion is deprecated. Use `eventHandler()` or `fromNodeMiddleware()` to define event handlers.",
+      _route && _route !== "/" ? `
+     Route: ${_route}` : "",
+      `
+     Handler: ${input}`
+    );
   }
-  if (typeof handler !== "function") {
-    throw new TypeError("Invalid handler. It should be a function:", handler);
-  }
-  return eventHandler((event) => {
-    return callHandler(handler, event.req, event.res);
-  });
+  return input;
 }
 function dynamicEventHandler(initial) {
   let current = initial;
@@ -540,30 +501,12 @@ const lazyEventHandler = defineLazyEventHandler;
 function createApp(options = {}) {
   const stack = [];
   const handler = createAppEventHandler(stack, options);
-  const nodeHandler = async function(req, res) {
-    const event = createEvent(req, res);
-    try {
-      await handler(event);
-    } catch (_error) {
-      const error = createError(_error);
-      if (!isError(_error)) {
-        error.unhandled = true;
-      }
-      if (options.onError) {
-        await options.onError(error, event);
-      } else {
-        if (error.unhandled || error.fatal) {
-          console.error("[h3]", error.fatal ? "[fatal]" : "[unhandled]", error);
-        }
-        await sendError(event, error, !!options.debug);
-      }
-    }
+  const app = {
+    use: (arg1, arg2, arg3) => use(app, arg1, arg2, arg3),
+    handler,
+    stack,
+    options
   };
-  const app = nodeHandler;
-  app.nodeHandler = nodeHandler;
-  app.stack = stack;
-  app.handler = handler;
-  app.use = (arg1, arg2, arg3) => use(app, arg1, arg2, arg3);
   return app;
 }
 function use(app, arg1, arg2, arg3) {
@@ -620,19 +563,22 @@ function createAppEventHandler(stack, options) {
       }
     }
     if (!event.res.writableEnded) {
-      throw createError({ statusCode: 404, statusMessage: "Not Found" });
+      throw createError({
+        statusCode: 404,
+        statusMessage: `Cannot find any route matching ${event.req.url || "/"}.`
+      });
     }
   });
 }
 function normalizeLayer(input) {
-  let handler = input.handler || input.handle;
+  let handler = input.handler;
   if (handler.handler) {
     handler = handler.handler;
   }
   if (input.lazy) {
     handler = lazyEventHandler(handler);
   } else if (!isEventHandler(handler)) {
-    handler = toEventHandler(handler);
+    handler = toEventHandler(handler, null, input.route);
   }
   return {
     route: ufo.withoutTrailingSlash(input.route),
@@ -641,8 +587,72 @@ function normalizeLayer(input) {
   };
 }
 
+const defineNodeListener = (handler) => handler;
+const defineNodeMiddleware = (middleware) => middleware;
+function fromNodeMiddleware(handler) {
+  if (isEventHandler(handler)) {
+    return handler;
+  }
+  if (typeof handler !== "function") {
+    throw new TypeError("Invalid handler. It should be a function:", handler);
+  }
+  return eventHandler((event) => {
+    return callNodeListener(handler, event.req, event.res);
+  });
+}
+function toNodeListener(app) {
+  const toNodeHandle = async function(req, res) {
+    const event = createEvent(req, res);
+    try {
+      await app.handler(event);
+    } catch (_error) {
+      const error = createError(_error);
+      if (!isError(_error)) {
+        error.unhandled = true;
+      }
+      if (app.options.onError) {
+        await app.options.onError(error, event);
+      } else {
+        if (error.unhandled || error.fatal) {
+          console.error("[h3]", error.fatal ? "[fatal]" : "[unhandled]", error);
+        }
+        await sendError(event, error, !!app.options.debug);
+      }
+    }
+  };
+  return toNodeHandle;
+}
+function promisifyNodeListener(handler) {
+  return function(req, res) {
+    return callNodeListener(handler, req, res);
+  };
+}
+function callNodeListener(handler, req, res) {
+  const isMiddleware = handler.length > 2;
+  return new Promise((resolve, reject) => {
+    const next = (err) => {
+      if (isMiddleware) {
+        res.off("close", next);
+        res.off("error", next);
+      }
+      return err ? reject(createError(err)) : resolve(void 0);
+    };
+    try {
+      const returned = handler(req, res, next);
+      if (isMiddleware && returned === void 0) {
+        res.once("close", next);
+        res.once("error", next);
+      } else {
+        resolve(returned);
+      }
+    } catch (err) {
+      next(err);
+    }
+  });
+}
+
 const RouterMethods = ["connect", "delete", "get", "head", "options", "post", "put", "trace", "patch"];
-function createRouter() {
+function createRouter(opts = {}) {
   const _router = radix3.createRouter({});
   const routes = {};
   const router = {};
@@ -655,7 +665,7 @@ function createRouter() {
     if (Array.isArray(method)) {
       method.forEach((m) => addRoute(path, handler, m));
     } else {
-      route.handlers[method] = toEventHandler(handler);
+      route.handlers[method] = toEventHandler(handler, null, path);
     }
     return router;
   };
@@ -664,18 +674,18 @@ function createRouter() {
     router[method] = (path, handle) => router.add(path, handle, method);
   }
   router.handler = eventHandler((event) => {
-    let path = event.req.url || "/";
-    const queryUrlIndex = path.lastIndexOf("?");
-    if (queryUrlIndex > -1) {
-      path = path.substring(0, queryUrlIndex);
-    }
+    const path = new URL(event.req.url || "/", "http://localhost").pathname;
     const matched = _router.lookup(path);
     if (!matched) {
-      throw createError({
-        statusCode: 404,
-        name: "Not Found",
-        statusMessage: `Cannot find any route matching ${event.req.url || "/"}.`
-      });
+      if (opts.preemtive) {
+        throw createError({
+          statusCode: 404,
+          name: "Not Found",
+          statusMessage: `Cannot find any route matching ${event.req.url || "/"}.`
+        });
+      } else {
+        return;
+      }
     }
     const method = (event.req.method || "get").toLowerCase();
     const handler = matched.handlers[method] || matched.handlers.all;
@@ -687,8 +697,7 @@ function createRouter() {
       });
     }
     const params = matched.params || {};
-    event.event.context.params = params;
-    event.req.context.params = params;
+    event.context.params = params;
     return handler(event);
   });
   return router;
@@ -704,7 +713,7 @@ exports.appendHeaders = appendHeaders;
 exports.appendResponseHeader = appendResponseHeader;
 exports.appendResponseHeaders = appendResponseHeaders;
 exports.assertMethod = assertMethod;
-exports.callHandler = callHandler;
+exports.callNodeListener = callNodeListener;
 exports.createApp = createApp;
 exports.createAppEventHandler = createAppEventHandler;
 exports.createError = createError;
@@ -712,14 +721,13 @@ exports.createEvent = createEvent;
 exports.createRouter = createRouter;
 exports.defaultContentType = defaultContentType;
 exports.defineEventHandler = defineEventHandler;
-exports.defineHandle = defineHandle;
-exports.defineHandler = defineHandler;
 exports.defineLazyEventHandler = defineLazyEventHandler;
-exports.defineLazyHandler = defineLazyHandler;
-exports.defineMiddleware = defineMiddleware;
+exports.defineNodeListener = defineNodeListener;
+exports.defineNodeMiddleware = defineNodeMiddleware;
 exports.deleteCookie = deleteCookie;
 exports.dynamicEventHandler = dynamicEventHandler;
 exports.eventHandler = eventHandler;
+exports.fromNodeMiddleware = fromNodeMiddleware;
 exports.getCookie = getCookie;
 exports.getHeader = getHeader;
 exports.getHeaders = getHeaders;
@@ -738,10 +746,8 @@ exports.isEventHandler = isEventHandler;
 exports.isMethod = isMethod;
 exports.isStream = isStream;
 exports.lazyEventHandler = lazyEventHandler;
-exports.lazyHandle = lazyHandle;
 exports.parseCookies = parseCookies;
-exports.promisifyHandle = promisifyHandle;
-exports.promisifyHandler = promisifyHandler;
+exports.promisifyNodeListener = promisifyNodeListener;
 exports.readBody = readBody;
 exports.readRawBody = readRawBody;
 exports.send = send;
@@ -754,6 +760,7 @@ exports.setHeaders = setHeaders;
 exports.setResponseHeader = setResponseHeader;
 exports.setResponseHeaders = setResponseHeaders;
 exports.toEventHandler = toEventHandler;
+exports.toNodeListener = toNodeListener;
 exports.use = use;
 exports.useBase = useBase;
 exports.useBody = useBody;
@@ -762,3 +769,4 @@ exports.useCookies = useCookies;
 exports.useMethod = useMethod;
 exports.useQuery = useQuery;
 exports.useRawBody = useRawBody;
+exports.writeEarlyHints = writeEarlyHints;