koa-framework

5.4.3 • Public • Published

koa-framework

Dead simple framework on top of koa

NPM version build status David deps

node version io version

Koa framework is a basic bootstrap library for creating a Koa server. It provides a router constructor with basic middleware such as a request parser and validator.

Usage

Step 1 - Add the base koa server as a dependency

npm install koa-framework --save

Step 2 - Create an app

A koa instance is returned so see koa documentation for more details.

let koa = require('koa-framework');
 
// koa server instance
let app = koa();

Step 2 - Add some app logic

Request body is automatically parsed using koa-body-parser. Both json and form encodings are supported.

Create router instance

See koa-router documentation for detailed documentation.

let router = app.router();
 
router.get('/test', function *() {
    this.body = 'Wow! just like Express';
});
 
// mount router
app.mount(router);

Data validation

One of the key aspects of a web application is data validation. koa-framework supports request data validation using jsonschema. If data does not pass validation, the server returns a 400 Bad Request error. In non production environments, the response body is populated with the validation errors.

let schema = {
    params: {
        properties: {
            object: { type: 'string', required: true }
        }
    },
    query: {
        properties: {
            something: { type: 'string', required: false } }
        }
    },
    body: {
        properties: {
            password: { type: 'string', required: true, minLength: 10 }
        }
    }
};
router.post('/secret/:object', app.schema(schema), function *() {
    let body = this.request.body;
 
    if (body.password === 'the best password ever') {
        this.body = 'You got it boss';
    } else {
        this.throw(403, 'Pffttt...');
    }
});

The server returns the following response body on schema validation error. The validationErrors property is the errors property returned by jsonschema on validation.

{
    "error": "Invalid request parameters",
    "validationErrors": [{
        "property": "request.body",
        "message": "Property password is required",
        "schema": { ... },
        "instance": ...
    }]
}

Namespaced routes and middleware

// private routes
let paymentsRouter = app.router({
    prefix: '/payments'
});
 
// middleware for /payments/*
paymentsRouter.use(ensureAuthenticated);
 
// POST /payments/transfer
paymentsRouter.post('/transfer', handleTransfer);
 
 
// public routes
let sharedRouter = app.router({
    prefix: '/shared'
});
 
// GET /shared/lolcat
sharedRouter.get('/lolcat', getLolcat);
 
app.mount(paymentsRouter, sharedRouter);
 
// alternatively
app.mount(paymentsRouter);
app.mount(sharedRouter);

Step 3 - Kick off the server

app.listen();

Bundled middleware

koa-framework comes bundled with koa-body-parser, koa-error and koa-x-request-id

Configuration

Middlewares are completely configurable with options being passed to the downstream middleware as is. Optionally, individual middlewares can also be turned off completely. An example is shown below:

var app = koa({
    middleware: {
        error: { enabled: false },
        parse: { jsonLimit: '512kb' },
        requestId: { key: 'x-request-id'. inject: false }
    }
});

Changelog

Readme

Keywords

Package Sidebar

Install

npm i koa-framework

Weekly Downloads

34

Version

5.4.3

License

MIT

Unpacked Size

22.7 kB

Total Files

14

Last publish

Collaborators

  • jksdua