koa-stark

This module provides a set of koa middleware and optional CRUD resource(s). Middleware include:

• koa-response-time
• koa-helmet
• @koa/cors
• koa-compress
• koa-conditional-get
• koa-etag
• koa-respond
• koa-body
• koa-pino-logger
• swagger2-koa

Installation

Install using npm:

npm install johnschult/koa-stark

Usage

const Koa = require('koa')
const stark = require('koa-stark')
const app = new Koa()

app.use(stark(options, app))

app.listen(9000)

The above creates a koa server with koa-stark middleware, where:

• options - optional, object where:
  • basePath - optional, a base path to serve requests from, e.g. '/api'
  • mongo - required if swagger.spec includes paths that require CRUD, a standard MongoDB connection string
  • logging - optional, if set to true will use koa-pino-logger
  • swagger - optional, an object where:
    • validate - optional, if set to true will validate requests and responses using swagger2-koa.validate
    • ui - optional, if set to true will serve a Swagger UI at options.basePath using swagger2-koa.ui
  • resources - optional, an array of objects where:
    • name - required, the name the resource, e.g. 'Robot'
    • path - required, the path to the resource, e.g. '/v1/clients'
    • mongooseSchema - optional, the resource schema, a mongoose.Schema object, if provided, a CRUD controller and routes will be generated for this resource
    • swaggerSchema - required, an OpenAPI 2.0 Definitions Object

Resources

If resources is defined in options, the following routes are defined for each resource:

• GET /<basePath>/<path>/ - Returns an array of all the models
• POST /<basePath>/<path>/ - Creates a new model
• GET /<basePath>/<path>/:id - Finds a model by ID
• PUT /<basePath>/<path>/:id - Updates an existing model
• DELETE /<basePath>/<path>/:id - Deletes a model
• GET /<basePath>/<path>/:id/exists - Checks whether a model exists
• GET /<basePath>/<path>/count - Returns a count of all the models

Watching Resources

A route is added using socket.io to enable watching individual or all model instance(s). In order to utilize the watch route, a socket.io connection needs to be made. For example:

const io = require('socket.io-client')

const socket = io('ws://localhost:9006/api/v1/robots/watch')

Events

Client

• watch - Used to define the resources and operations you are interested in observing, optional object where:
  • id - optional, the resource id
  • operationType - optional, any of insert, update, delete as a comma separated string

Server

• change - The server emits changes to this event. A single argument is sent to the callback containing the change data.

Examples

Watch all operations on all resource instances:

const io = require('socket.io-client')

const socket = io('ws://localhost:9006/api/v1/robots/watch')

socket.on('connect', () => {
  socket.emit('watch')
})

socket.on('change', data => {
  console.log(data)
})

socket.on('disconnect', () => {
  process.exit()
})

Watch all update operation on a single resource instances and disconnect after first change is emitted:

const io = require('socket.io-client')

const socket = io('ws://localhost:9006/api/v1/robots/watch')

socket.on('connect', () => {
  socket.emit('watch', {
    operationType: 'update',
    id: '5af2fe000e488a70acf4be22',
    disconnect: true
  })
})

socket.on('change', data => {
  console.log(data)
})

socket.on('disconnect', () => {
  process.exit()
})

Example

A simple koa application is included in the example directory.

koa-stark is opinionated about the database being used and requires that you use MongoDB. Before running the example make changes to mongo in example/config.js as needed.

To run this example:

$ git clone https://github.com/johnschult/koa-stark
$ cd koa-stark && npm install
$ npm run mongod
$ npm run example

Browse to http://localhost:9006/api to use the example OpenAPI 2.0 UI.