333

schangxiang@126.com

2025-09-19 18966e02fb573c7e2bb0c6426ed792b38b910940

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
 
# koa-convert
 
[![npm version](https://img.shields.io/npm/v/koa-convert.svg)](https://npmjs.org/package/koa-convert)
[![build status](https://travis-ci.org/gyson/koa-convert.svg)](https://travis-ci.org/gyson/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 0.x or 1.x ).
 
## Note
 
It should be able to convert any legacy generator middleware to modern promise middleware ( or convert it back ).
 
Please let me know ( send a issue ) if you fail to do so.
 
## Installation
 
```
$ npm install 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