Skip to content

Latest commit

 

History

History
107 lines (72 loc) · 3.03 KB

README.md

File metadata and controls

107 lines (72 loc) · 3.03 KB
Raw

⚡ zap npm CI

Zap is a lightweight HTTP server framework for Node.

Installation

Install with your favorite package manager:

$ pnpm add zap
$ yarn add zap
$ npm install zap

Usage

import {route, router, serve} from 'zap'

const app = router(
  route('GET', '/', () => 'Hello World'),

  route('GET', '/hello/:name', (req) => `Hello ${req.params.name}`),
)

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:

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.

serve(handler, {
  errorHandler: (_, res, error) => {
    send(res, 500, {message: 'Internal server error', details: formatError(error)})
  },
})

Credits

Special thanks to @nornagon for the zap package name. For versions of this module published before v1.0.0, see nornagon/node-zap.

License

MIT License, see LICENSE.