egg 4.0.9 → 4.1.0-beta.2

package/README.md

@@ -1,8 +1,4 @@
-English | [简体中文](./README.zh-CN.md)
-
-<div style="text-align:center">
-	<img src="site/public/assets/egg-banner.png" />
-</div>
+# egg
 
 [![NPM version](https://img.shields.io/npm/v/egg.svg?style=flat-square)](https://npmjs.org/package/egg)
 [![NPM quality](http://npm.packagequality.com/shield/egg.svg?style=flat-square)](http://packagequality.com/#?package=egg)
@@ -10,8 +6,6 @@ English | [简体中文](./README.zh-CN.md)
 [![Node.js Version](https://img.shields.io/node/v/egg.svg?style=flat)](https://nodejs.org/en/download/)
 [![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Feggjs%2Fegg.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Feggjs%2Fegg?ref=badge_shield)
 
-[![Continuous Integration](https://github.com/eggjs/egg/actions/workflows/nodejs.yml/badge.svg)](https://github.com/eggjs/egg/actions?query=branch%3Amaster)
-[![Test coverage](https://img.shields.io/codecov/c/github/eggjs/egg.svg?style=flat-square)](https://codecov.io/gh/eggjs/egg)
 [![Known Vulnerabilities](https://snyk.io/test/npm/egg/badge.svg?style=flat-square)](https://snyk.io/test/npm/egg)
 [![Open Collective backers and sponsors](https://img.shields.io/opencollective/all/eggjs?style=flat-square)](https://opencollective.com/eggjs)
 
@@ -29,12 +23,12 @@ Follow the commands listed below.
 ```bash
 $ mkdir showcase && cd showcase
 $ npm init egg --type=simple # Optionally pnpm create egg --type=simple
-$ npm install
-$ npm run dev
+$ pnpm install
+$ pnpm run dev
 $ open http://localhost:7001
 ```
 
-> Node.js >= 14.20.0 required.
+> Node.js >= 20.19.0 required, [supports `require(esm)` by default](https://nodejs.org/en/blog/release/v20.19.0).
 
 ## Documentations
 
@@ -43,16 +37,6 @@ $ open http://localhost:7001
 - [Frameworks](https://github.com/search?q=topic%3Aegg-framework&type=Repositories)
 - [Examples](https://github.com/eggjs/examples)
 
-## Contributors
-
-[![contributors](https://contrib.rocks/image?repo=eggjs/egg&max=240&columns=26)](https://github.com/eggjs/egg/graphs/contributors)
-
-## How to Contribute
-
-Please let us know how can we help. Do check out [issues](https://github.com/eggjs/egg/issues) for bug reports or suggestions first.
-
-To become a contributor, please follow our [contributing guide](CONTRIBUTING.md).
-
 ## Sponsors and Backers
 
 [![sponsors](https://opencollective.com/eggjs/tiers/sponsors.svg?avatarHeight=48)](https://opencollective.com/eggjs#support)
@@ -61,5 +45,3 @@ To become a contributor, please follow our [contributing guide](CONTRIBUTING.md)
 ## License
 
 [MIT](LICENSE)
-
-[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Feggjs%2Fegg.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Feggjs%2Fegg?ref=badge_large)

package/dist/agent.d.ts

@@ -0,0 +1,8 @@
+import { BaseHookClass } from "./lib/core/base_hook_class.js";
+
+//#region src/agent.d.ts
+declare class EggAgentHook extends BaseHookClass {
+  configDidLoad(): void;
+}
+//#endregion
+export { EggAgentHook as default };

package/dist/agent.js

@@ -0,0 +1,11 @@
+import { BaseHookClass } from "./lib/core/base_hook_class.js";
+
+//#region src/agent.ts
+var EggAgentHook = class extends BaseHookClass {
+	configDidLoad() {
+		this.agent._wrapMessenger();
+	}
+};
+
+//#endregion
+export { EggAgentHook as default };

package/dist/app/extend/context.d.ts

@@ -0,0 +1,207 @@
+import Helper from "./helper.js";
+import { Application } from "../../lib/application.js";
+import { EggContextHttpClient as HttpClient, HttpClientRequestOptions, HttpClientRequestURL } from "../../lib/core/httpclient.js";
+import Response$1 from "./response.js";
+import Request$1 from "./request.js";
+import { BaseContextClass as BaseContextClass$1 } from "../../lib/core/base_context_class.js";
+import { Context as Context$1, Router } from "@eggjs/core";
+import { EggLogger } from "egg-logger";
+import { Cookies } from "@eggjs/cookies";
+
+//#region src/app/extend/context.d.ts
+interface Cookies$1 extends Cookies {
+  request: any;
+  response: any;
+}
+declare class Context extends Context$1 {
+  app: Application;
+  request: Request$1;
+  response: Response$1;
+  service: BaseContextClass$1;
+  proxy: any;
+  /**
+   * Request start time
+   * @member {Number} Context#starttime
+   */
+  starttime: number;
+  /**
+   * Request start timer using `performance.now()`
+   * @member {Number} Context#performanceStarttime
+   */
+  performanceStarttime: number;
+  /**
+   * Get the current visitor's cookies.
+   */
+  get cookies(): Cookies$1;
+  /**
+   * Get a wrapper httpclient instance contain ctx in the hold request process
+   *
+   * @return {HttpClient} the wrapper httpclient instance
+   */
+  get httpclient(): HttpClient;
+  /**
+   * Alias to {@link Context#httpclient}
+   */
+  get httpClient(): HttpClient;
+  /**
+   * Shortcut for httpclient.curl
+   *
+   * @function Context#curl
+   * @param {String|Object} url - request url address.
+   * @param {Object} [options] - options for request.
+   * @return {Object} see {@link ContextHttpClient#curl}
+   */
+  curl(url: HttpClientRequestURL, options?: HttpClientRequestOptions): ReturnType<HttpClient['request']>;
+  /**
+   * Alias to {@link Application#router}
+   *
+   * @member {Router} Context#router
+   * @since 1.0.0
+   * @example
+   * ```js
+   * this.router.pathFor('post', { id: 12 });
+   * ```
+   */
+  get router(): Router;
+  /**
+   * Set router to Context, only use on EggRouter
+   * @param {Router} val router instance
+   */
+  set router(val: Router);
+  /**
+   * Get helper instance from {@link Application#Helper}
+   *
+   * @member {Helper} Context#helper
+   * @since 1.0.0
+   */
+  get helper(): Helper;
+  /**
+   * Wrap app.loggers with context information,
+   * if a custom logger is defined by naming aLogger, then you can `ctx.getLogger('aLogger')`
+   *
+   * @param {String} name - logger name
+   */
+  getLogger(name: string): EggLogger;
+  /**
+   * Logger for Application
+   *
+   * @member {Logger} Context#logger
+   * @since 1.0.0
+   * @example
+   * ```js
+   * this.logger.info('some request data: %j', this.request.body);
+   * this.logger.warn('WARNING!!!!');
+   * ```
+   */
+  get logger(): EggLogger;
+  /**
+   * Logger for frameworks and plugins
+   *
+   * @member {Logger} Context#coreLogger
+   * @since 1.0.0
+   */
+  get coreLogger(): EggLogger;
+  /**
+   * locals is an object for view, you can use `app.locals` and `ctx.locals` to set variables,
+   * which will be used as data when view is rendering.
+   * The difference between `app.locals` and `ctx.locals` is the context level, `app.locals` is global level, and `ctx.locals` is request level. when you get `ctx.locals`, it will merge `app.locals`.
+   *
+   * when you set locals, only object is available
+   *
+   * ```js
+   * this.locals = {
+   *   a: 1
+   * };
+   * this.locals = {
+   *   b: 1
+   * };
+   * this.locals.c = 1;
+   * console.log(this.locals);
+   * {
+   *   a: 1,
+   *   b: 1,
+   *   c: 1,
+   * };
+   * ```
+   *
+   * `ctx.locals` has cache, it only merges `app.locals` once in one request.
+   *
+   * @member {Object} Context#locals
+   */
+  get locals(): Record<string, any>;
+  set locals(val: Record<string, any>);
+  /**
+   * alias to {@link Context#locals}, compatible with koa that use this variable
+   * @member {Object} state
+   * @see Context#locals
+   */
+  get state(): Record<string, any>;
+  set state(val: Record<string, any>);
+  /**
+   * Run async function in the background
+   * @param {Function} scope - the first args is ctx
+   * ```js
+   * this.body = 'hi';
+   *
+   * this.runInBackground(async ctx => {
+   *   await ctx.mysql.query(sql);
+   *   await ctx.curl(url);
+   * });
+   * ```
+   */
+  runInBackground(scope: (ctx: Context) => Promise<void>, taskName?: string): void;
+  _runInBackground(scope: (ctx: Context) => Promise<void>, taskName: string): Promise<void>;
+  /**
+   * @member {Boolean} Context#acceptJSON
+   * @see Request#acceptJSON
+   * @since 1.0.0
+   */
+  get acceptJSON(): boolean;
+  get query(): Record<string, string>;
+  /**
+   * @member {Array} Context#queries
+   * @see Request#queries
+   * @since 1.0.0
+   */
+  get queries(): Record<string, string[]>;
+  /**
+   * @member {string} Context#ip
+   * @see Request#ip
+   * @since 1.0.0
+   */
+  get ip(): string;
+  set ip(val: string);
+  /**
+   * @member {Number} Context#realStatus
+   * @see Response#realStatus
+   * @since 1.0.0
+   */
+  get realStatus(): number;
+  set realStatus(val: number);
+}
+declare module '@eggjs/core' {
+  interface Context {
+    proxy: any;
+    performanceStarttime: number;
+    starttime: number;
+    runInBackground(scope: (ctx: Context) => Promise<void>, taskName?: string): void;
+    _runInBackground(scope: (ctx: Context) => Promise<void>, taskName: string): void;
+    get acceptJSON(): boolean;
+    get query(): Record<string, string>;
+    get queries(): Record<string, string[]>;
+    curl(url: HttpClientRequestURL, options?: HttpClientRequestOptions): ReturnType<HttpClient['request']>;
+    get router(): Router;
+    set router(val: Router);
+    get helper(): Helper;
+    get httpclient(): HttpClient;
+    get httpClient(): HttpClient;
+    getLogger(name: string): EggLogger;
+    get logger(): EggLogger;
+    get coreLogger(): EggLogger;
+    get locals(): Record<string, any>;
+    get realStatus(): number;
+    set realStatus(val: number);
+  }
+}
+//#endregion
+export { Context as default };

package/dist/app/extend/context.js

@@ -0,0 +1,244 @@
+import { Context as Context$1, Router, utils } from "@eggjs/core";
+import { assign } from "utility";
+import { diff, now } from "performance-ms";
+
+//#region src/app/extend/context.ts
+const HELPER = Symbol("ctx helper");
+const LOCALS = Symbol("ctx locals");
+const LOCALS_LIST = Symbol("ctx localsList");
+const COOKIES = Symbol("ctx cookies");
+const CONTEXT_HTTPCLIENT = Symbol("ctx httpclient");
+const CONTEXT_ROUTER = Symbol("ctx router");
+var Context = class extends Context$1 {
+	/**
+	* Request start time
+	* @member {Number} Context#starttime
+	*/
+	starttime;
+	/**
+	* Request start timer using `performance.now()`
+	* @member {Number} Context#performanceStarttime
+	*/
+	performanceStarttime;
+	/**
+	* Get the current visitor's cookies.
+	*/
+	get cookies() {
+		let cookies = this[COOKIES];
+		if (!cookies) this[COOKIES] = cookies = new this.app.ContextCookies(this, this.app.keys, this.app.config.cookies);
+		return cookies;
+	}
+	/**
+	* Get a wrapper httpclient instance contain ctx in the hold request process
+	*
+	* @return {HttpClient} the wrapper httpclient instance
+	*/
+	get httpclient() {
+		if (!this[CONTEXT_HTTPCLIENT]) this[CONTEXT_HTTPCLIENT] = new this.app.ContextHttpClient(this);
+		return this[CONTEXT_HTTPCLIENT];
+	}
+	/**
+	* Alias to {@link Context#httpclient}
+	*/
+	get httpClient() {
+		return this.httpclient;
+	}
+	/**
+	* Shortcut for httpclient.curl
+	*
+	* @function Context#curl
+	* @param {String|Object} url - request url address.
+	* @param {Object} [options] - options for request.
+	* @return {Object} see {@link ContextHttpClient#curl}
+	*/
+	async curl(url, options) {
+		return await this.httpclient.curl(url, options);
+	}
+	/**
+	* Alias to {@link Application#router}
+	*
+	* @member {Router} Context#router
+	* @since 1.0.0
+	* @example
+	* ```js
+	* this.router.pathFor('post', { id: 12 });
+	* ```
+	*/
+	get router() {
+		if (this[CONTEXT_ROUTER]) return this[CONTEXT_ROUTER];
+		return this.app.router;
+	}
+	/**
+	* Set router to Context, only use on EggRouter
+	* @param {Router} val router instance
+	*/
+	set router(val) {
+		this[CONTEXT_ROUTER] = val;
+	}
+	/**
+	* Get helper instance from {@link Application#Helper}
+	*
+	* @member {Helper} Context#helper
+	* @since 1.0.0
+	*/
+	get helper() {
+		if (!this[HELPER]) this[HELPER] = new this.app.Helper(this);
+		return this[HELPER];
+	}
+	/**
+	* Wrap app.loggers with context information,
+	* if a custom logger is defined by naming aLogger, then you can `ctx.getLogger('aLogger')`
+	*
+	* @param {String} name - logger name
+	*/
+	getLogger(name) {
+		return this.app.getLogger(name);
+	}
+	/**
+	* Logger for Application
+	*
+	* @member {Logger} Context#logger
+	* @since 1.0.0
+	* @example
+	* ```js
+	* this.logger.info('some request data: %j', this.request.body);
+	* this.logger.warn('WARNING!!!!');
+	* ```
+	*/
+	get logger() {
+		return this.getLogger("logger");
+	}
+	/**
+	* Logger for frameworks and plugins
+	*
+	* @member {Logger} Context#coreLogger
+	* @since 1.0.0
+	*/
+	get coreLogger() {
+		return this.getLogger("coreLogger");
+	}
+	/**
+	* locals is an object for view, you can use `app.locals` and `ctx.locals` to set variables,
+	* which will be used as data when view is rendering.
+	* The difference between `app.locals` and `ctx.locals` is the context level, `app.locals` is global level, and `ctx.locals` is request level. when you get `ctx.locals`, it will merge `app.locals`.
+	*
+	* when you set locals, only object is available
+	*
+	* ```js
+	* this.locals = {
+	*   a: 1
+	* };
+	* this.locals = {
+	*   b: 1
+	* };
+	* this.locals.c = 1;
+	* console.log(this.locals);
+	* {
+	*   a: 1,
+	*   b: 1,
+	*   c: 1,
+	* };
+	* ```
+	*
+	* `ctx.locals` has cache, it only merges `app.locals` once in one request.
+	*
+	* @member {Object} Context#locals
+	*/
+	get locals() {
+		if (!this[LOCALS]) this[LOCALS] = assign({}, this.app.locals);
+		if (Array.isArray(this[LOCALS_LIST]) && this[LOCALS_LIST].length > 0) {
+			assign(this[LOCALS], this[LOCALS_LIST]);
+			this[LOCALS_LIST] = null;
+		}
+		return this[LOCALS];
+	}
+	set locals(val) {
+		const localsList = this[LOCALS_LIST] ?? [];
+		localsList.push(val);
+		this[LOCALS_LIST] = localsList;
+	}
+	/**
+	* alias to {@link Context#locals}, compatible with koa that use this variable
+	* @member {Object} state
+	* @see Context#locals
+	*/
+	get state() {
+		return this.locals;
+	}
+	set state(val) {
+		this.locals = val;
+	}
+	/**
+	* Run async function in the background
+	* @param {Function} scope - the first args is ctx
+	* ```js
+	* this.body = 'hi';
+	*
+	* this.runInBackground(async ctx => {
+	*   await ctx.mysql.query(sql);
+	*   await ctx.curl(url);
+	* });
+	* ```
+	*/
+	runInBackground(scope, taskName) {
+		if (!taskName) taskName = Reflect.get(scope, "_name") || scope.name || utils.getCalleeFromStack(true);
+		setImmediate(() => {
+			this._runInBackground(scope, taskName);
+		});
+	}
+	async _runInBackground(scope, taskName) {
+		const startTime = now();
+		try {
+			await scope(this);
+			this.coreLogger.info("[egg:background] task:%s success (%dms)", taskName, diff(startTime));
+		} catch (err) {
+			this.coreLogger.info("[egg:background] task:%s fail (%dms)", taskName, diff(startTime));
+			err.runInBackground = true;
+			this.app.emit("error", err, this);
+		}
+	}
+	/**
+	* @member {Boolean} Context#acceptJSON
+	* @see Request#acceptJSON
+	* @since 1.0.0
+	*/
+	get acceptJSON() {
+		return this.request.acceptJSON;
+	}
+	get query() {
+		return this.request.query;
+	}
+	/**
+	* @member {Array} Context#queries
+	* @see Request#queries
+	* @since 1.0.0
+	*/
+	get queries() {
+		return this.request.queries;
+	}
+	/**
+	* @member {string} Context#ip
+	* @see Request#ip
+	* @since 1.0.0
+	*/
+	get ip() {
+		return this.request.ip;
+	}
+	set ip(val) {
+		this.request.ip = val;
+	}
+	/**
+	* @member {Number} Context#realStatus
+	* @see Response#realStatus
+	* @since 1.0.0
+	*/
+	get realStatus() {
+		return this.response.realStatus;
+	}
+	set realStatus(val) {
+		this.response.realStatus = val;
+	}
+};
+
+//#endregion
+export { Context as default };

package/{src/app/extend/helper.ts → dist/app/extend/helper.d.ts}

@@ -1,12 +1,13 @@
-import url from 'node:url';
-import { BaseContextClass } from '../../lib/core/base_context_class.js';
+import { BaseContextClass } from "../../lib/core/base_context_class.js";
+
+//#region src/app/extend/helper.d.ts
 
 /**
  * The Helper class which can be used as utility function.
  * We support developers to extend Helper through ${baseDir}/app/extend/helper.js ,
  * then you can use all method on `ctx.helper` that is a instance of Helper.
  */
-export default class Helper extends BaseContextClass {
+declare class Helper extends BaseContextClass {
   /**
    * Generate URL path(without host) for route. Takes the route name and a map of named params.
    * @function Helper#pathFor
@@ -21,10 +22,7 @@ export default class Helper extends BaseContextClass {
    * ```
    * @return {String} url path(without host)
    */
-  pathFor(name: string, params: Record<string, any>): string {
-    return this.app.router.url(name, params);
-  }
-
+  pathFor(name: string, params: Record<string, any>): string;
   /**
    * Generate full URL(with host) for route. Takes the route name and a map of named params.
    * @function Helper#urlFor
@@ -38,7 +36,7 @@ export default class Helper extends BaseContextClass {
    * ```
    * @return {String} full url(with host)
    */
-  urlFor(name: string, params: Record<string, any>): string {
-    return this.ctx.protocol + '://' + this.ctx.host + url.resolve('/', this.pathFor(name, params));
-  }
+  urlFor(name: string, params: Record<string, any>): string;
 }
+//#endregion
+export { Helper as default };

package/dist/app/extend/helper.js

@@ -0,0 +1,47 @@
+import { BaseContextClass } from "../../lib/core/base_context_class.js";
+import url from "node:url";
+
+//#region src/app/extend/helper.ts
+/**
+* The Helper class which can be used as utility function.
+* We support developers to extend Helper through ${baseDir}/app/extend/helper.js ,
+* then you can use all method on `ctx.helper` that is a instance of Helper.
+*/
+var Helper = class extends BaseContextClass {
+	/**
+	* Generate URL path(without host) for route. Takes the route name and a map of named params.
+	* @function Helper#pathFor
+	* @param {String} name - Router Name
+	* @param {Object} params - Other params
+	*
+	* @example
+	* ```js
+	* app.get('home', '/index.htm', 'home.index');
+	* ctx.helper.pathFor('home', { by: 'recent', limit: 20 })
+	* => /index.htm?by=recent&limit=20
+	* ```
+	* @return {String} url path(without host)
+	*/
+	pathFor(name, params) {
+		return this.app.router.url(name, params);
+	}
+	/**
+	* Generate full URL(with host) for route. Takes the route name and a map of named params.
+	* @function Helper#urlFor
+	* @param {String} name - Router name
+	* @param {Object} params - Other params
+	* @example
+	* ```js
+	* app.get('home', '/index.htm', 'home.index');
+	* ctx.helper.urlFor('home', { by: 'recent', limit: 20 })
+	* => http://127.0.0.1:7001/index.htm?by=recent&limit=20
+	* ```
+	* @return {String} full url(with host)
+	*/
+	urlFor(name, params) {
+		return this.ctx.protocol + "://" + this.ctx.host + url.resolve("/", this.pathFor(name, params));
+	}
+};
+
+//#endregion
+export { Helper as default };