update

Author: pi0

docs/content/2.concepts/1.app.md

@@ -1,62 +1,123 @@
 ---
 title: H3 App
-description:
+description: Learn more about H3 app usage
 ---
 
+Every H3 server has at least one app instance. It is the beating hearth of your server.
+
+## Initialing H3 App
+
+You can create a new h3 app instance using `createApp` utility:
+
+```js [app.mjs]
+import { createApp } from "h3";
+
+const app = createApp();
+```
+
+You can also pass global app configurtions when initializing an app:
+
+```js
+const app = createApp({
+  debug: true,
+});
+```
+
+## Adding Event Handlers
+
+After initializing app instance, we need to register [Event Handlers](/concepts/event-handler) to our app to handle the logic.
+
+In order to register event handlers, we have to use `app.use()` method. Each handler can be registred without prefix (middleware) or with a static route prefix.
+
+When an HTTP request comes, H3, tries to call our registred handlers (that match the prefix) one by one (**in order that we add them**) until one of them ends the request. This is called "stack runner".
+
+**Example:** Resgister a simple `/hello` route:
+
 ```js
-// Handle can directly return object or Promise<object> for JSON response
 app.use(
-  "/api",
-  eventHandler((event) => ({ url: event.node.req.url })),
+  "/hello",
+  eventHandler(() => "Hello World"),
 );
+```
+
+**Note:** Above example matches any request starting with `/hello`, including `/hello` but also `/hello/world` and `/hello/you`.
+
+If event handlers don't register a prefix, they will match every request.
+
+**Example:** Simple request logger
 
-// We can have better matching other than quick prefix match
+```js
 app.use(
-  "/odd",
-  eventHandler(() => "Is odd!"),
-  { match: (url) => url.substr(1) % 2 },
+  eventHandler((event) => {
+    console.log("Request:", event.path);
+    // Since we don't return anything, h3, goes to the next middleware
+  }),
 );
 
-// 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>"),
-  );
-
-// We can proxy requests and rewrite cookie's domain and path
 app.use(
-  "/api",
-  eventHandler((event) =>
-    proxyRequest(event, "https://example.com", {
-      // f.e. keep one domain unchanged, rewrite one domain and remove other domains
-      cookieDomainRewrite: {
-        "example.com": "example.com",
-        "example.com": "somecompany.co.uk",
-        "*": "",
-      },
-      cookiePathRewrite: {
-        "/": "/api",
-      },
-    }),
-  ),
+  "/hello",
+  eventHandler(() => "Hello World"),
 );
+```
+
+**Note:** Avoid adding global middleware as much as possible. They will be soon the enemy of your application performance and make scaling project size harder as global logic can become complex and tricky to manage!
+
+There are couple of advanced option you can also provide when registering an event handler as last object.
 
-// Legacy middleware with 3rd argument are automatically promisified
+### Custom Matcher
+
+If you need matching logic more advanced than prefix matching but simpler than using a router, you can use custom `match` option:
+
+**Example** Only match odd number routes (`/2`, `/4`, `/8`, ...)
+
+```js
 app.use(
-  fromNodeMiddleware((req, res, next) => {
-    req.setHeader("x-foo", "bar");
-    next();
-  }),
+  "/",
+  eventHandler(() => "This is odd!"),
+  { match: (url) => url.substr(1) % 2 },
 );
+```
 
-// Lazy loaded routes using { lazy: true }
+### Lazy Matcher
+
+You can provide a callback function that h3 uses on first time matching handler to load it. It is particulary useful for dynamic imports to reduce server startup time.
+
+**Example:**
+
+```js
 app.use("/big", () => import("./big-handler"), { lazy: true });
 ```
+
+## Sending Responses
+
+When a request comes, h3 app asyncly calls matching handlers and waits for them one-by-one. The first handler that sends a response by directly returning a value or using a response utility, steps h3 from running the rest of handlers.
+
+If all handlers get called and there is still no response, h3 will automatically throw a 404 error.
+
+The simplest way to handle response, is to directly return a value from event handlers. See [Event Handlers](/concepts/event-handler#sending-responses) for possible values.
+
+## Event Handling
+
+When handling a request, if one of the handlers throws an error, H3 app will automatically catch it and renders error. You can override default error handler using `onError` option.
+
+<!-- TODO: Examples -->
+
+## Global Hooks
+
+When initializing an H3 app, you can register global hooks:
+
+- `onError`
+- `onRequest`
+- `onBeforeResponse`
+- `onAfterResponse`
+
+<!-- TODO: Examples -->
+
+## App Properties (advanced)
+
+H3 app instance has some additional propertier. However it is usually not recommanded to directly access them unless you know what are you doing!
+
+- `app.stack`: An ordered array of currently registred event handlers.
+  - Each item has `route` and `handler` properties.
+- `app.options`: Global options object provided when initializing the app
+- `app.handler`: Direct stack handler function (unsafe)

docs/content/2.concepts/2.event-handler.md

@@ -0,0 +1,48 @@
+---
+title: Event Handlers
+description: Learn more about H3 event handlers
+---
+
+Event handlers are the building blocks to define applicaion logic.
+
+You can define event handlers using `defineEventHandler` or `eventHandler` helper utilities (they are aliases and both do exactly the same!).
+
+```js
+import { defineEventHandler } from "h3";
+
+const apiHandler = defineEventHandler((event) => {
+  return "Response";
+});
+```
+
+Event handlers can be registed to [App Instance](/concepts/app) or [Router Instance](/concepts/router.)
+
+## Sending Responses
+
+You can directly send responses by returning a value from event handlers. It can be:
+
+- JSON serializable value: If returning a json object or serializable value, it will be stringified and sent with default `application/json` content-type.
+- `string`: Will be sent as-is using default `application/html` content-type.
+- `null` value: H3 with end response with `204 - No Content` status code.
+- [Web `ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [node `Readable`](https://nodejs.org/api/stream.html#readable-streams)
+- [Web `ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) or [node `Buffer`](https://nodejs.org/api/buffer.html#buffer)
+- [Web Fetch Response](https://developer.mozilla.org/en-US/docs/Web/API/Response/Response)
+- [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) instance (suupported but instead `throw` errors, it is much better!!)
+
+All H3 event handler support `async/await` syntax. Therefore any of above values could also be wrapped in a [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).
+
+**Example:** Send HTML response:
+
+```js
+app.use(eventHandler(async (event) => "<h1>Hello world!</h1>"));
+```
+
+**Example:** Send JSON response:
+
+```js
+// Handle can directly return object or Promise<object> for JSON response
+app.use(
+  "/api",
+  eventHandler(async (event) => ({ url: event.node.req.url })),
+);
+```

docs/content/2.concepts/2.event.md

@@ -0,0 +1,20 @@
+---
+title: H3 Event
+description: Learn more about H3 event objects
+---
+
+H3 uses a unified event object to keep track of an incoming request shared between utilities.
+
+Properties:
+
+- `method`
+- `path`
+- `headers`
+- `handled`
+
+Methods:
+
+- `respondWith`
+-
+
+[[WIP]]

docs/content/2.concepts/3.event-handler.md

@@ -3,7 +3,7 @@ title: Routing
 description:
 ---
 
-The `app` instance created by `h3` uses a middleware stack (see [how it works](./src/app.ts)) with the ability to match route prefix and apply matched middleware.
+The [`app` instance](/concepts/app) created by `h3` uses a middleware stack 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.
 

docs/content/2.concepts/3.event.md

@@ -4,3 +4,5 @@ description:
 ---
 
 H3 has a concept of composable utilities that accept `event` (from `eventHandler((event) => {})`) as their first argument. This has several performance benefits over injecting them to `event` or `app` instances in global middleware commonly used in Node.js frameworks, such as Express. This concept means only required code is evaluated and bundled, and the rest of the utilities can be tree-shaken when not used.
+
+[[WIP]]

docs/content/2.concepts/4.router.md

@@ -15,3 +15,15 @@ description:
 #### Cache
 
 - `handleCacheHeaders(event, opts)`
+
+#### Legacy
+
+```js
+// Legacy middleware with 3rd argument are automatically promisified
+app.use(
+  fromNodeMiddleware((req, res, next) => {
+    req.setHeader("x-foo", "bar");
+    next();
+  }),
+);
+```

docs/content/2.concepts/5.composables.md

@@ -7,3 +7,22 @@ description:
 - `proxyRequest(event, { target, ...options })`
 - `fetchWithEvent(event, req, init, { fetch? }?)`
 - `getProxyRequestHeaders(event)`
+
+```js
+app.use(
+  "/api",
+  eventHandler((event) =>
+    proxyRequest(event, "https://example.com", {
+      // f.e. keep one domain unchanged, rewrite one domain and remove other domains
+      cookieDomainRewrite: {
+        "example.com": "example.com",
+        "example.com": "somecompany.co.uk",
+        "*": "",
+      },
+      cookiePathRewrite: {
+        "/": "/api",
+      },
+    }),
+  ),
+);
+```

docs/content/2.concepts/6.adapters.md

@@ -2,3 +2,5 @@
 title: Plain Adapter
 description:
 ---
+
+[[WIP]]

docs/content/4.utils/other.md

@@ -11,3 +11,4 @@ router.get(
     return { path: event.path, message: "Hello World!" };
   }),
 );
+app.use("/", () => {}, {});