Merge pull request #11 from jacobwgillespie/v2

README.md

@@ -2,13 +2,20 @@
 
 Zap is a lightweight HTTP server framework for Node.
 
+- [Installation](#installation)
+- [Usage](#usage)
+- [API](#api)
+- [Recipes](#recipes)
+- [Credits](#credits)
+- [License](#license)
+
 ## Installation
 
 Install with your favorite package manager:
 
 ```shell
-$ yarn add zap
 $ pnpm add zap
+$ yarn add zap
 $ npm install zap
 ```
 
@@ -27,6 +34,70 @@ const server = http.createServer(serve(app))
 server.listen(3000)
 ```
 
+## API
+
+### `serve(handler, options)`
+
+Constructs a new `http.RequestListener` out of a `Handler`.
+
+### `router(...routes)`
+
+Constructs a new `Handler` out of a list of `RouteHandlers`.
+
+### `route(method, path, handler)`
+
+Constructs a `RouteHandler` that matches a given method (`GET`, `POST`, etc) and path.
+
+### Body parsers
+
+- `buffer(req, options)` - read the request body as a `Buffer`
+- `text(req, options)` - read the request body as a string
+- `json(req, options)` - read the request body as parsed JSON
+
+### Request helpers
+
+- `getHeader(req, header)` - returns the requested header if it was provided
+- `fromRequest(fn)` - wraps a function in the form `(req: ServerRequest, ...rest) => any` to return an equivalent function that caches its results for the provided request
+
+### Response helpers
+
+- Ordinarily you would return a `ResponseBodyType` from a `Handler` function
+- `send(res, statusCode, body)` - a response with a given status code
+- `notFound()` - a 404 response
+- `redirect(location, statusCode)` - a redirect to another location (default status code 303)
+- `httpError(code, message, metadata)` - an error response with a given code, message, and optional metadata
+
+## Recipes
+
+### Validating body schema
+
+You can use a function that throws an `httpError` to provide type-safe body payload parsing:
+
+```typescript
+async function parseBody(req: ServerRequest) {
+  const body = await json(req)
+  if (!validate(body)) throw httpError(400, 'invalid body')
+  return body
+}
+
+route('POST', '/example', (req) => {
+  const body = await parseBody(req)
+  // body is now typed according to your parseBody return type
+})
+```
+
+### Error handling
+
+The `serve()` function options accept an `errorHandler` that will replace `zap`'s built-in error handler. This allows you to report errors to services like Sentry, format the response sent to the user, etc.
+
+```typescript
+serve(handler, {
+  errorHandler: (_, res, error) => {
+    send(res, 500, {message: 'Internal server error', details: formatError(error)})
+  },
+})
+```
+
 ## Credits
 
 Special thanks to [@nornagon](https://github.com/nornagon) for the `zap` package name. For versions of this module published before `v1.0.0`, see [nornagon/node-zap](https://github.com/nornagon/node-zap).