effectsloop-server-utils v1.8.0

Who Is This For?

I made this for myself as I spin up new servers for solo projects. So it's a bit opinionated.

It's served me well so I thought I'd make it available to anyone who wants it. Also, I wanted access to it as an NPM package, and splurging to make this lib private felt unnecessary.

It uses Koa under the hood because I like how lightweight it is, so this is also for people who are not wed to Express.

What Is Its Purpose?

• Building an extendable server with some default middleware, and an optional logging middleware (buildServer).
• Building a logger than can be used throughout your app and consumed by buildServer (buildLogger).
• Building routes that you pass to the server builder (buildRouter).
• Handling errors with a syntax that is self-documenting (handleError).

Core Concepts

• Information is persisted across a request's lifespan via the request's ctx.state object.
  • When the core buildServer function's default logging middleware is left enabled and the optional handleError fn is used, you will find that your response status is reflected in your logging level (info, warn, error), as well as some other niceties. This is thanks to information that is persisted to ctx.state.warning and ctx.state.err.
• Every request has a unique UUID assigned to it, stored in ctx.state.id.
• Every request's start time is stored in ctx.state.start as a Date.now() value.
• It should be simple to tell what types of responses you'll get from a route, so the handleError is intended to receive arguments in a way that is relatively self-documenting. Unless you specifically specify otherwise, the error message from a thrown error will be returned in the server response body.
• I assume that every request body is either empty or an object.
• I assume that every response body is either empty or an object.

API

buildServer

Used to build the base Koa server and Bunyan logger, with optional middleware.

Ex:

const { app, log } = buildServer({ name: 'my-server', port: 8080, routes: routesArray })

Arguments

Returns

Logging In Depth

When the logging middleware is enabled, each request gains several features:

• Access to a logger which automatically includes the id of the request at ctx.state.log. It enables ctx.log.info, ctx.log.warn, and ctx.log.error calls from within routes.
• Logging an info output on successful requests, a warn on requests with ctx.state.warning, and an error on requests with ctx.state.err. Because of this, I recommend using this middleware in conjunction with the handleError function that is also exposed by this library, as it leverages the paradigm.
• Logging the following information upon completion of every request:

buildLogger

Used to build a Bunyan logger.

Ex:

const log = buildLogger({ name: 'my-server', logPath: './optionalLogFolderPath' })
const { app } = buildServer({ log, port: 3000 })

log.info('Something to show')

Arguments

Returns

buildRouter

Used to build a Koa router.

Ex:

const router = buildRouter('/users')

router.post('/sign-up', async ({ request, response, state }) => { ... })

Arguments

Returns

handleError

Used to handle errors in your routes with a self-documenting API.

Ex:

router.post('/sign-up', async ({ request, response, state }) => {
  try {
    // route logic here
  } catch (err) {
    const options = {
      emailTaken: 409,
      usernameTaken: {
        status: 409,
        message: 'That username is already taken',
        code: 'userTaken',
      },
      defaultMessage: 'Something broke while attempting to sign up',
    }
    handleError({ response, state, err, options })
  }
})

Arguments

• msg:

{
  message: String (non-empty),
  status: Number (optional, 500 default),
  code: String (optional)
}

OR

String (returns 500)

• options:

{
  [optionCode]:
    {
      status: Number,
      isError: Bool (optional, if true state.err = err, else state.warning = (message || err.message)),
      message: String (optional, overrides err.message as returned error.message),
      code: String (optional, overrides optionCode as returned error.code),
      noCode: Bool (optional, when true no error.code is returned)
    },

    OR

    Number (status to return, which means the thrown err.message and err.code are sent; if >= 500, state.err = err)
  ...
  defaultMessage: same as msg
}

Pass either but not both msg and options.

• If neither is provided then a 500 is sent automatically with a generic error.
• If only options are passed, and the thrown error.code key does not match any options (options[error.code]), and no options.defaultMessage is passed, then a 500 is sent automatically with a generic error.
• If both are provided then a warning is logged and the msg is used.

Responses

Standard errors have the format:

{
  error: {
    message: String (msg.message || msg || options[err.code].message || options[err.code])
    code: String (options[err.code].code || err.code) // Not sent for generic errors, or when options[err.code].noCode is passed
  }
}

Validation (struct) errors have the format:

{
  error: {
    message: String
    fields: {
      [fieldName]: validation error message,
      ...
    }
  }
}

Everything In Action

Define Routes

const { buildRouter } = require('effectsloop-server-utils')

const users = require('./someUserModule')
const handleError = require('./handleError')

const router = buildRouter('/users')

router.post('/sign-up', async ({ request, response, state }) => {
  try {
    // route logic here
  } catch (err) {
    const { validationErrors } = users.signUp

    // The codes for errors that could be thrown, and the info to send back for those errors
    // 4xx errors will log a warning, and the message from the error will be sent in the
    // the response body as { error: { message: error message } }
    // The defaultMessage logs an error, and the response body is { error: { message: defaultMessage } }
    const options = {
      [validationErrors.EMAIL_TAKEN]: 409,
      [validationErrors.USERNAME_TAKEN]: {
        status: 409,
        message: 'That username is already taken',
        code: 'userTaken',
      },
      defaultMessage: 'Something broke while attempting to sign up',
    }

    handleError({ response, state, err, options })
  }
})

router.post('/delete-account', async ({ request, response, state }) => {
  try {
    // route logic here
  } catch (err) {
    // No route-specific errors are anticipated here, so any error results in a 500
    // with { error: { message: msg } }
    handleError({ response, state, err, msg: 'Something broke while attempting to delete account' })
  }
})

module.exports = router

Extend handleError If Needed

const { handleError } = require('effectsloop-server-utils')
const { StructError } = require('superstruct')

const { DBError, ValidationError } = require('../lib/Errors')
const { users } = require('../repo')

module.exports = ({ response, state, err, msg, options }) => {
  // Handle route-agnostic DBErrors here so that you can avoid defining this handling in multiple routes
  if (err instanceof DBError) {
    response.status = 500
    response.body = { error: { message: 'An error occured in the DB', code: 'dbError' } }
    state.err = err // eslint-disable-line no-param-reassign
    return
  }

  // Handle route-agnostic ValidationErrors here so that you can avoid defining this handling in multiple routes
  const { INVALID_EMAIL, DEACTIVATED_ACCOUNT, UNVERIFIED_ACCOUNT } = users.genericValidationErrors
  if (
    err instanceof ValidationError &&
    [INVALID_EMAIL, DEACTIVATED_ACCOUNT, UNVERIFIED_ACCOUNT].includes(err.code)
  ) {
    const { code, message } = err
    response.status = code === INVALID_EMAIL ? 401 : 409
    response.body = { error: { message, code } }
    state.warning = 'Generic user validation failed' // eslint-disable-line no-param-reassign
    return
  }

  // Handle route-specific errors as you've defined in each route
  handleError({ response, state, err, msg, options, StructError })
}

Create The Logger and Server

const { buildLogger, buildServer } = require('effectsloop-server-utils')

const connectToDB = require('./connectToDB')
const userRoutes = require('../userRoutes')

const { SERVER_PORT } = process.env

const connectToDB = log = new Promise((resolve, reject) => {
  // DB connection logic here
  db.on('error', err => {
    log.error({ err }, 'Connection error')
    reject()
  })

  db.on('open', () => {
    log.info('Connected to the DB!')
    resolve()
  })
})

// Instead of building here, could pass `name` to buildServer and get `{ app, log }` from it
const log = buildLogger({ name: 'user-service' })

// The only unused option here is noLogging
const { app } = buildServer({
  log,
  routes: [userRoutes],
  port: SERVER_PORT,
  allowCors: true,
  requestBodyMaxLoggingLen: 300,
  responseBodyMaxLoggingLen: 400,
  beforeStartup: connectToDB,
})

module.exports = { app, log }