koa 2.14.0 → 3.0.0-alpha.0

package/Readme.md

@@ -2,7 +2,7 @@
 
   [![gitter][gitter-image]][gitter-url]
   [![NPM version][npm-image]][npm-url]
-  [![build status][travis-image]][travis-url]
+  [![build status][github-action-image]][github-action-url]
   [![Test coverage][coveralls-image]][coveralls-url]
   [![OpenCollective Backers][backers-image]](#backers)
   [![OpenCollective Sponsors][sponsors-image]](#sponsors)
@@ -17,7 +17,7 @@
 
 ## Installation
 
-Koa requires __node v7.6.0__ or higher for ES2015 and async function support.
+Koa requires __node v12.17.0__ or higher for ES2015 and async function support.
 
 ```
 $ npm install koa
@@ -40,9 +40,7 @@ app.listen(3000);
 ## Getting started
 
  - [Kick-Off-Koa](https://github.com/koajs/kick-off-koa) - An intro to Koa via a set of self-guided workshops.
- - [Workshop](https://github.com/koajs/workshop) - A workshop to learn the basics of Koa, Express' spiritual successor.
- - [Introduction Screencast](https://knowthen.com/episode-3-koajs-quickstart-guide/) - An introduction to installing and getting started with Koa
-
+ - [Guide](docs/guide.md) - Go straight to the docs.
 
 ## Middleware
 
@@ -181,6 +179,7 @@ See [AUTHORS](AUTHORS).
 
 ## Community
 
+ - [KoaJS Slack Group](https://join.slack.com/t/koa-js/shared_invite/zt-5pjgthmb-1JeKDbByqqcARtlPbtf~vQ)
  - [Badgeboard](https://koajs.github.io/badgeboard) and list of official modules
  - [Examples](https://github.com/koajs/examples)
  - [Middleware](https://github.com/koajs/koa/wiki) list
@@ -276,8 +275,8 @@ Become a sponsor and get your logo on our README on Github with a link to your s
 
 [npm-image]: https://img.shields.io/npm/v/koa.svg?style=flat-square
 [npm-url]: https://www.npmjs.com/package/koa
-[travis-image]: https://img.shields.io/travis/koajs/koa/master.svg?style=flat-square
-[travis-url]: https://travis-ci.org/koajs/koa
+[github-action-image]: https://github.com/koajs/koa/actions/workflows/node.js.yml/badge.svg
+[github-action-url]: https://github.com/koajs/koa/actions/workflows/node.js.yml
 [coveralls-image]: https://img.shields.io/codecov/c/github/koajs/koa.svg?style=flat-square
 [coveralls-url]: https://codecov.io/github/koajs/koa?branch=master
 [backers-image]: https://opencollective.com/koajs/backers/badge.svg?style=flat-square

package/lib/application.js

@@ -1,27 +1,38 @@
 
-'use strict';
+'use strict'
 
 /**
  * Module dependencies.
  */
 
-const isGeneratorFunction = require('is-generator-function');
-const debug = require('debug')('koa:application');
-const onFinished = require('on-finished');
-const assert = require('assert');
-const response = require('./response');
-const compose = require('koa-compose');
-const context = require('./context');
-const request = require('./request');
-const statuses = require('statuses');
-const Emitter = require('events');
-const util = require('util');
-const Stream = require('stream');
-const http = require('http');
-const only = require('only');
-const convert = require('koa-convert');
-const deprecate = require('depd')('koa');
-const { HttpError } = require('http-errors');
+const debug = require('debug')('koa:application')
+const assert = require('assert')
+const onFinished = require('on-finished')
+const response = require('./response')
+const compose = require('koa-compose')
+const context = require('./context')
+const request = require('./request')
+const statuses = require('statuses')
+const Emitter = require('events')
+const util = require('util')
+const Stream = require('stream')
+const http = require('http')
+const only = require('only')
+const { HttpError } = require('http-errors')
+
+/** @typedef {typeof import ('./context') & {
+ *  app: Application
+ *  req: import('http').IncomingMessage
+ *  res: import('http').ServerResponse
+ *  request: KoaRequest
+ *  response: KoaResponse
+ *  state: any
+ *  originalUrl: string
+ * }} Context */
+
+/** @typedef {typeof import('./request')} KoaRequest */
+
+/** @typedef {typeof import('./response')} KoaResponse */
 
 /**
  * Expose `Application` class.
@@ -47,29 +58,30 @@ module.exports = class Application extends Emitter {
     *
     */
 
-  constructor(options) {
-    super();
-    options = options || {};
-    this.proxy = options.proxy || false;
-    this.subdomainOffset = options.subdomainOffset || 2;
-    this.proxyIpHeader = options.proxyIpHeader || 'X-Forwarded-For';
-    this.maxIpsCount = options.maxIpsCount || 0;
-    this.env = options.env || process.env.NODE_ENV || 'development';
-    if (options.keys) this.keys = options.keys;
-    this.middleware = [];
-    this.context = Object.create(context);
-    this.request = Object.create(request);
-    this.response = Object.create(response);
+  constructor (options) {
+    super()
+    options = options || {}
+    this.proxy = options.proxy || false
+    this.subdomainOffset = options.subdomainOffset || 2
+    this.proxyIpHeader = options.proxyIpHeader || 'X-Forwarded-For'
+    this.maxIpsCount = options.maxIpsCount || 0
+    this.env = options.env || process.env.NODE_ENV || 'development'
+    this.compose = options.compose || compose
+    if (options.keys) this.keys = options.keys
+    this.middleware = []
+    this.context = Object.create(context)
+    this.request = Object.create(request)
+    this.response = Object.create(response)
     // util.inspect.custom support for node 6+
     /* istanbul ignore else */
     if (util.inspect.custom) {
-      this[util.inspect.custom] = this.inspect;
+      this[util.inspect.custom] = this.inspect
     }
     if (options.asyncLocalStorage) {
-      const { AsyncLocalStorage } = require('async_hooks');
-      assert(AsyncLocalStorage, 'Requires node 12.17.0 or higher to enable asyncLocalStorage');
-      this.ctxStorage = new AsyncLocalStorage();
-      this.use(createAsyncCtxStorage(this));
+      const { AsyncLocalStorage } = require('async_hooks')
+      assert(AsyncLocalStorage, 'Requires node 12.17.0 or higher to enable asyncLocalStorage')
+      this.ctxStorage = new AsyncLocalStorage()
+      this.use(this.createAsyncCtxStorageMiddleware())
     }
   }
 
@@ -79,14 +91,14 @@ module.exports = class Application extends Emitter {
    *    http.createServer(app.callback()).listen(...)
    *
    * @param {Mixed} ...
-   * @return {Server}
+   * @return {import('http').Server}
    * @api public
    */
 
-  listen(...args) {
-    debug('listen');
-    const server = http.createServer(this.callback());
-    return server.listen(...args);
+  listen (...args) {
+    debug('listen')
+    const server = http.createServer(this.callback())
+    return server.listen(...args)
   }
 
   /**
@@ -97,12 +109,12 @@ module.exports = class Application extends Emitter {
    * @api public
    */
 
-  toJSON() {
+  toJSON () {
     return only(this, [
       'subdomainOffset',
       'proxy',
       'env'
-    ]);
+    ])
   }
 
   /**
@@ -112,8 +124,8 @@ module.exports = class Application extends Emitter {
    * @api public
    */
 
-  inspect() {
-    return this.toJSON();
+  inspect () {
+    return this.toJSON()
   }
 
   /**
@@ -121,22 +133,16 @@ module.exports = class Application extends Emitter {
    *
    * Old-style middleware will be converted.
    *
-   * @param {Function} fn
+   * @param {(context: Context) => Promise<any | void>} fn
    * @return {Application} self
    * @api public
    */
 
-  use(fn) {
-    if (typeof fn !== 'function') throw new TypeError('middleware must be a function!');
-    if (isGeneratorFunction(fn)) {
-      deprecate('Support for generators will be removed in v3. ' +
-                'See the documentation for examples of how to convert old middleware ' +
-                'https://github.com/koajs/koa/blob/master/docs/migration.md');
-      fn = convert(fn);
-    }
-    debug('use %s', fn._name || fn.name || '-');
-    this.middleware.push(fn);
-    return this;
+  use (fn) {
+    if (typeof fn !== 'function') throw new TypeError('middleware must be a function!')
+    debug('use %s', fn._name || fn.name || '-')
+    this.middleware.push(fn)
+    return this
   }
 
   /**
@@ -147,24 +153,24 @@ module.exports = class Application extends Emitter {
    * @api public
    */
 
-  callback() {
-    const fn = compose(this.middleware);
+  callback () {
+    const fn = this.compose(this.middleware)
 
-    if (!this.listenerCount('error')) this.on('error', this.onerror);
+    if (!this.listenerCount('error')) this.on('error', this.onerror)
 
     const handleRequest = (req, res) => {
-      const ctx = this.createContext(req, res);
-      return this.handleRequest(ctx, fn);
-    };
+      const ctx = this.createContext(req, res)
+      return this.handleRequest(ctx, fn)
+    }
 
-    return handleRequest;
+    return handleRequest
   }
 
   /**
-   * return currnect contenxt from async local storage
+   * return current context from async local storage
    */
-  get currentContext() {
-    if (this.ctxStorage) return this.ctxStorage.getStore();
+  get currentContext () {
+    if (this.ctxStorage) return this.ctxStorage.getStore()
   }
 
   /**
@@ -173,13 +179,13 @@ module.exports = class Application extends Emitter {
    * @api private
    */
 
-  handleRequest(ctx, fnMiddleware) {
-    const res = ctx.res;
-    res.statusCode = 404;
-    const onerror = err => ctx.onerror(err);
-    const handleResponse = () => respond(ctx);
-    onFinished(res, onerror);
-    return fnMiddleware(ctx).then(handleResponse).catch(onerror);
+  handleRequest (ctx, fnMiddleware) {
+    const res = ctx.res
+    res.statusCode = 404
+    const onerror = err => ctx.onerror(err)
+    const handleResponse = () => respond(ctx)
+    onFinished(res, onerror)
+    return fnMiddleware(ctx).then(handleResponse).catch(onerror)
   }
 
   /**
@@ -188,19 +194,22 @@ module.exports = class Application extends Emitter {
    * @api private
    */
 
-  createContext(req, res) {
-    const context = Object.create(this.context);
-    const request = context.request = Object.create(this.request);
-    const response = context.response = Object.create(this.response);
-    context.app = request.app = response.app = this;
-    context.req = request.req = response.req = req;
-    context.res = request.res = response.res = res;
-    request.ctx = response.ctx = context;
-    request.response = response;
-    response.request = request;
-    context.originalUrl = request.originalUrl = req.url;
-    context.state = {};
-    return context;
+  createContext (req, res) {
+    /** @type {Context} */
+    const context = Object.create(this.context)
+    /** @type {KoaRequest} */
+    const request = context.request = Object.create(this.request)
+    /** @type {KoaResponse} */
+    const response = context.response = Object.create(this.response)
+    context.app = request.app = response.app = this
+    context.req = request.req = response.req = req
+    context.res = request.res = response.res = res
+    request.ctx = response.ctx = context
+    request.response = response
+    response.request = request
+    context.originalUrl = request.originalUrl = req.url
+    context.state = {}
+    return context
   }
 
   /**
@@ -210,20 +219,20 @@ module.exports = class Application extends Emitter {
    * @api private
    */
 
-  onerror(err) {
+  onerror (err) {
     // When dealing with cross-globals a normal `instanceof` check doesn't work properly.
     // See https://github.com/koajs/koa/issues/1466
     // We can probably remove it once jest fixes https://github.com/facebook/jest/issues/2549.
     const isNativeError =
       Object.prototype.toString.call(err) === '[object Error]' ||
-      err instanceof Error;
-    if (!isNativeError) throw new TypeError(util.format('non-error thrown: %j', err));
+      err instanceof Error
+    if (!isNativeError) throw new TypeError(util.format('non-error thrown: %j', err))
 
-    if (404 === err.status || err.expose) return;
-    if (this.silent) return;
+    if (err.status === 404 || err.expose) return
+    if (this.silent) return
 
-    const msg = err.stack || err.toString();
-    console.error(`\n${msg.replace(/^/gm, '  ')}\n`);
+    const msg = err.stack || err.toString()
+    console.error(`\n${msg.replace(/^/gm, '  ')}\n`)
   }
 
   /**
@@ -231,78 +240,80 @@ module.exports = class Application extends Emitter {
    * @see https://github.com/koajs/koa/issues/1513
    */
 
-  static get default() {
-    return Application;
+  static get default () {
+    return Application
+  }
+
+  createAsyncCtxStorageMiddleware () {
+    const app = this
+    return async function asyncCtxStorage (ctx, next) {
+      await app.ctxStorage.run(ctx, async () => {
+        return await next()
+      })
+    }
   }
-};
-
-function createAsyncCtxStorage(app) {
-  return async function asyncCtxStorage(ctx, next) {
-    await app.ctxStorage.run(ctx, async() => {
-      return await next();
-    });
-  };
 }
 
 /**
  * Response helper.
  */
 
-function respond(ctx) {
+function respond (ctx) {
   // allow bypassing koa
-  if (false === ctx.respond) return;
+  if (ctx.respond === false) return
 
-  if (!ctx.writable) return;
+  if (!ctx.writable) return
 
-  const res = ctx.res;
-  let body = ctx.body;
-  const code = ctx.status;
+  const res = ctx.res
+  let body = ctx.body
+  const code = ctx.status
 
   // ignore body
   if (statuses.empty[code]) {
     // strip headers
-    ctx.body = null;
-    return res.end();
+    ctx.body = null
+    return res.end()
   }
 
-  if ('HEAD' === ctx.method) {
+  if (ctx.method === 'HEAD') {
     if (!res.headersSent && !ctx.response.has('Content-Length')) {
-      const { length } = ctx.response;
-      if (Number.isInteger(length)) ctx.length = length;
+      const { length } = ctx.response
+      if (Number.isInteger(length)) ctx.length = length
     }
-    return res.end();
+    return res.end()
   }
 
   // status body
-  if (null == body) {
+  if (body == null) {
     if (ctx.response._explicitNullBody) {
-      ctx.response.remove('Content-Type');
-      ctx.response.remove('Transfer-Encoding');
-      return res.end();
+      ctx.response.remove('Content-Type')
+      ctx.response.remove('Transfer-Encoding')
+      ctx.length = 0
+      return res.end()
     }
     if (ctx.req.httpVersionMajor >= 2) {
-      body = String(code);
+      body = String(code)
     } else {
-      body = ctx.message || String(code);
+      body = ctx.message || String(code)
     }
     if (!res.headersSent) {
-      ctx.type = 'text';
-      ctx.length = Buffer.byteLength(body);
+      ctx.type = 'text'
+      ctx.length = Buffer.byteLength(body)
     }
-    return res.end(body);
+    return res.end(body)
   }
 
   // responses
-  if (Buffer.isBuffer(body)) return res.end(body);
-  if ('string' === typeof body) return res.end(body);
-  if (body instanceof Stream) return body.pipe(res);
+  if (Buffer.isBuffer(body)) return res.end(body)
+  if (typeof body === 'string') return res.end(body)
+  if (body instanceof Stream) return body.pipe(res)
 
   // body: json
-  body = JSON.stringify(body);
+  body = JSON.stringify(body)
   if (!res.headersSent) {
-    ctx.length = Buffer.byteLength(body);
+    ctx.length = Buffer.byteLength(body)
   }
-  res.end(body);
+  res.end(body)
 }
 
 /**
@@ -310,4 +321,4 @@ function respond(ctx) {
  * have a direct dependency upon `http-errors`
  */
 
-module.exports.HttpError = HttpError;
+module.exports.HttpError = HttpError

package/lib/context.js

@@ -1,18 +1,18 @@
 
-'use strict';
+'use strict'
 
 /**
  * Module dependencies.
  */
 
-const util = require('util');
-const createError = require('http-errors');
-const httpAssert = require('http-assert');
-const delegate = require('delegates');
-const statuses = require('statuses');
-const Cookies = require('cookies');
+const util = require('util')
+const createError = require('http-errors')
+const httpAssert = require('http-assert')
+const delegate = require('delegates')
+const statuses = require('statuses')
+const Cookies = require('cookies')
 
-const COOKIES = Symbol('context#cookies');
+const COOKIES = Symbol('context#cookies')
 
 /**
  * Context prototype.
@@ -28,9 +28,9 @@ const proto = module.exports = {
    * @api public
    */
 
-  inspect() {
-    if (this === proto) return this;
-    return this.toJSON();
+  inspect () {
+    if (this === proto) return this
+    return this.toJSON()
   },
 
   /**
@@ -45,7 +45,7 @@ const proto = module.exports = {
    * @api public
    */
 
-  toJSON() {
+  toJSON () {
     return {
       request: this.request.toJSON(),
       response: this.response.toJSON(),
@@ -54,7 +54,7 @@ const proto = module.exports = {
       req: '<original node req>',
       res: '<original node res>',
       socket: '<original node socket>'
-    };
+    }
   },
 
   /**
@@ -93,8 +93,8 @@ const proto = module.exports = {
    * @api public
    */
 
-  throw(...args) {
-    throw createError(...args);
+  throw (...args) {
+    throw createError(...args)
   },
 
   /**
@@ -104,81 +104,81 @@ const proto = module.exports = {
    * @api private
    */
 
-  onerror(err) {
+  onerror (err) {
     // don't do anything if there is no error.
     // this allows you to pass `this.onerror`
     // to node-style callbacks.
-    if (null == err) return;
+    if (err == null) return
 
     // When dealing with cross-globals a normal `instanceof` check doesn't work properly.
     // See https://github.com/koajs/koa/issues/1466
     // We can probably remove it once jest fixes https://github.com/facebook/jest/issues/2549.
     const isNativeError =
       Object.prototype.toString.call(err) === '[object Error]' ||
-      err instanceof Error;
-    if (!isNativeError) err = new Error(util.format('non-error thrown: %j', err));
+      err instanceof Error
+    if (!isNativeError) err = new Error(util.format('non-error thrown: %j', err))
 
-    let headerSent = false;
+    let headerSent = false
     if (this.headerSent || !this.writable) {
-      headerSent = err.headerSent = true;
+      headerSent = err.headerSent = true
     }
 
     // delegate
-    this.app.emit('error', err, this);
+    this.app.emit('error', err, this)
 
     // nothing we can do here other
     // than delegate to the app-level
     // handler and log.
     if (headerSent) {
-      return;
+      return
     }
 
-    const { res } = this;
+    const { res } = this
 
     // first unset all headers
     /* istanbul ignore else */
     if (typeof res.getHeaderNames === 'function') {
-      res.getHeaderNames().forEach(name => res.removeHeader(name));
+      res.getHeaderNames().forEach(name => res.removeHeader(name))
     } else {
-      res._headers = {}; // Node < 7.7
+      res._headers = {} // Node < 7.7
     }
 
     // then set those specified
-    this.set(err.headers);
+    this.set(err.headers)
 
     // force text/plain
-    this.type = 'text';
+    this.type = 'text'
 
-    let statusCode = err.status || err.statusCode;
+    let statusCode = err.status || err.statusCode
 
     // ENOENT support
-    if ('ENOENT' === err.code) statusCode = 404;
+    if (err.code === 'ENOENT') statusCode = 404
 
     // default to 500
-    if ('number' !== typeof statusCode || !statuses[statusCode]) statusCode = 500;
+    if (typeof statusCode !== 'number' || !statuses[statusCode]) statusCode = 500
 
     // respond
-    const code = statuses[statusCode];
-    const msg = err.expose ? err.message : code;
-    this.status = err.status = statusCode;
-    this.length = Buffer.byteLength(msg);
-    res.end(msg);
+    const code = statuses[statusCode]
+    const msg = err.expose ? err.message : code
+    this.status = err.status = statusCode
+    this.length = Buffer.byteLength(msg)
+    res.end(msg)
   },
 
-  get cookies() {
+  get cookies () {
     if (!this[COOKIES]) {
       this[COOKIES] = new Cookies(this.req, this.res, {
         keys: this.app.keys,
         secure: this.request.secure
-      });
+      })
     }
-    return this[COOKIES];
+    return this[COOKIES]
   },
 
-  set cookies(_cookies) {
-    this[COOKIES] = _cookies;
+  set cookies (_cookies) {
+    this[COOKIES] = _cookies
   }
-};
+}
 
 /**
  * Custom inspection implementation for newer Node.js versions.
@@ -189,7 +189,7 @@ const proto = module.exports = {
 
 /* istanbul ignore else */
 if (util.inspect.custom) {
-  module.exports[util.inspect.custom] = module.exports.inspect;
+  module.exports[util.inspect.custom] = module.exports.inspect
 }
 
 /**
@@ -213,7 +213,7 @@ delegate(proto, 'response')
   .access('lastModified')
   .access('etag')
   .getter('headerSent')
-  .getter('writable');
+  .getter('writable')
 
 /**
  * Request delegation.
@@ -248,4 +248,4 @@ delegate(proto, 'request')
   .getter('stale')
   .getter('fresh')
   .getter('ips')
-  .getter('ip');
+  .getter('ip')