Skip to content

Latest commit

 

History

History
96 lines (70 loc) · 5.01 KB

getting-started.md

File metadata and controls

96 lines (70 loc) · 5.01 KB

Getting started

Motivation

The goal of this project is to enable developers to take advantage of the simplicity & minimalism of paperplane while retaining all the advanced features of koa. This gives us the best of both frameworks:

  • Developers can continue to quickly develop simple, minimalistic code in a "functional-programming" style.
  • Developers can also use the full koa context for more advanced workflows that do not easily fit into a "functional-programming" style, while also allowing us to take advantage of the expansive Koa ecosystem.

Please review both koa & paperplane if you're not familiar with these frameworks.

Basic concepts

This library provides a mount function that converts a pure, paperplane function handler into koa v2 middleware. The function accepts a request-like input & resolves with a response-like output:

const Koa = require('koa')
const { mount } = require('@articulate/koala')

const handler = req => ({
  body: null,
  headers: {},
  statusCode: 200,
})

const server = new Koa()
server.use(mount(handler))

server.listen(3000)

Request object

An abbreviated port of paperplane's Request object.

Property Type Details
body Any request body, passed through from ctx.request.body
cookies Object map of cookies, parsed in from the cookie header
headers Object map of headers, with downcased header names as keys
method String request method, should be uppercase
params Object map of named route parameters, passed through from ctx.params
pathname String just the path portion of the request url
protocol String https if connection is encrypted, otherwise http
query Object map of query string parameters
url String the full request url

Response object

Port of paperplane's Response object.

Your handler function needs to return a Response object, or a Promise that resolves to one.

Property Type Details
body Buffer, Readable, String can also be falsy for an empty body
headers Object defaults to {}
statusCode Number defaults to 200

Errors

Like paperplane, this library will support boom, http-errors, & joi errors.

Like Koa, if the status code is a client-error, 400-level error status, the error's message & payload, if applicable, will be used as the response body. The response body will be omitted on server-error, 500-level errors. You can override this behavior by setting the expose property to true or false on the error.

An error will be emitted to the koa application if one of the following is true:

  • The response's status code is greater than or equal to 500.
  • The error encountered contains a cry: true property.
const Boom = require('boom')
const Koa = require('koa')
const Router = require('koa-router')
const { mount } = require('@articulate/koala')

const router = new Router()
router.get('/error', mount(() => { throw new Error() })) // emits error
router.get('/boom-server', mount(() => { throw Boom.internal() })) // emits error
router.get('/boom-client', mount(() => { throw Boom.notFound() }) // does not emit error
router.get('/cry', mount(() => { throw Object.assign(Boom.notFound(), { cry: true }) }) // emits error

const cry = err =>
  console.error(err)

const server = new Koa()
server.on('error', cry)
server.use(router.routes())
server.use(router.allowedMethods())

server.listen(3000)