@4lch4/koa-oto

This library is a responder library for handling responses within the Koa framework.

!!! warning v2.0.0 Upgrade With the release of v2.0.0, this package is now a pure ESM package. If you're unsure what that means or would simply like some more information then I highly recommend you read this GitHub Gist (Pure ESM Package) from the legendary Sindresorhus.

If you still want to use this package before the ESM switch, you'll want the [`v1.3.2`](https://www.npmjs.com/package/@4lch4/koa-oto/v/1.3.2) release.

If you have any questions, comments, or concerns, please don't hesitate to [file an issue](https://git.4lch4.io/4lch4/Koa-Oto/issues) and I'll reply ASAP.

The Name

The name "Koa-Ōtō" is a combination of Koa (duh), and the Japanese Romaji version of 応答 (Ōtō) which means "Respond".

NOTE: According to Google Translate at least 😅

Example Usage

It isn't much, but this is the most basic way to use the library within your API:

import { ClientErrors, Successful } from '@4lch4/koa-oto'
import Router from '@koa/router'
import Koa from 'koa'

const app = new Koa()
const router = new Router()

router.get('/', async ctx => Successful.ok(ctx, 'Hello World'))
router.get('/error', ctx => ClientErrors.badRequest(ctx, 'Bad Request'))

app.use(router.routes())
app.use(router.allowedMethods())

app.listen(3000, () => {
  console.log('Server is running on port 3000')
})

Simple Auth Helper Usage

I recently added the SimpleAuthHelper class, also as part of the v2.0.0 release, that is designed to be used by the author (@4lch4) so I do not recommend anyone else use it, but I figured I'd document it just in case.

Using the same example server from above, if we want to secure just one of the routes, we'd do something like so:

router.get('/secure', async ctx => {
  const authenticated = new SimpleAuthHelper().authenticateRequest(ctx)

  if (authenticated) Successful.ok(ctx, 'Request was authenticated!')
  else ClientErrors.unauthorized(ctx)
})

Auth Check Details

All the authenticateRequest method does is the following:

• Check the request for an API token.
  • Checks for an Authorization header with a value that starts with Token.
  • If no header is found, it checks for an apiToken query parameter.
• If an API token is found in the previous step, compare it to the API token that was set when instantiating the SimpleAuthHelper class.
  • If you don't provide an API token to the constructor then it'll attempt to pull the value from the API_REQUEST_TOKEN environment variable.
  • If the environment variable isn't set then the token will be set to a random generated string generated in order to avoid any unintentional authorization.

Testing and Coverage

I went a really weird route for testing this library, but in the end I've achieved a solid coverage percentage in CodeCov. The following images are an icicle and grid representation of the current test coverage:

Icicle: The top section represents the entire project. Proceeding with folders and finally individual files. The size and color of each slice is representing the number of statements and the coverage, respectively.

Grid: Each block represents a single file in the project. The size and color of each block is represented by the number of statements and the coverage, respectively.