A library for responding to requests within the Koa framework.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
Go to file
4lch4 a385205928
continuous-integration/drone/push Build is passing Details
continuous-integration/drone Build is passing Details
Merge branch 'develop' into main
3 months ago
sample feat: updated sample 1 year ago
src feat: updated library to be pure ESM 3 months ago
tests feat: updated library to be pure ESM 3 months ago
.drone.yml tmp: commented out npm test 3 months ago
.gitignore feat: added .dccache to .gitignore 3 months ago
.npmignore chore: added .npmignore 3 months ago
.nvmrc chore: added .npmrc/.nvmrc 1 year ago
.nycrc.json chore: executed prettier 3 months ago
.prettierignore fix: fixed issues with prettier 3 months ago
.prettierrc chore: executed prettier 3 months ago
README.md feat: updated README w/ SimpleAuthHelper details 3 months ago
package.json 2.0.0 3 months ago
pnpm-lock.yaml feat: updated library to be pure ESM 3 months ago
publish.sh feat: added a publish script 1 year ago
tsconfig.json feat: updated library to be pure ESM 3 months ago

README.md

Drone (self-hosted) with branch Codecov Codacy Badge

NPM Standard-Js

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

Code-Coverage-Icicle

Code-Coverage-Tree

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.