{"id":13799485,"url":"https://github.com/d-band/koa-mapper","last_synced_at":"2025-04-11T05:22:22.802Z","repository":{"id":44933128,"uuid":"172418409","full_name":"d-band/koa-mapper","owner":"d-band","description":"A better and smart router middleware for koa.","archived":false,"fork":false,"pushed_at":"2022-07-31T22:21:30.000Z","size":51,"stargazers_count":39,"open_issues_count":3,"forks_count":1,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-05-01T22:54:50.896Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/d-band.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-02-25T02:14:28.000Z","updated_at":"2024-04-19T01:24:20.000Z","dependencies_parsed_at":"2022-09-24T22:23:09.391Z","dependency_job_id":null,"html_url":"https://github.com/d-band/koa-mapper","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d-band%2Fkoa-mapper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d-band%2Fkoa-mapper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d-band%2Fkoa-mapper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d-band%2Fkoa-mapper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/d-band","download_url":"https://codeload.github.com/d-band/koa-mapper/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248346361,"owners_count":21088445,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-04T00:01:03.239Z","updated_at":"2025-04-11T05:22:22.781Z","avatar_url":"https://github.com/d-band.png","language":"JavaScript","funding_links":[],"categories":["仓库"],"sub_categories":["中间件"],"readme":"# koa-mapper\n\n[![NPM version](https://img.shields.io/npm/v/koa-mapper.svg)](https://www.npmjs.com/package/koa-mapper)\n[![NPM downloads](https://img.shields.io/npm/dm/koa-mapper.svg)](https://www.npmjs.com/package/koa-mapper)\n[![Dependency Status](https://david-dm.org/d-band/koa-mapper.svg)](https://david-dm.org/d-band/koa-mapper)\n[![Build Status](https://travis-ci.org/d-band/koa-mapper.svg?branch=master)](https://travis-ci.org/d-band/koa-mapper)\n[![Coverage Status](https://coveralls.io/repos/github/d-band/koa-mapper/badge.svg?branch=master)](https://coveralls.io/github/d-band/koa-mapper?branch=master) [![Greenkeeper badge](https://badges.greenkeeper.io/d-band/koa-mapper.svg)](https://greenkeeper.io/)\n\n\u003e `koa-mapper` is a better and smart router middleware for koa. (Inspired by `koa-router`)\n\n* Support almost all features of `koa-router`\n* Support for parameters validation\n* Support parameters in `path`, `header`, `query`, `cookie`\n* Support body parser\n* Support request body validation\n* Support coerce data types of parameters and body\n* Support OpenAPI generation\n\n## Installation\n\n```bash\nnpm install koa-mapper\n```\n\n## Example\n\n```js\nimport Koa from 'koa';\nimport logger from 'koa-logger';\nimport Mapper from 'koa-mapper';\n\nconst app = new Koa();\n\napp.use(logger());\n\nconst mapper = new Mapper();\n\nmapper.get('/users/:id', {\n  params: {\n    id: { type: 'number' },\n    info: { type: 'User', in: 'query' }\n  }\n}, (ctx) =\u003e {\n  ctx.body = ctx.params;\n});\n\nmapper.post('/users', {\n  body: {\n    users: { type: 'array\u003cUser\u003e' }\n  }\n}, (ctx) =\u003e {\n  ctx.body = ctx.request.body;\n});\n\nmapper.define('User', {\n  id: { type: 'number', required: true },\n  name: { type: 'string', required: true }\n});\n\napp.use(mapper.routes());\napp.use(mapper.allowedMethods());\n\napp.listen(3000);\n\n// open http://localhost:3000/users/123?info[id]=456\u0026info[name]=hello\n// open http://localhost:3000/openapi.json\n```\n\n## API Reference\n\n### `new Mapper([options])`\n\n**Options**\n\n| Name | Type | Default | Description |\n| --- | --- | --- | --- |\n| prefix | `string` | `''` | the path prefix for a Mapper |\n| openURL | `string` or `false` | `/openapi.json` | OpenAPI route, `false` to disable OpenAPI |\n| bodyparser | `object` or `boolean` | `false` | `koa-body` options, `true|{}` to enable body parser |\n| throwParamsError | `function` or `boolean` | `utils.validateError` | Throw error for params invalid |\n| throwBodyError | `function` or `boolean` | `utils.validateError` | Throw error for body invalid |\n| validator | `object` | `{}` | [`ajv options`](https://github.com/epoberezkin/ajv#options) |\n| sensitive | `boolean` | `false` | `sensitive` option for [path-to-regexp](https://github.com/pillarjs/path-to-regexp) |\n| strict | `boolean` | `false` | `strict` option for [path-to-regexp](https://github.com/pillarjs/path-to-regexp) |\n\n### `mapper.get|put|post|del(path, [options], ...middlewares) =\u003e Mapper`\n\n```js\ntype options = {\n  name: string, // route name, default null\n  prefix: string, // route prefix, default ''\n  bodyparser: object|boolean, // like Mapper options.bodyparser\n  throwParamsError: function, // like Mapper options.throwParamsError\n  throwBodyError: function, // like Mapper options.throwBodyError\n  params: Params, // OpenAPI parameters definition\n  body: Body, // OpenAPI requestBody schema definition\n  ...others, // Fields of OpenAPI Operation Object\n}\n```\n\n\u003e More fields of [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#operation-object)\n\n```js\ntype Params = {\n  in: string, // parameter in: `path`, `query`, `header`, `cookie`\n  type: string, // parameter type\n  ...others, // Fields of OpenAPI Parameter Object\n}\n```\n\n\u003e More fields of OpenAPI [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#parameterObject)\n\n`type` support:\n\n* Basic type: `array`, `boolean`, `integer`, `null`, `number`, `object`, `string`, `date`, `time`, `datetime`, `regex`\n* Array type: `array\u003cstring\u003e`, `array\u003cnumber|string\u003e`\n* Custom type: `Pet`, `array\u003cPet\u003e`\n\n```js\ntype Body = string | {\n  [property]: Schema\n}\n```\n\nbody examples:\n\n* `body: 'Pet'` =\u003e `body: { $ref: 'Pet' }`\n* `body: { id: { type: 'number' } }` =\u003e `body: { type: 'object', properties: { id: { type: 'number' } }}`\n\n\n### `mapper.schema(name, properties, options) =\u003e Mapper` alias `mapper.define()`\n\n```js\nmapper.schema('Tag', {\n  id: { type: 'integer', format: 'int64' },\n  name: { type: 'string' }\n});\nmapper.schema('Category', {\n  id: { type: 'integer', format: 'int64' },\n  name: { type: 'string' }\n});\nmapper.schema('Pet', {\n  id: { type: 'integer', format: 'int64' },\n  category: { type: 'Category' },\n  name: { type: 'string' },\n  photoUrls: { type: 'array\u003cstring\u003e' },\n  tags: { type: 'array\u003cTag\u003e' },\n  status: { type: 'string', enum: ['available', 'pending', 'sold'] }\n}, {\n  required: ['name', 'photoUrls']\n});\n```\n\nSupport type extends:\n\n```js\nmapper.schema('Model', {\n  id: { type: 'number' },\n  createdAt: { type: 'datetime' },\n  updatedAt: { type: 'datetime' }\n});\nmapper.schema('User: Model', {\n  name: { type: 'string' }\n});\n```\n\n### BodyParser\n\n```js\nmapper.post('/users', {\n  body: 'User'\n}, (ctx) =\u003e {\n  const { id, name } = ctx.request.body;\n});\n```\n\nMultipart and file upload:\n\n```js\nmapper.post('/uploadImage', {\n  bodyparser: { multipart: true },\n  body: {\n    user: { type: 'number' },\n    image: { type: 'file' }\n  }\n}, (ctx) =\u003e {\n  const { user, image } = ctx.request.body;\n});\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fd-band%2Fkoa-mapper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fd-band%2Fkoa-mapper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fd-band%2Fkoa-mapper/lists"}