@goa/router


@goa/router is The Router For Creating Middleware For Goa Apps.

``sh
yarn add @goa/router
`

Table Of Contents

- Table Of Contents
- API
* Router
* RouterConfig
- Verbs
- Allowed Methods
* AllowedMethodsOptions
- Named Routes
- Multiple Middleware
- Nested Routes
- Router Prefixes
- URL Parameters
- Copyright & License

API

The package is available by importing its default class:

`js
import Router from '@goa/router'
`

The example below creates a really simple router that responds to the GET / and POST /users/:uid requests. Because of allowedMethods, it will also send a response to the OPTIONS request with the allow header.


__Router__: Router For Goa Apps.


Verbs

Routes are assigned to the router by calling HTTP method verbs on the instance:

`js
router
.get('/', (ctx, next) => {
ctx.body = 'Hello World!'
})
.post('/users', (ctx, next) => {
// ...
})
.put('/users/:id', (ctx, next) => {
// ...
})
.del('/users/:id', (ctx, next) => {
// ...
})
.all('/users/:id', (ctx, next) => {
// ...
})
`

Additionally, router.all() can be used to match against all methods. router.del() is an alias for router.delete().

When a route is matched, its path is available at ctx._matchedRoute and if named, the name is available at ctx._matchedRouteName.

Route paths will be translated to regular expressions using path-to-regexp.

Query strings will not be considered when matching requests.

Allowed Methods

The router can respond to the OPTIONS request with the allow header.

Example with Boom

`js
const app = new Goa()
const router = new Router()

app.use(router.routes())
app.use(router.allowedMethods({
throw: true,
notImplemented: () => new Boom.notImplemented(),
methodNotAllowed: () => new Boom.methodNotAllowed(),
}))
`

__AllowedMethodsOptions__: The options for the allowedMethods middleware generation.


| Name | Type | Description |
| ---------------- | --------------------- | -------------------------------------------------------------------------- |
| throw | boolean | Throw error instead of setting status and header. |
| notImplemented | () => !Error | Throw the returned value in place of the default NotImplemented error. |
| methodNotAllowed | () => !Error | Throw the returned value in place of the default MethodNotAllowed error. |

Named Routes

Routes can optionally have names. This allows generation of URLs and easy renaming of URLs during development.

`js
router.get('user', '/users/:id', (ctx, next) => {
// ...
})

router.url('user', 3)
// => "/users/3"
`

Multiple Middleware

Multiple middleware may be passed to the router.

`js
router.get(
'/users/:id',
async (ctx, next) => {
const user = await User.findOne(ctx.params.id)
ctx.user = user
await next()
},
ctx => {
console.log(ctx.user)
// => { id: 17, name: "Alex" }
}
)
`

Nested Routes

It's possible to create a _Router_ instance, and then pass another _Router_ instance to its .use call to nest the two.

Router Prefixes

Route paths can be prefixed at the router level.

`js
const router = new Router({
prefix: '/users',
})

router.get('/', (ctx) => {
// responds to "/users"
ctx.body = ctx.params
})
router.get('/:id', (ctx) => {
// responds to "/users/:id"
ctx.body = ctx.params
})

goa.use(router.routes())
`
`js
// Request /users
{}
// Request /users/123
{ id: '123' }
`

URL Parameters

Named route parameters are captured and added to ctx.params.

`js
const router = new Router()

router.get('/:category/:title', (ctx) => {
// the params are exposed to the context.
ctx.body = ctx.params
})

goa.use(router.routes())
`
`js
// Request /programming/how-to-node
{ category: 'programming', title: 'how-to-node' }
``

Copyright & License

GNU Affero General Public License v3.0

Original Work by Alexander C. Mingoia under MIT License found in COPYING.

There's also a fork in the Koa org.

© Idio 2019