# effectsloop-server-utils

> Utilities useful for spinning up servers

Latest version **1.8.0** (published 2020-08-30) · ISC license · 0 weekly downloads

## Install

```sh
npm install effectsloop-server-utils
pnpm add effectsloop-server-utils
yarn add effectsloop-server-utils
bun add effectsloop-server-utils
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.8.0 |
| Published | 2020-08-30 |
| First published | 2019-03-30 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 5 |
| Unpacked size | 23.4 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Jared Selcoe and Jordan Namer |
| Maintainers | effects-loop |

## Links

- npm: https://www.npmjs.com/package/effectsloop-server-utils
- Repository: https://github.com/effects-loop/server-utils
- Homepage: https://github.com/effects-loop/server-utils#readme
- Issues: https://github.com/effects-loop/server-utils/issues
- npm.io page: https://npm.io/package/effectsloop-server-utils

## Dependencies (5)

- [koa](https://npm.io/package/koa.md) ^2.8.1
- [bunyan](https://npm.io/package/bunyan.md) ^1.8.12
- [@koa/cors](https://npm.io/package/@koa/cors.md) ^3.0.0
- [@koa/router](https://npm.io/package/@koa/router.md) ^8.0.1
- [koa-bodyparser](https://npm.io/package/koa-bodyparser.md) ^4.2.1

## Recent versions

- 1.8.0 (latest) — 2020-08-30
- 1.7.0 — 2020-07-27
- 1.6.0 — 2020-04-27
- 1.5.0 — 2020-04-26
- 1.4.0 — 2020-04-26
- 1.3.0 — 2019-09-23
- 1.2.1 — 2019-09-09
- 1.2.0 — 2019-09-09
- 1.1.0 — 2019-09-09
- 1.0.10 — 2019-04-05
- 1.0.9 — 2019-04-04
- 1.0.8 — 2019-04-04
- 1.0.7 — 2019-03-31
- 1.0.6 — 2019-03-31
- 1.0.5 — 2019-03-31
- … 4 more at https://npm.io/package/effectsloop-server-utils/versions

## README

# 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
| Name | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| **`port`** * | Number | **Required** | The port for the server to listen on. |
| `name` * | String | | Server name for use in logging. Is _REQUIRED_ if you do not provide a `log` argument, as `buildServer` expects one of the two. |
| `log` | Bunyan Logger | | The Bunyan logger you would like to use to log requests. Recommended to be generated by `buildLogger`. |
| `logPath` | String | | The folder path where you want to store your log files. |
| | | | When not passed, output is sent to the console. |
| | | | When passed, output is sent to a file in the specified directory with the syntax `[logPath].log`. The log file is rotated out once per day, and 3 days of logs plus the current day are held as per the [Bunyan spec](https://github.com/trentm/node-bunyan#stream-type-rotating-file). |
| `routes` | Array[buildRouter()] | | Array of routes to use built with the `buildRouter` API fn. |
| `beforeStartup` | Function(log) => Promise | | Anything you want to happen before we start listening on a port, such as connecting to a DB. It must be a function that returns a Promise. The function is passed the `log` for use before the server starts listening. |
| `noLogging` | Boolean | `false` | Whether you want each request to be logged via the logging middleware. |
| `allowCors` | Boolean | `false` | Whether you want to allow CORS for the server. |
| `middleware` | Array[fn()] | | Array of middleware you would like to use. They are applied right before your routes. |
| `requestBodyMaxLoggingLen` | Number | `500` | The max length of the request body that you want to log - anything afterwards is truncated. Only matters if `noLogging` is not set. |
| `responseBodyMaxLoggingLen` | Number | `500` | The max length of the response body that you want to log - anything afterwards is truncated. Only matters if `noLogging` is not set. |

### Returns
| Name | Type | Description |
| ---- | ---- | ----------- |
| `app` | Koa server | This way you can do anything else you want to the server. |
| `log` | Bunyan logger | This is used by the request/response logging middleware, and is also provided here for you to call as you want. |

### 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:

| Name | Type | Description |
| ---- | ---- | ----------- |
| `responseStatus` | Number | The response status. |
| `method` | String | The request method. |
| `url` | String | The request url. |
| `body` | String or Object | The request body. |
| | | Top-level `token` and `password` keys are logged as `*******`. |
| | | Because request bodies can get long, logs of them are truncated to 500 characters by default. You can override this on a per-request basis with `ctx.state.requestBodyMaxLoggingLen`, or for all requests with the `requestBodyMaxLoggingLen` argument as described above. |
| `ip` | String | The IP of the request. |
| `responseTime` | Number | The response time in ms. |
| `responseBody` | Object or Undefined | The response body. |
| | | Top-level `token` and `password` keys are logged as `*******`. |
| | | Because response bodies can get long, logs of them are truncated to 500 characters by default. You can override this on a per-request basis with `ctx.state.responseBodyMaxLoggingLen`, or for all requests with the `responseBodyMaxLoggingLen` argument as described above. |
| `id` | String | The UUID of the 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
| Name | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| **`name`** * | String | **Required** | The name of the logger that will be generated (this shows up in logs, and would typically be your server name). |
| `logPath` | String | | The folder path where you want to store your log files. |
| | | | When not passed, output is sent to the console. |
| | | | When passed, output is sent to a file in the specified directory with the syntax `[logPath].log`. The log file is rotated out once per day, and 3 days of logs plus the current day are held as per the [Bunyan spec](https://github.com/trentm/node-bunyan#stream-type-rotating-file). |

### Returns
| Name | Type | Description |
| ---- | ---- | ----------- |
| n/a | Bunyan logger instance. | An instance of a Bunyan logger. |

## buildRouter

Used to build a Koa router.

Ex:
```
const router = buildRouter('/users')

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

### Arguments
| Name | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| n/a | String or Object (koa router options) | | When a String, is the route prefix to use. When an Object, is assumed to be [koaRouterOptions](https://www.npmjs.com/package/@koa/router). |

### Returns
| Name | Type | Description |
| ---- | ---- | ----------- |
| n/a | Router instance | An instance of a Koa `Router` for you to apply `router.post`, `router.get`, etc routes to. |

## 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

| Name | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| **`response`** * | Object | **Required** | Koa response. |
| **`state`** * | Object | **Required** | Koa state. |
| **`err`** * | Error | **Required** | The thrown error. |
| `msg` | Object or String | | The error response to use for all error cases. _See below._ |
| `options` | Object | | The different possible error responses to use. _See below._ |
| `StructError` | StructError | | The error class to use for data structure validation checks - an `err instanceof StructError` check will be used on it, and if there is a match, the passed `err` shape is expected to match the shape of [superstruct errors](https://www.npmjs.com/package/superstruct). |

* `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 }
```

---
_Source: https://npm.io/package/effectsloop-server-utils · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
