@eggjs/koa 2.14.2 → 2.15.0

package/Readme.md

@@ -2,13 +2,13 @@
 
 @eggjs/koa is forked from [Koa v2.x](https://github.com/koajs/koa/tree/v2.x) for LTS and drop Node.js < 16.13.0 support.
 
-<img src="/docs/logo.png" alt="Koa middleware framework for nodejs"/>
+<img height="240px" src="/docs/logo.png" alt="Koa middleware framework for nodejs"/>
 
 [![NPM version](https://img.shields.io/npm/v/@eggjs/koa.svg?style=flat-square)](https://npmjs.org/package/@eggjs/koa)
 [![NPM quality](http://npm.packagequality.com/shield/@eggjs/koa.svg?style=flat-square)](http://packagequality.com/#?package=@eggjs/koa)
 [![NPM download](https://img.shields.io/npm/dm/@eggjs/koa.svg?style=flat-square)](https://npmjs.org/package/@eggjs/koa)
 [![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Feggjs%2Fkoa.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Feggjs%2Fkoa?ref=badge_shield)
-[![Continuous Integration](https://github.com/eggjs/koa/workflows/Continuous%20integration/badge.svg)](https://github.com/eggjs/koa/actions?query=branch%3Amaster)
+[![Node.js CI](https://github.com/eggjs/koa/actions/workflows/node.js.yml/badge.svg?branch=master)](https://github.com/eggjs/koa/actions/workflows/node.js.yml)
 [![Test coverage](https://img.shields.io/codecov/c/github/eggjs/koa.svg?style=flat-square)](https://codecov.io/gh/eggjs/koa)
 [![Known Vulnerabilities](https://snyk.io/test/npm/@eggjs/koa/badge.svg?style=flat-square)](https://snyk.io/test/npm/@eggjs/koa)
 
@@ -29,7 +29,7 @@ npm install @eggjs/koa
 
 ## Hello Koa
 
-```js
+```ts
 const Koa = require('@eggjs/koa');
 const app = new Koa();
 
@@ -56,9 +56,9 @@ Koa is a middleware framework that can take two different kinds of functions as
 
 Here is an example of logger middleware with each of the different functions:
 
-### ___async___ functions (node v7.6+)
+### ___async___ functions
 
-```js
+```ts
 app.use(async (ctx, next) => {
   const start = Date.now();
   await next();
@@ -69,7 +69,7 @@ app.use(async (ctx, next) => {
 
 ### Common function
 
-```js
+```ts
 // Middleware normally takes two parameters (ctx, next), ctx is the context for one request,
 // next is a function that is invoked to execute the downstream middleware. It returns a Promise with a then function for running code after completion.
 
@@ -82,15 +82,6 @@ app.use((ctx, next) => {
 });
 ```
 
-### Koa v1.x Middleware Signature
-
-The middleware signature changed between v1.x and v2.x.  The older signature is deprecated.
-
-__Old signature middleware support will be removed in v3__
-
-Please see the [Migration Guide](docs/migration.md) for more information on upgrading from v1.x and
-using v1.x middleware with v2.x.
-
 ## Context, Request and Response
 
 Each middleware receives a Koa `Context` object that encapsulates an incoming
@@ -110,7 +101,7 @@ from the node `http` module.
 
 Here is an example of checking that a requesting client supports xml.
 
-```js
+```ts
 app.use(async (ctx, next) => {
   ctx.assert(ctx.request.accepts('xml'), 406);
   // equivalent to:
@@ -132,7 +123,7 @@ accessed as the `res` property on the `Context`.
 
 Here is an example using Koa's `Response` object to stream a file as the response body.
 
-```js
+```ts
 app.use(async (ctx, next) => {
   await next();
   ctx.response.type = 'xml';
@@ -186,93 +177,10 @@ See [AUTHORS](AUTHORS).
 
 ## Community
 
-- [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
 - [Wiki](https://github.com/koajs/koa/wiki)
-- [Reddit Community](https://www.reddit.com/r/koajs)
-- [Mailing list](https://groups.google.com/forum/#!forum/koajs)
-- [中文文档 v1.x](https://github.com/guo-yu/koa-guide)
 - [中文文档 v2.x](https://github.com/demopark/koa-docs-Zh-CN)
-- __[#koajs]__ on freenode
-
-## Job Board
-
-Looking for a career upgrade?
-
-<a href="https://astro.netlify.com/automattic"><img src="https://astro.netlify.com/static/automattic.png"></a>
-<a href="https://astro.netlify.com/segment"><img src="https://astro.netlify.com/static/segment.png"></a>
-<a href="https://astro.netlify.com/auth0"><img src="https://astro.netlify.com/static/auth0.png"/></a>
-
-## Backers
-
-Support us with a monthly donation and help us continue our activities.
-
-<a href="https://opencollective.com/koajs/backer/0/website" target="_blank"><img src="https://opencollective.com/koajs/backer/0/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/backer/1/website" target="_blank"><img src="https://opencollective.com/koajs/backer/1/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/backer/2/website" target="_blank"><img src="https://opencollective.com/koajs/backer/2/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/backer/3/website" target="_blank"><img src="https://opencollective.com/koajs/backer/3/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/backer/4/website" target="_blank"><img src="https://opencollective.com/koajs/backer/4/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/backer/5/website" target="_blank"><img src="https://opencollective.com/koajs/backer/5/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/backer/6/website" target="_blank"><img src="https://opencollective.com/koajs/backer/6/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/backer/7/website" target="_blank"><img src="https://opencollective.com/koajs/backer/7/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/backer/8/website" target="_blank"><img src="https://opencollective.com/koajs/backer/8/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/backer/9/website" target="_blank"><img src="https://opencollective.com/koajs/backer/9/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/backer/10/website" target="_blank"><img src="https://opencollective.com/koajs/backer/10/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/backer/11/website" target="_blank"><img src="https://opencollective.com/koajs/backer/11/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/backer/12/website" target="_blank"><img src="https://opencollective.com/koajs/backer/12/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/backer/13/website" target="_blank"><img src="https://opencollective.com/koajs/backer/13/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/backer/14/website" target="_blank"><img src="https://opencollective.com/koajs/backer/14/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/backer/15/website" target="_blank"><img src="https://opencollective.com/koajs/backer/15/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/backer/16/website" target="_blank"><img src="https://opencollective.com/koajs/backer/16/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/backer/17/website" target="_blank"><img src="https://opencollective.com/koajs/backer/17/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/backer/18/website" target="_blank"><img src="https://opencollective.com/koajs/backer/18/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/backer/19/website" target="_blank"><img src="https://opencollective.com/koajs/backer/19/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/backer/20/website" target="_blank"><img src="https://opencollective.com/koajs/backer/20/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/backer/21/website" target="_blank"><img src="https://opencollective.com/koajs/backer/21/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/backer/22/website" target="_blank"><img src="https://opencollective.com/koajs/backer/22/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/backer/23/website" target="_blank"><img src="https://opencollective.com/koajs/backer/23/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/backer/24/website" target="_blank"><img src="https://opencollective.com/koajs/backer/24/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/backer/25/website" target="_blank"><img src="https://opencollective.com/koajs/backer/25/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/backer/26/website" target="_blank"><img src="https://opencollective.com/koajs/backer/26/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/backer/27/website" target="_blank"><img src="https://opencollective.com/koajs/backer/27/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/backer/28/website" target="_blank"><img src="https://opencollective.com/koajs/backer/28/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/backer/29/website" target="_blank"><img src="https://opencollective.com/koajs/backer/29/avatar.svg"></a>
-
-## Sponsors
-
-Become a sponsor and get your logo on our README on Github with a link to your site.
-
-<a href="https://opencollective.com/koajs/sponsor/0/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/0/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/sponsor/1/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/1/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/sponsor/2/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/2/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/sponsor/3/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/3/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/sponsor/4/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/4/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/sponsor/5/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/5/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/sponsor/6/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/6/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/sponsor/7/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/7/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/sponsor/8/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/8/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/sponsor/9/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/9/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/sponsor/10/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/10/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/sponsor/11/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/11/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/sponsor/12/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/12/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/sponsor/13/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/13/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/sponsor/14/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/14/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/sponsor/15/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/15/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/sponsor/16/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/16/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/sponsor/17/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/17/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/sponsor/18/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/18/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/sponsor/19/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/19/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/sponsor/20/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/20/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/sponsor/21/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/21/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/sponsor/22/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/22/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/sponsor/23/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/23/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/sponsor/24/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/24/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/sponsor/25/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/25/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/sponsor/26/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/26/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/sponsor/27/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/27/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/sponsor/28/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/28/avatar.svg"></a>
-<a href="https://opencollective.com/koajs/sponsor/29/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/29/avatar.svg"></a>
 
 # License
 

package/lib/application.d.ts

@@ -0,0 +1,110 @@
+/// <reference types="node" />
+/// <reference types="node" />
+/// <reference types="node" />
+/// <reference types="node" />
+import Emitter from 'node:events';
+import util from 'node:util';
+import http from 'node:http';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import Context from './context';
+import Request from './request';
+import Response from './response';
+import type { ContextDelegation } from './context';
+import type { CustomError, ProtoImplClass, AnyProto } from './types';
+export type Next = () => Promise<void>;
+export type MiddlewareFunc = (ctx: ContextDelegation, next: Next) => Promise<void> | void;
+export type { ContextDelegation as Context } from './context';
+export type { CustomError, ProtoImplClass } from './types';
+/**
+ * Expose `Application` class.
+ * Inherits from `Emitter.prototype`.
+ */
+export default class Application extends Emitter {
+    #private;
+    /**
+     * Make HttpError available to consumers of the library so that consumers don't
+     * have a direct dependency upon `http-errors`
+     */
+    static HttpError: any;
+    proxy: boolean;
+    subdomainOffset: number;
+    proxyIpHeader: string;
+    maxIpsCount: number;
+    env: string;
+    keys?: string[];
+    middleware: MiddlewareFunc[];
+    ctxStorage: AsyncLocalStorage<ContextDelegation>;
+    silent: boolean;
+    ContextClass: ProtoImplClass<Context>;
+    context: AnyProto;
+    RequestClass: ProtoImplClass<Request>;
+    request: AnyProto;
+    ResponseClass: ProtoImplClass<Response>;
+    response: AnyProto;
+    /**
+     * Initialize a new `Application`.
+      *
+      * @param {object} [options] Application options
+      * @param {string} [options.env='development'] Environment
+      * @param {string[]} [options.keys] Signed cookie keys
+      * @param {boolean} [options.proxy] Trust proxy headers
+      * @param {number} [options.subdomainOffset] Subdomain offset
+      * @param {string} [options.proxyIpHeader] Proxy IP header, defaults to X-Forwarded-For
+      * @param {number} [options.maxIpsCount] Max IPs read from proxy IP header, default to 0 (means infinity)
+      */
+    constructor(options?: {
+        proxy?: boolean;
+        subdomainOffset?: number;
+        proxyIpHeader?: string;
+        maxIpsCount?: number;
+        env?: string;
+        keys?: string[];
+    });
+    /**
+     * Shorthand for:
+     *
+     *    http.createServer(app.callback()).listen(...)
+     */
+    listen(...args: any[]): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
+    /**
+     * Return JSON representation.
+     * We only bother showing settings.
+     */
+    toJSON(): any;
+    /**
+     * Inspect implementation.
+     */
+    inspect(): any;
+    [util.inspect.custom](): any;
+    /**
+     * Use the given middleware `fn`.
+     *
+     * Old-style middleware will be converted.
+     */
+    use(fn: MiddlewareFunc): this;
+    /**
+     * Return a request handler callback
+     * for node's native http server.
+     */
+    callback(): (req: IncomingMessage, res: ServerResponse) => Promise<void | http.ServerResponse<http.IncomingMessage>>;
+    /**
+     * return currnect contenxt from async local storage
+     */
+    get currentContext(): ContextDelegation | undefined;
+    /**
+     * Initialize a new context.
+     * @private
+     */
+    protected createContext(req: IncomingMessage, res: ServerResponse): ContextDelegation;
+    /**
+     * Default error handler.
+     * @private
+     */
+    protected onerror(err: CustomError): void;
+    createAsyncCtxStorageMiddleware(): (ctx: ContextDelegation, next: Next) => Promise<void>;
+    /**
+     * Response helper.
+     */
+    protected _respond(ctx: ContextDelegation): http.ServerResponse<http.IncomingMessage> | undefined;
+}