switch to vuepress

7 files changed, 516 insertions, 0 deletions

diff --git a/node_modules/koa-convert/.npmignore b/node_modules/koa-convert/.npmignore
new file mode 100644
index 00000000..3c3629e6
--- /dev/null
+++ b/node_modules/koa-convert/.npmignore
@@ -0,0 +1 @@
+node_modules
diff --git a/node_modules/koa-convert/.travis.yml b/node_modules/koa-convert/.travis.yml
new file mode 100644
index 00000000..82b24eeb
--- /dev/null
+++ b/node_modules/koa-convert/.travis.yml
@@ -0,0 +1,5 @@
+language: node_js
+node_js:
+  - "4"
+  - "5"
+script: "npm run test"
diff --git a/node_modules/koa-convert/LICENSE b/node_modules/koa-convert/LICENSE
new file mode 100644
index 00000000..03d4071e
--- /dev/null
+++ b/node_modules/koa-convert/LICENSE
@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 yunsong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
diff --git a/node_modules/koa-convert/README.md b/node_modules/koa-convert/README.md
new file mode 100644
index 00000000..79cb65d4
--- /dev/null
+++ b/node_modules/koa-convert/README.md
@@ -0,0 +1,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
diff --git a/node_modules/koa-convert/index.js b/node_modules/koa-convert/index.js
new file mode 100644
index 00000000..5fff6b5c
--- /dev/null
+++ b/node_modules/koa-convert/index.js
@@ -0,0 +1,60 @@
+'use strict'
+
+const co = require('co')
+const compose = require('koa-compose')
+
+module.exports = convert
+
+function convert (mw) {
+  if (typeof mw !== 'function') {
+    throw new TypeError('middleware must be a function')
+  }
+  if (mw.constructor.name !== 'GeneratorFunction') {
+    // assume it's Promise-based middleware
+    return mw
+  }
+  const converted = function (ctx, next) {
+    return co.call(ctx, mw.call(ctx, createGenerator(next)))
+  }
+  converted._name = mw._name || mw.name
+  return converted
+}
+
+function * createGenerator (next) {
+  return yield next()
+}
+
+// convert.compose(mw, mw, mw)
+// convert.compose([mw, mw, mw])
+convert.compose = function (arr) {
+  if (!Array.isArray(arr)) {
+    arr = Array.from(arguments)
+  }
+  return compose(arr.map(convert))
+}
+
+convert.back = function (mw) {
+  if (typeof mw !== 'function') {
+    throw new TypeError('middleware must be a function')
+  }
+  if (mw.constructor.name === 'GeneratorFunction') {
+    // assume it's generator middleware
+    return mw
+  }
+  const converted = function * (next) {
+    let ctx = this
+    let called = false
+    // no need try...catch here, it's ok even `mw()` throw exception
+    yield Promise.resolve(mw(ctx, function () {
+      if (called) {
+        // guard against multiple next() calls
+        // https://github.com/koajs/compose/blob/4e3e96baf58b817d71bd44a8c0d78bb42623aa95/index.js#L36
+        return Promise.reject(new Error('next() called multiple times'))
+      }
+      called = true
+      return co.call(ctx, next)
+    }))
+  }
+  converted._name = mw._name || mw.name
+  return converted
+}
diff --git a/node_modules/koa-convert/package.json b/node_modules/koa-convert/package.json
new file mode 100644
index 00000000..d741ce56
--- /dev/null
+++ b/node_modules/koa-convert/package.json
@@ -0,0 +1,38 @@
+{
+  "name": "koa-convert",
+  "version": "1.2.0",
+  "keywords": [
+    "koa",
+    "middleware",
+    "convert"
+  ],
+  "description": "convert koa legacy generator-based middleware to promise-based middleware",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gyson/koa-convert.git"
+  },
+  "main": "index.js",
+  "scripts": {
+    "test": "standard && mocha test.js"
+  },
+  "author": "gyson <eilian.yunsong@gmail.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/gyson/koa-convert/issues"
+  },
+  "homepage": "https://github.com/gyson/koa-convert#readme",
+  "dependencies": {
+    "co": "^4.6.0",
+    "koa-compose": "^3.0.0"
+  },
+  "devDependencies": {
+    "koa": "^2.0.0-alpha.2",
+    "koa-v1": "^1.0.0",
+    "mocha": "^2.3.3",
+    "standard": "^5.3.1",
+    "supertest": "^1.1.0"
+  },
+  "engines": {
+    "node": ">= 4"
+  }
+}
diff --git a/node_modules/koa-convert/test.js b/node_modules/koa-convert/test.js
new file mode 100644
index 00000000..9c1f11c0
--- /dev/null
+++ b/node_modules/koa-convert/test.js
@@ -0,0 +1,254 @@
+/* global describe, it */
+
+'use strict'
+
+const co = require('co')
+const Koa = require('koa')
+const KoaV1 = require('koa-v1')
+const assert = require('assert')
+const convert = require('./index')
+const request = require('supertest')
+
+describe('convert()', () => {
+  it('should work', () => {
+    let call = []
+    let ctx = {}
+    let mw = convert(function * (next) {
+      assert.ok(ctx === this)
+      call.push(1)
+    })
+
+    return mw(ctx, function () {
+      call.push(2)
+    }).then(function () {
+      assert.deepEqual(call, [1])
+    })
+  })
+
+  it('should inherit the original middleware name', () => {
+    let mw = convert(function * testing (next) {})
+    assert.strictEqual(mw._name, 'testing')
+  })
+
+  it('should work with `yield next`', () => {
+    let call = []
+    let ctx = {}
+    let mw = convert(function * (next) {
+      assert.ok(ctx === this)
+      call.push(1)
+      yield next
+      call.push(3)
+    })
+
+    return mw(ctx, function () {
+      call.push(2)
+      return Promise.resolve()
+    }).then(function () {
+      assert.deepEqual(call, [1, 2, 3])
+    })
+  })
+
+  it('should work with `yield* next`', () => {
+    let call = []
+    let ctx = {}
+    let mw = convert(function * (next) {
+      assert.ok(ctx === this)
+      call.push(1)
+      yield* next
+      call.push(3)
+    })
+
+    return mw(ctx, function () {
+      call.push(2)
+      return Promise.resolve()
+    }).then(function () {
+      assert.deepEqual(call, [1, 2, 3])
+    })
+  })
+})
+
+describe('convert.compose()', () => {
+  it('should work', () => {
+    let call = []
+    let context = {}
+    let _context
+    let mw = convert.compose([
+      function * name (next) {
+        call.push(1)
+        yield next
+        call.push(11)
+      },
+      (ctx, next) => {
+        call.push(2)
+        return next().then(() => {
+          call.push(10)
+        })
+      },
+      function * (next) {
+        call.push(3)
+        yield* next
+        call.push(9)
+      },
+      co.wrap(function * (ctx, next) {
+        call.push(4)
+        yield next()
+        call.push(8)
+      }),
+      function * (next) {
+        try {
+          call.push(5)
+          yield next
+        } catch (e) {
+          call.push(7)
+        }
+      },
+      (ctx, next) => {
+        _context = ctx
+        call.push(6)
+        throw new Error()
+      }
+    ])
+
+    return mw(context).then(() => {
+      assert.equal(context, _context)
+      assert.deepEqual(call, [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11])
+    })
+  })
+
+  it('should work too', () => {
+    let call = []
+    let context = {}
+    let _context
+    let mw = convert.compose(
+      (ctx, next) => {
+        call.push(1)
+        return next().catch(() => {
+          call.push(4)
+        })
+      },
+      function * (next) {
+        call.push(2)
+        yield next
+        call.push(-1) // should not call this
+      },
+      function * (next) {
+        call.push(3)
+        yield* next
+        call.push(-1) // should not call this
+      },
+      (ctx, next) => {
+        _context = ctx
+        return Promise.reject(new Error())
+      }
+    )
+
+    return mw(context).then(() => {
+      assert.equal(context, _context)
+      assert.deepEqual(call, [1, 2, 3, 4])
+    })
+  })
+})
+
+describe('convert.back()', () => {
+  it('should work with koa 1', done => {
+    let app = new KoaV1()
+
+    app.use(function * (next) {
+      this.body = [1]
+      yield next
+      this.body.push(6)
+    })
+
+    app.use(convert.back((ctx, next) => {
+      ctx.body.push(2)
+      return next().then(() => {
+        ctx.body.push(5)
+      })
+    }))
+
+    app.use(convert.back(co.wrap(function * (ctx, next) {
+      ctx.body.push(3)
+      yield next()
+      ctx.body.push(4)
+    })))
+
+    request(app.callback())
+      .get('/')
+      .expect(200, [1, 2, 3, 4, 5, 6])
+      .end(done)
+  })
+
+  it('should guard multiple calls', done => {
+    let app = new KoaV1()
+
+    app.use(function * (next) {
+      try {
+        this.body = [1]
+        yield next
+      } catch (e) {
+        this.body.push(e.message)
+      }
+    })
+
+    app.use(convert.back(co.wrap(function * (ctx, next) {
+      ctx.body.push(2)
+      yield next()
+      yield next() // this should throw new Error('next() called multiple times')
+    })))
+
+    request(app.callback())
+      .get('/')
+      .expect(200, [1, 2, 'next() called multiple times'])
+      .end(done)
+  })
+
+  it('should inherit the original middleware name', () => {
+    let mw = convert.back(function testing (ctx, next) {})
+    assert.strictEqual(mw._name, 'testing')
+  })
+})
+
+describe('migration snippet', () => {
+  let app = new Koa()
+
+  // snippet
+  const _use = app.use
+  app.use = x => _use.call(app, convert(x))
+  // end
+
+  app.use((ctx, next) => {
+    ctx.body = [1]
+    return next().then(() => {
+      ctx.body.push(9)
+    })
+  })
+
+  app.use(function * (next) {
+    this.body.push(2)
+    yield next
+    this.body.push(8)
+  })
+
+  app.use(function * (next) {
+    this.body.push(3)
+    yield* next
+    this.body.push(7)
+  })
+
+  app.use(co.wrap(function * (ctx, next) {
+    ctx.body.push(4)
+    yield next()
+    ctx.body.push(6)
+  }))
+
+  app.use(ctx => {
+    ctx.body.push(5)
+  })
+
+  it('should work', done => {
+    request(app.callback())
+      .get('/')
+      .expect(200, [1, 2, 3, 4, 5, 6, 7, 8, 9])
+      .end(done)
+  })
+})