Skip to content
Convert koa generator-based middleware to promise-based middleware
JavaScript
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.gitignore add implementation, readme and test Oct 11, 2015
.travis.yml add node v5 in .travis.yml Nov 2, 2015
LICENSE Initial commit Oct 11, 2015
README.md update build status link Jan 19, 2016
index.js inherit original name for convert.back Nov 16, 2015
package.json 1.2.0 Nov 16, 2015
test.js inherit original name for convert.back Nov 16, 2015

README.md

koa-convert

npm version build status

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

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, which are koa 2.x ready now:

Installation

$ npm install koa-convert

Usage

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.

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.

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:

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.

modernMiddleware = convert(legacyMiddleware)

convert.compose()

Convert and compose multiple middleware (could mix legacy and modern ones) and return modern promise middleware.

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.

legacyMiddleware = convert.back(modernMiddleware)

License

MIT

You can’t perform that action at this time.