Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/koajs/convert
Convert koa generator-based middleware to promise-based middleware
https://github.com/koajs/convert
Last synced: about 1 month ago
JSON representation
Convert koa generator-based middleware to promise-based middleware
- Host: GitHub
- URL: https://github.com/koajs/convert
- Owner: koajs
- License: mit
- Created: 2015-10-11T00:26:08.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2020-09-10T18:43:48.000Z (about 4 years ago)
- Last Synced: 2024-04-14T00:34:24.547Z (7 months ago)
- Language: JavaScript
- Homepage:
- Size: 21.5 KB
- Stars: 253
- Watchers: 7
- Forks: 22
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-koa - convert - Convert koa generator-based middleware to promise-based middleware (Middleware)
README
# koa-convert
[![Build Status][travis-img]][travis-url]
[![NPM version][npm-badge]][npm-url]
[![License][license-badge]][license-url]
![Code Size][code-size-badge]
[travis-img]: https://travis-ci.org/koajs/convert.svg?branch=master
[travis-url]: https://travis-ci.org/koajs/convert
[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:
* [[email protected]](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)