.verb.md
# {%= name %} {%= badge('npm') %} {%= badge('downloads') %} [![npm total downloads][downloads-img]][downloads-url]
> {%= description %}
[![codeclimate][codeclimate-img]][codeclimate-url]
[![codestyle][standard-img]][standard-url]
[![linux build][travis-img]][travis-url]
[![windows build][appveyor-img]][appveyor-url]
[![codecov][coverage-img]][coverage-url]
[![dependency status][david-img]][david-url]
_You might also be interested in [gibon][] - a minimal & functional 600 bytes client-side router._
## Highlighs
- **production:** ready for and used in
- **composability:** grouping multiple resources and multiple routers
- **flexibility:** overriding controller and request methods, plus custom prefixes
- **compatibility:** accepts both old and modern middlewares without deprecation messages
- **powerful:** multiple routers on same [koa][] app - even can combine multiple routers
- **light:** not poluting your router instance and app - see `.loadMethods`
- **backward compatible:** works on koa v1 - use `.legacyMiddleware`
- **maintainability:** very small, beautiful, maintainable and commented codebase
- **stability:** strict semantic versioning and very well documented, based on [koa-better-router][]
- **open:** love PRs for features, issues and recipes - [Contribute a recipe?](#contributing-recipes) See the [recipes](https://github.com/tunnckoCore/koa-better-router/tree/master/recipes) of [koa-better-router][]
## Table of Contents
<!-- toc -->
**ProTip:** Checkout [koa-better-router API](https://github.com/tunnckoCore/koa-better-router#api) too to know what more methods comes with this.
## Quickstart
> This router uses [koa-better-router][], so you should review its API documentation to get more info how the things are working and what more methods are exposed.
### Controller methods mapping
> In addition this router allows you to override the controller methods which will be used in certain route path.
**Defaults**
| Request method | Route path | Controller method |
| --- | --- | --- |
| GET | `/users` | `index` |
| GET | `/users/new ` | `new` |
| POST | `/users` | `create` |
| GET | `/users/:user` | `show` |
| GET | `/users/:user/edit` | `edit` |
| PUT | `/users/:user` | `update` |
| DELETE | `/users/:user` | `remove` |
**Example**
```js
let Router = require('koa-rest-router')
let router = Router()
router.resource('users', {
// GET /users
index: (ctx, next) => {},
// GET /users/new
new: (ctx, next) => {},
// POST /users
create: (ctx, next) => {},
// GET /users/:user
show: (ctx, next) => {},
// GET /users/:user/edit
edit: (ctx, next) => {},
// PUT /users/:user
update: (ctx, next) => {},
// DELETE /users/:user
remove: (ctx, next) => {}
})
let users = router.getResource('users')
console.log(users.length) // => 7
console.log(users) // => Array Route Objects
console.log(router.routes.length) // => 7
console.log(router.resources.length) // => 1
```
**Note:** Multiple middlewares can be passed on each. Also combining old and modern koa middlewares, so both generator functions and normal functions.
### Overriding controller methods
> You easily can override the defaults by passing `options.map` object with key/value pairs where the key represents the original, and value is a string containing the wanted override.
**Example**
```js
let router = require('koa-rest-router')()
let options = {
map: {
index: 'foo',
new: 'bar',
create: 'baz',
show: 'qux',
}
}
router.resource('users', {
// GET /users
foo: (ctx, next) => {},
// GET /users/new
bar: (ctx, next) => {},
// POST /users
baz: (ctx, next) => {},
// GET /users/:user
qux: (ctx, next) => {},
// ... etc
}, options)
```
### Overriding request methods
> In some cases in guides the REST routes uses different request methods and that field is not clear enough. So every sane router should allow overriding such things, so we do it. By default for updating is used `PUT`, for deleting/removing is `DELETE`. You can override this methods to use `POST` instead, so ...
**Example**
```js
let router = require('koa-rest-router')()
let options = {
methods: {
put: 'POST'
}
}
router.resource('cats', {
// POST /cats/:cat
update: (ctx, next) => {}
}, options)
```
And you can combine both overriding variants, of course
**Example**
```js
let router = require('koa-rest-router')()
let options = {
methods: {
put: 'POST'
},
map: {
update: 'foobar'
}
}
router.resource('cats', {
// POST /cats/:cat
foobar: (ctx, next) => {}
}, options)
```
## Install
> Install with [npm](https://www.npmjs.com/)
```sh
$ npm i koa-rest-router --save
```
## Usage
> For more use-cases see the [tests](./test.js)
```js
let router = require('koa-rest-router')()
// or
let Router = require('koa-rest-router')
let apiRouter = Router({ prefix: '/api/v1' })
```
## API
{%= apidocs('index.js') %}
{% if (verb.related && verb.related.list && verb.related.list.length) { %}
## Related
{%= related(verb.related.list, {words: 11}) %}
{% } %}
## Contributing
Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](https://github.com/{%= repository %}/issues/new).
Please read the [contributing guidelines](CONTRIBUTING.md) for advice on opening issues, pull requests, and coding standards.
If you need some help and can spent some cash, feel free to [contact me at CodeMentor.io](https://www.codementor.io/tunnckocore?utm_source=github&utm_medium=button&utm_term=tunnckocore&utm_campaign=github) too.
**In short:** If you want to contribute to that project, please follow these things
1. Please DO NOT edit [README.md](README.md), [CHANGELOG.md](CHANGELOG.md) and [.verb.md](.verb.md) files. See ["Building docs"](#building-docs) section.
2. Ensure anything is okey by installing the dependencies and run the tests. See ["Running tests"](#running-tests) section.
3. Always use `npm run commit` to commit changes instead of `git commit`, because it is interactive and user-friendly. It uses [commitizen][] behind the scenes, which follows Conventional Changelog idealogy.
4. Do NOT bump the version in package.json. For that we use `npm run release`, which is [standard-version][] and follows Conventional Changelog idealogy.
Thanks a lot! :)
### Contributing Recipes
Recipes are just different use cases, written in form of README in human language. Showing some "Pro Tips" and tricks, answering common questions and so on. They look like [tests](./test.js), but in more readable and understandable way for humans - mostly for beginners that not reads or understand enough the README or API and tests.
- They are in form of folders in the root [`recipes/`](./recipes) folder: for example `recipes/[short-meaningful-recipe-name]/`.
- In recipe folder should exist `README.md` file
- In recipe folder there may have actual js files, too. And should be working.
- The examples from the recipe README.md should also exist as separate `.js` files.
- Examples in recipe folder also should be working and actual.
It would be great if you follow these steps when you want to _fix, update or create_ a recipes. :sunglasses:
- Title for recipe idea should start with `[recipe]`: for example`[recipe] my awesome recipe`
- Title for new recipe (PR) should also start with `[recipe]`.
- Titles of Pull Requests or Issues for fixing/updating some existing recipes should start with `[recipe-fix]`.
It will help a lot, thanks in advance! :yum:
## Building docs
Documentation and that readme is generated using [verb-generate-readme][], which is a [verb][] generator, so you need to install both of them and then run `verb` command like that
```
$ npm install verbose/verb#dev verb-generate-readme --global && verb
```
_Please don't edit the README directly. Any changes to the readme must be made in [.verb.md](.verb.md)._
## Running tests
Clone repository and run the following in that cloned directory
```
$ npm install && npm test
```
## Author
{%= includeEither('authors', 'author') %}
+ [codementor/tunnckoCore](https://codementor.io/tunnckoCore)
## License
{%= copyright({ start: 2016, linkify: true, prefix: 'Copyright', symbol: '©' }) %} {%= license %}
***
{%= include('footer') %}
_Project scaffolded using [charlike][] cli._
{%= reflinks(verb.reflinks) %}
[downloads-url]: https://www.npmjs.com/package/{%= name %}
[downloads-img]: https://img.shields.io/npm/dt/{%= name %}.svg
[codeclimate-url]: https://codeclimate.com/github/{%= repository %}
[codeclimate-img]: https://img.shields.io/codeclimate/github/{%= repository %}.svg
[travis-url]: https://travis-ci.org/{%= repository %}
[travis-img]: https://img.shields.io/travis/{%= repository %}/master.svg?label=linux
[appveyor-url]: https://ci.appveyor.com/project/tunnckoCore/{%= name %}
[appveyor-img]: https://img.shields.io/appveyor/ci/tunnckoCore/{%= name %}/master.svg?label=windows
[coverage-url]: https://codecov.io/gh/{%= repository %}
[coverage-img]: https://img.shields.io/codecov/c/github/{%= repository %}/master.svg
[david-url]: https://david-dm.org/{%= repository %}
[david-img]: https://img.shields.io/david/{%= repository %}.svg
[standard-url]: https://github.com/feross/standard
[standard-img]: https://img.shields.io/badge/code%20style-standard-brightgreen.svg