Skip to content

Latest commit

 

History

History
272 lines (196 loc) · 9.1 KB

.verb.md

File metadata and controls

272 lines (196 loc) · 9.1 KB

{%= name %} {%= badge('npm') %} {%= badge('downloads') %} [![npm total downloads][downloads-img]][downloads-url]

{%= description %}

[![codeclimate][codeclimate-img]][codeclimate-url] codestyle [![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? See the recipes of [koa-better-router][]

Table of Contents

ProTip: Checkout 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

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

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

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

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

$ npm i koa-rest-router --save

Usage

For more use-cases see the tests

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 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 too.

In short: If you want to contribute to that project, please follow these things

  1. Please DO NOT edit README.md, CHANGELOG.md and .verb.md files. See "Building docs" section.
  2. Ensure anything is okey by installing the dependencies and run the tests. See "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, 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/ 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. 😎

  • 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! 😋

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.

Running tests

Clone repository and run the following in that cloned directory

$ npm install && npm test

Author

{%= includeEither('authors', 'author') %}

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