README.md

koa-mapper

koa-mapper is a better and smart router middleware for koa. (Inspired by koa-router)

• Support almost all features of koa-router
• Support for parameters validation
• Support parameters in path, header, query, cookie
• Support body parser
• Support request body validation
• Support coerce data types of parameters and body
• Support OpenAPI generation

Installation

npm install koa-mapper

Example

import Koa from 'koa';
import logger from 'koa-logger';
import Mapper from 'koa-mapper';

const app = new Koa();

app.use(logger());

const mapper = new Mapper();

mapper.get('/users/:id', {
  params: {
    id: { type: 'number' },
    info: { type: 'User', in: 'query' }
  }
}, (ctx) => {
  ctx.body = ctx.params;
});

mapper.post('/users', {
  body: {
    users: { type: 'array<User>' }
  }
}, (ctx) => {
  ctx.body = ctx.request.body;
});

mapper.define('User', {
  id: { type: 'number', required: true },
  name: { type: 'string', required: true }
});

app.use(mapper.routes());
app.use(mapper.allowedMethods());

app.listen(3000);

// open http://localhost:3000/users/123?info[id]=456&info[name]=hello
// open http://localhost:3000/openapi.json

API Reference

new Mapper([options])

Options

Name	Type	Default	Description
prefix	string	''	the path prefix for a Mapper
openURL	string or false	/openapi.json	OpenAPI route, false to disable OpenAPI
bodyparser	object or boolean	false	koa-body options, `true
throwParamsError	function or boolean	utils.validateError	Throw error for params invalid
throwBodyError	function or boolean	utils.validateError	Throw error for body invalid
validator	object	{}	ajv options
sensitive	boolean	false	sensitive option for path-to-regexp
strict	boolean	false	strict option for path-to-regexp

mapper.get|put|post|del(path, [options], ...middlewares) => Mapper

type options = {
  name: string, // route name, default null
  prefix: string, // route prefix, default ''
  bodyparser: object|boolean, // like Mapper options.bodyparser
  throwParamsError: function, // like Mapper options.throwParamsError
  throwBodyError: function, // like Mapper options.throwBodyError
  params: Params, // OpenAPI parameters definition
  body: Body, // OpenAPI requestBody schema definition
  ...others, // Fields of OpenAPI Operation Object
}

More fields of Operation Object

type Params = {
  in: string, // parameter in: `path`, `query`, `header`, `cookie`
  type: string, // parameter type
  ...others, // Fields of OpenAPI Parameter Object
}

More fields of OpenAPI Parameter Object

type support:

• Basic type: array, boolean, integer, null, number, object, string, date, time, datetime, regex
• Array type: array<string>, array<number|string>
• Custom type: Pet, array<Pet>

type Body = string | {
  [property]: Schema
}

body examples:

• body: 'Pet' => body: { $ref: 'Pet' }
• body: { id: { type: 'number' } } => body: { type: 'object', properties: { id: { type: 'number' } }}

mapper.schema(name, properties, options) => Mapper alias mapper.define()

mapper.schema('Tag', {
  id: { type: 'integer', format: 'int64' },
  name: { type: 'string' }
});
mapper.schema('Category', {
  id: { type: 'integer', format: 'int64' },
  name: { type: 'string' }
});
mapper.schema('Pet', {
  id: { type: 'integer', format: 'int64' },
  category: { type: 'Category' },
  name: { type: 'string' },
  photoUrls: { type: 'array<string>' },
  tags: { type: 'array<Tag>' },
  status: { type: 'string', enum: ['available', 'pending', 'sold'] }
}, {
  required: ['name', 'photoUrls']
});

Support type extends:

mapper.schema('Model', {
  id: { type: 'number' },
  createdAt: { type: 'datetime' },
  updatedAt: { type: 'datetime' }
});
mapper.schema('User: Model', {
  name: { type: 'string' }
});

BodyParser

mapper.post('/users', {
  body: 'User'
}, (ctx) => {
  const { id, name } = ctx.request.body;
});

Multipart and file upload:

mapper.post('/uploadImage', {
  bodyparser: { multipart: true },
  body: {
    user: { type: 'number' },
    image: { type: 'file' }
  }
}, (ctx) => {
  const { user, image } = ctx.request.body;
});

License

MIT