Spaces:
Sleeping
Sleeping
File size: 4,590 Bytes
cdb0d23 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 |
# 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)
|