167 lines
4.5 KiB
Markdown
167 lines
4.5 KiB
Markdown
# koa-convert
|
|
|
|
[![Build Status][travis-img]][travis-url]
|
|
[![NPM version][npm-badge]][npm-url]
|
|
[![License][license-badge]][license-url]
|
|
![Code Size][code-size-badge]
|
|
|
|
<!-- [![Coverage Status][coverage-img]][coverage-url] -->
|
|
|
|
<!-- ***************** -->
|
|
|
|
[travis-img]: https://travis-ci.org/koajs/convert.svg?branch=master
|
|
[travis-url]: https://travis-ci.org/koajs/convert
|
|
|
|
<!--
|
|
WAIT FOR ACCESS
|
|
[coverage-img]: https://coveralls.io/repos/github/koajs/convert/badge.svg?branch=master
|
|
[coverage-url]: https://coveralls.io/github/koajs/convert?branch=master
|
|
-->
|
|
|
|
[npm-badge]: https://img.shields.io/npm/v/koa-better-request-id.svg?style=flat
|
|
[npm-url]: https://www.npmjs.com/package/koa-better-request-id
|
|
[license-badge]: https://img.shields.io/badge/license-MIT-green.svg?style=flat-square
|
|
[license-url]: https://github.com/koajs/koa-convert/blob/master/LICENSE
|
|
[code-size-badge]: https://img.shields.io/github/languages/code-size/koajs/koa-convert
|
|
|
|
<!-- ***************** -->
|
|
|
|
Convert Koa legacy (0.x & 1.x) generator middleware to modern promise middleware (2.x).
|
|
|
|
It could also convert modern promise middleware back to legacy generator middleware (useful to help modern middleware support Koa v0.x or v1.x).
|
|
|
|
## Note
|
|
|
|
Router middleware is special case here. Because it reimplements middleware composition internally, we cannot not simply convert it.
|
|
|
|
You may use following packages for [routing](https://github.com/koajs/koa/wiki#routing-and-mounting), which are koa 2.x ready now:
|
|
|
|
* [koa-route@3.0.0](https://github.com/koajs/route/tree/next)
|
|
* [koa-simple-router](https://github.com/gyson/koa-simple-router)
|
|
* [koa-router@next](https://github.com/alexmingoia/koa-router/tree/master)
|
|
* [koa-66](https://github.com/menems/koa-66)
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
# npm ..
|
|
$ npm i koa-convert
|
|
# yarn ..
|
|
$ yarn add koa-convert
|
|
```
|
|
|
|
## Usage
|
|
|
|
```js
|
|
const Koa = require('koa') // koa v2.x
|
|
const convert = require('koa-convert')
|
|
const app = new Koa()
|
|
|
|
app.use(modernMiddleware)
|
|
|
|
app.use(convert(legacyMiddleware))
|
|
|
|
app.use(convert.compose(legacyMiddleware, modernMiddleware))
|
|
|
|
function * legacyMiddleware (next) {
|
|
// before
|
|
yield next
|
|
// after
|
|
}
|
|
|
|
function modernMiddleware (ctx, next) {
|
|
// before
|
|
return next().then(() => {
|
|
// after
|
|
})
|
|
}
|
|
```
|
|
|
|
## Distinguish legacy and modern middleware
|
|
|
|
In koa 0.x and 1.x (without experimental flag), `app.use` has an assertion that all (legacy) middleware must be generator function and it's tested with `fn.constructor.name == 'GeneratorFunction'` at [here](https://github.com/koajs/koa/blob/7fe29d92f1e826d9ce36029e1b9263b94cba8a7c/lib/application.js#L105).
|
|
|
|
Therefore, we can distinguish legacy and modern middleware with `fn.constructor.name == 'GeneratorFunction'`.
|
|
|
|
## Migration
|
|
|
|
`app.use(legacyMiddleware)` is everywhere in 0.x and 1.x and it would be painful to manually change all of them to `app.use(convert(legacyMiddleware))`.
|
|
|
|
You can use following snippet to make migration easier.
|
|
|
|
```js
|
|
const _use = app.use
|
|
app.use = x => _use.call(app, convert(x))
|
|
```
|
|
|
|
The above snippet will override `app.use` method and implicitly convert all legacy generator middleware to modern promise middleware.
|
|
|
|
Therefore, you can have both `app.use(modernMiddleware)` and `app.use(legacyMiddleware)` and your 0.x or 1.x should work without modification.
|
|
|
|
Complete example:
|
|
|
|
```js
|
|
const Koa = require('koa') // v2.x
|
|
const convert = require('koa-convert')
|
|
const app = new Koa()
|
|
|
|
// ---------- override app.use method ----------
|
|
|
|
const _use = app.use
|
|
app.use = x => _use.call(app, convert(x))
|
|
|
|
// ---------- end ----------
|
|
|
|
app.use(modernMiddleware)
|
|
|
|
// this will be converted to modern promise middleware implicitly
|
|
app.use(legacyMiddleware)
|
|
|
|
function * legacyMiddleware (next) {
|
|
// before
|
|
yield next
|
|
// after
|
|
}
|
|
|
|
function modernMiddleware (ctx, next) {
|
|
// before
|
|
return next().then(() => {
|
|
// after
|
|
})
|
|
}
|
|
```
|
|
|
|
## API
|
|
|
|
#### `convert()`
|
|
|
|
Convert legacy generator middleware to modern promise middleware.
|
|
|
|
```js
|
|
modernMiddleware = convert(legacyMiddleware)
|
|
```
|
|
|
|
#### `convert.compose()`
|
|
|
|
Convert and compose multiple middleware (could mix legacy and modern ones) and return modern promise middleware.
|
|
|
|
```js
|
|
composedModernMiddleware = convert.compose(legacyMiddleware, modernMiddleware)
|
|
// or
|
|
composedModernMiddleware = convert.compose([legacyMiddleware, modernMiddleware])
|
|
```
|
|
|
|
#### `convert.back()`
|
|
|
|
Convert modern promise middleware back to legacy generator middleware.
|
|
|
|
This is useful to help modern promise middleware support koa 0.x or 1.x.
|
|
|
|
```js
|
|
legacyMiddleware = convert.back(modernMiddleware)
|
|
```
|
|
|
|
## License
|
|
|
|
[MIT](LICENSE)
|