@eggjs/errors 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017-present Alibaba Group Holding Limited and other contributors.
+
+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.

package/README.md

@@ -0,0 +1,258 @@
+# egg-errors
+
+[![NPM version][npm-image]][npm-url]
+[![Node.js CI](https://github.com/eggjs/egg-errors/actions/workflows/nodejs.yml/badge.svg)](https://github.com/eggjs/egg-errors/actions/workflows/nodejs.yml)
+[![Test coverage][codecov-image]][codecov-url]
+[![Known Vulnerabilities][snyk-image]][snyk-url]
+[![npm download][download-image]][download-url]
+
+[npm-image]: https://img.shields.io/npm/v/egg-errors.svg?style=flat-square
+[npm-url]: https://npmjs.org/package/egg-errors
+[codecov-image]: https://codecov.io/gh/eggjs/egg-errors/branch/master/graph/badge.svg
+[codecov-url]: https://codecov.io/gh/eggjs/egg-errors
+[snyk-image]: https://snyk.io/test/npm/egg-errors/badge.svg?style=flat-square
+[snyk-url]: https://snyk.io/test/npm/egg-errors
+[download-image]: https://img.shields.io/npm/dm/egg-errors.svg?style=flat-square
+[download-url]: https://npmjs.org/package/egg-errors
+
+Errors for [Egg.js](https://eggjs.org)
+
+egg-errors provide two kinds of errors that is Error and Exception.
+
+- Exception is system error that egg will log an error and throw exception, but it will be catched by onerror plugin.
+- Error is business error that egg will transform it to response.
+
+## Install
+
+```bash
+$ npm i egg-errors --save
+```
+
+## Usage
+
+Create an Error
+
+```js
+const { EggError, EggException } = require('egg-errors');
+let err = new EggError('egg error');
+console.log(EggError.getType(err)); // ERROR
+```
+
+Create an Exception
+
+```js
+err = new EggException('egg exception');
+console.log(EggException.getType(err)); // EXCEPTION
+```
+
+You can import an error from an normal error object
+
+```js
+err = new Error('normal error');
+console.log(EggError.getType(err)); // BUILTIN
+err = EggError.from(err);
+console.log(EggError.getType(err)); // ERROR
+```
+
+### Customize Error
+
+Error can be extendable.
+
+```js
+const { EggBaseError } = require('egg-errors');
+
+class CustomError extends EggBaseError {
+  constructor(message) {
+    super({ message, code: 'CUSTOM_CODE' });
+  }
+}
+```
+
+or using typescript you can customize ErrorOptions.
+
+```js
+import { EggBaseError, ErrorOptions } from 'egg-errors';
+
+class CustomErrorOptions extends ErrorOptions {
+  public data: object;
+}
+class CustomError extends EggBaseError<CustomErrorOptions> {
+  public data: object;
+  protected options: CustomErrorOptions;
+
+  constructor(options?: CustomErrorOptions) {
+    super(options);
+    this.data = this.options.data;
+  }
+}
+```
+
+Recommend use message instead of options in user land that it can be easily understood by developer, see [http error](https://github.com/eggjs/egg-errors/blob/master/lib/http/400.ts).
+
+### HTTP Errors
+
+HTTP Errors is BUILTIN errors that transform 400 ~ 500 status code to error objects. HttpError extends EggBaseError providing two properties which is `status` and `headers`;
+
+```js
+const { ForbiddenError } = require('egg-errors');
+const err = new ForbiddenError('your request is forbidden');
+console.log(err.status); // 403
+```
+
+Support short name too:
+
+```js
+const { E403 } = require('egg-errors');
+const err = new E403('your request is forbidden');
+console.log(err.status); // 403
+```
+
+### FrameworkBaseError
+
+FrameworkBaseError is for egg framework/plugin developer to throw framework error.it can format by FrameworkErrorFormater
+
+FrameworkBaseError extends EggBaseError providing three properties which is `module`、`serialNumber` and `errorContext`
+
+FrameworkBaseError could not be used directly, framework/plugin should extends like this
+
+```js
+const { FrameworkBaseError } = require('egg-errors');
+
+class EggMysqlError extends FrameworkBaseError {
+  // module should be implement
+  get module() {
+    return 'EGG_MYSQL';
+  }
+}
+
+const err = new EggMysqlError('error message', '01', { traceId: 'xxx' });
+console.log(err.module); // EGG_MYSQL
+console.log(err.serialNumber); // 01
+console.log(err.code); // EGG_MYSQL_01
+console.log(err.errorContext); // { traceId: 'xxx' }
+```
+
+#### create frameworkError with formater
+
+use the static method `.create(message: string, serialNumber: string | number, errorContext?: any)` to new a frameworkError and format it convenient
+
+```js
+const { FrameworkBaseError } = require('egg-errors');
+
+class EggMysqlError extends FrameworkBaseError {
+  // module should be implement
+  get module() {
+    return 'EGG_MYSQL';
+  }
+}
+
+const err = EggMysqlError.create('error message', '01', { traceId: 'xxx' });
+console.log(err.message);
+// =>
+framework.EggMysqlError: error message [ https://eggjs.org/zh-cn/faq/EGG_MYSQL/01 ]
+```
+
+### FrameworkErrorFormater
+
+FrameworkErrorFormater will append a faq guide url in error message.this would be helpful when developer encountered a framework error
+
+the faq guide url format: `${faqPrefix}/${err.module}/${err.serialNumber}`, `faqPrefix` is `https://eggjs.org/zh-cn/faq` by default. can be extendable or set `process.env.EGG_FRAMEWORK_ERR_FAQ_PERFIX` to override it.
+
+```js
+const { FrameworkErrorFormater } = require('egg-errors');
+
+class CustomErrorFormatter extends FrameworkErrorFormater {
+  static faqPrefix = 'http://www.custom.com/faq';
+}
+```
+
+#### .format(err)
+
+format error to message, it will not effect origin error
+
+```js
+const { FrameworkBaseError, FrameworkErrorFormater } = require('egg-errors');
+
+class EggMysqlError extends FrameworkBaseError {
+  // module should be implement
+  get module() {
+    return 'EGG_MYSQL';
+  }
+}
+
+const message = FrameworkErrorFormater.format(new EggMysqlError('error message', '01'));
+console.log(message);
+// => message format like this
+framework.EggMysqlError: error message [ https://eggjs.org/zh-cn/faq/EGG_MYSQL/01 ]
+...stack
+...
+code: "EGG_MYSQL_01"
+serialNumber: "01"
+errorContext:
+pid: 66568
+hostname: xxx
+
+
+// extends
+class CustomErrorFormatter extends FrameworkErrorFormater {
+  static faqPrefix = 'http://www.custom.com/faq';
+}
+const message = CustomErrorFormatter.format(new EggMysqlError('error message', '01'));
+console.log(message);
+// =>
+framework.EggMysqlError: error message [ http://www.custom.com/faq/EGG_MYSQL/01 ]
+...
+```
+
+#### .formatError(err)
+
+append faq guide url to err.message
+
+```js
+const { FrameworkBaseError, FrameworkErrorFormater } = require('egg-errors');
+
+class EggMysqlError extends FrameworkBaseError {
+  // module should be implement
+  get module() {
+    return 'EGG_MYSQL';
+  }
+}
+
+const err = FrameworkErrorFormater.formatError(new EggMysqlError('error message', '01'));
+console.log(err.message); // error message [ https://eggjs.org/zh-cn/faq/EGG_MYSQL/01 ]
+```
+
+### Available Errors
+
+```
+BaseError
+|- EggBaseError
+|  |- EggError
+|  |- HttpError
+|  |  |- NotFoundError, alias to E404
+|  |  `- ...
+|  |- FrameworkBaseError
+|  `- CustomError
+`- EggBaseException
+   |- EggException
+   `- CustomException
+```
+
+## Questions & Suggestions
+
+Please open an issue [here](https://github.com/eggjs/egg/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc).
+
+## License
+
+[MIT](LICENSE)
+
+<!-- GITCONTRIBUTOR_START -->
+
+## Contributors
+
+| [<img src="https://avatars.githubusercontent.com/u/360661?v=4" width="100px;"/><br/><sub><b>popomore</b></sub>](https://github.com/popomore)<br/> | [<img src="https://avatars.githubusercontent.com/u/2160731?v=4" width="100px;"/><br/><sub><b>mansonchor</b></sub>](https://github.com/mansonchor)<br/> | [<img src="https://avatars.githubusercontent.com/u/156269?v=4" width="100px;"/><br/><sub><b>fengmk2</b></sub>](https://github.com/fengmk2)<br/> | [<img src="https://avatars.githubusercontent.com/u/12657964?v=4" width="100px;"/><br/><sub><b>beliefgp</b></sub>](https://github.com/beliefgp)<br/> | [<img src="https://avatars.githubusercontent.com/u/19644997?v=4" width="100px;"/><br/><sub><b>sm2017</b></sub>](https://github.com/sm2017)<br/> |
+| :-----------------------------------------------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------: |
+
+This project follows the git-contributor [spec](https://github.com/xudafeng/git-contributor), auto updated at `Tue Feb 22 2022 11:32:47 GMT+0800`.
+
+<!-- GITCONTRIBUTOR_END -->

package/dist/base.d.ts

@@ -0,0 +1,22 @@
+import { ErrorOptions } from "./error_options.js";
+import { ErrorType } from "./error_type.js";
+
+//#region src/base.d.ts
+declare const TYPE: symbol;
+declare class BaseError<T extends ErrorOptions> extends Error {
+  [TYPE]?: ErrorType | undefined;
+  [key: string]: any;
+  static getType(err: Error): ErrorType;
+  /**
+   * Create a new instance of the error class from an existing error
+   * @param err - The error to create a new instance from
+   * @param args - The arguments to pass to the constructor
+   * @returns A new instance of the error class
+   */
+  static from<S extends new (...args: any) => InstanceType<typeof BaseError>, P extends ConstructorParameters<S>>(this: S, err: Error, ...args: P | undefined[]): InstanceType<S>;
+  code: string;
+  protected options: T;
+  constructor(options?: T);
+}
+//#endregion
+export { BaseError };

package/dist/base.js

@@ -0,0 +1,35 @@
+import { ErrorType } from "./error_type.js";
+
+//#region src/base.ts
+const TYPE = Symbol.for("BaseError#type");
+var BaseError = class extends Error {
+	[TYPE];
+	static getType(err) {
+		return err[TYPE] ?? ErrorType.BUILTIN;
+	}
+	/**
+	* Create a new instance of the error class from an existing error
+	* @param err - The error to create a new instance from
+	* @param args - The arguments to pass to the constructor
+	* @returns A new instance of the error class
+	*/
+	static from(err, ...args) {
+		const newErr = new this(...args);
+		newErr.message = err.message;
+		newErr.stack = err.stack;
+		for (const key of Object.keys(err)) newErr[key] = err[key];
+		return newErr;
+	}
+	code;
+	options;
+	constructor(options) {
+		super();
+		this.options = options ?? {};
+		this.message = this.options.message ?? "";
+		this.code = this.options.code ?? "";
+		this.name = this.constructor.name;
+	}
+};
+
+//#endregion
+export { BaseError, TYPE };

package/dist/base_error.d.ts

@@ -0,0 +1,9 @@
+import { ErrorOptions } from "./error_options.js";
+import { BaseError } from "./base.js";
+
+//#region src/base_error.d.ts
+declare class EggBaseError<T extends ErrorOptions> extends BaseError<T> {
+  constructor(options?: T);
+}
+//#endregion
+export { EggBaseError };

package/dist/base_error.js

@@ -0,0 +1,13 @@
+import { ErrorType } from "./error_type.js";
+import { BaseError, TYPE } from "./base.js";
+
+//#region src/base_error.ts
+var EggBaseError = class extends BaseError {
+	constructor(options) {
+		super(options);
+		this[TYPE] = ErrorType.ERROR;
+	}
+};
+
+//#endregion
+export { EggBaseError };

package/dist/base_exception.d.ts

@@ -0,0 +1,9 @@
+import { ErrorOptions } from "./error_options.js";
+import { BaseError } from "./base.js";
+
+//#region src/base_exception.d.ts
+declare class EggBaseException<T extends ErrorOptions> extends BaseError<T> {
+  constructor(options?: T);
+}
+//#endregion
+export { EggBaseException };

package/dist/base_exception.js

@@ -0,0 +1,13 @@
+import { ErrorType } from "./error_type.js";
+import { BaseError, TYPE } from "./base.js";
+
+//#region src/base_exception.ts
+var EggBaseException = class extends BaseError {
+	constructor(options) {
+		super(options);
+		this[TYPE] = ErrorType.EXCEPTION;
+	}
+};
+
+//#endregion
+export { EggBaseException };

package/dist/error.d.ts

@@ -0,0 +1,9 @@
+import { ErrorOptions } from "./error_options.js";
+import { EggBaseError } from "./base_error.js";
+
+//#region src/error.d.ts
+declare class EggError extends EggBaseError<ErrorOptions> {
+  constructor(message?: string);
+}
+//#endregion
+export { EggError };

package/dist/error.js

@@ -0,0 +1,14 @@
+import { EggBaseError } from "./base_error.js";
+
+//#region src/error.ts
+var EggError = class extends EggBaseError {
+	constructor(message) {
+		super({
+			code: "EGG_ERROR",
+			message: message ?? ""
+		});
+	}
+};
+
+//#endregion
+export { EggError };

package/dist/error_options.d.ts

@@ -0,0 +1,8 @@
+//#region src/error_options.d.ts
+declare class ErrorOptions {
+  code?: string;
+  message: string;
+  [key: string]: any;
+}
+//#endregion
+export { ErrorOptions };

package/dist/error_options.js

@@ -0,0 +1,8 @@
+//#region src/error_options.ts
+var ErrorOptions = class {
+	code;
+	message;
+};
+
+//#endregion
+export { ErrorOptions };

package/dist/error_type.d.ts

@@ -0,0 +1,18 @@
+//#region src/error_type.d.ts
+declare const ErrorType: {
+  /**
+   * Built-in Error
+   */
+  readonly BUILTIN: "BUILTIN";
+  /**
+   * Egg Error
+   */
+  readonly ERROR: "ERROR";
+  /**
+   * Egg Exception
+   */
+  readonly EXCEPTION: "EXCEPTION";
+};
+type ErrorType = (typeof ErrorType)[keyof typeof ErrorType];
+//#endregion
+export { ErrorType };

package/dist/error_type.js

@@ -0,0 +1,9 @@
+//#region src/error_type.ts
+const ErrorType = {
+	BUILTIN: "BUILTIN",
+	ERROR: "ERROR",
+	EXCEPTION: "EXCEPTION"
+};
+
+//#endregion
+export { ErrorType };

package/dist/exception.d.ts

@@ -0,0 +1,9 @@
+import { ErrorOptions } from "./error_options.js";
+import { EggBaseException } from "./base_exception.js";
+
+//#region src/exception.d.ts
+declare class EggException extends EggBaseException<ErrorOptions> {
+  constructor(message?: string);
+}
+//#endregion
+export { EggException };

package/dist/exception.js

@@ -0,0 +1,14 @@
+import { EggBaseException } from "./base_exception.js";
+
+//#region src/exception.ts
+var EggException = class extends EggBaseException {
+	constructor(message) {
+		super({
+			code: "EGG_EXCEPTION",
+			message: message ?? ""
+		});
+	}
+};
+
+//#endregion
+export { EggException };

package/dist/framework/formatter.d.ts

@@ -0,0 +1,12 @@
+//#region src/framework/formatter.d.ts
+declare class FrameworkErrorFormater {
+  protected static faqPrefix: string;
+  /**
+   * Custom framework error FAQ prefix
+   */
+  private static faqPrefixEnv;
+  static format(err: Error): string;
+  static formatError<T extends Error>(err: T): T;
+}
+//#endregion
+export { FrameworkErrorFormater };

package/dist/framework/formatter.js

@@ -0,0 +1,28 @@
+import { FrameworkBaseError } from "./framework_base_error.js";
+import util from "node:util";
+import os from "node:os";
+
+//#region src/framework/formatter.ts
+const hostname = os.hostname();
+var FrameworkErrorFormater = class {
+	static faqPrefix = "https://eggjs.org/zh-cn/faq";
+	/**
+	* Custom framework error FAQ prefix
+	*/
+	static faqPrefixEnv = process.env.EGG_FRAMEWORK_ERR_FAQ_PERFIX;
+	static format(err) {
+		const faqPrefix = this.faqPrefixEnv ?? this.faqPrefix;
+		let errMessage = err.message;
+		if (FrameworkBaseError.isFrameworkError(err) && !errMessage.includes(faqPrefix)) errMessage += ` [ ${faqPrefix}/${err.code} ]`;
+		const errStack = err.stack || "no_stack";
+		return util.format("framework.%s: %s\n%s\ncode: %s\nserialNumber: %s\nerrorContext: %j\npid: %s\nhostname: %s\n", err.name, errMessage, errStack.substring(errStack.indexOf("\n") + 1), err.code, err.serialNumber, err.errorContext, process.pid, hostname);
+	}
+	static formatError(err) {
+		const faqPrefix = this.faqPrefixEnv ?? this.faqPrefix;
+		if (FrameworkBaseError.isFrameworkError(err) && !err.message.includes(faqPrefix)) err.message += ` [ ${faqPrefix}/${err.code} ]`;
+		return err;
+	}
+};
+
+//#endregion
+export { FrameworkErrorFormater };

package/dist/framework/framework_base_error.d.ts

@@ -0,0 +1,15 @@
+import { ErrorOptions } from "../error_options.js";
+import { EggBaseError } from "../base_error.js";
+
+//#region src/framework/framework_base_error.d.ts
+declare const FRAMEWORK_ERROR_SYMBOL: unique symbol;
+declare class FrameworkBaseError extends EggBaseError<ErrorOptions> {
+  readonly serialNumber: string;
+  readonly errorContext?: any;
+  get module(): string;
+  constructor(message: string, serialNumber: string | number, errorContext?: any);
+  static create(message: string, serialNumber: string | number, errorContext?: any): FrameworkBaseError;
+  static isFrameworkError(err: Error): err is FrameworkBaseError;
+}
+//#endregion
+export { FRAMEWORK_ERROR_SYMBOL, FrameworkBaseError };

package/dist/framework/framework_base_error.js

@@ -0,0 +1,37 @@
+import { EggBaseError } from "../base_error.js";
+import { FrameworkErrorFormater } from "./formatter.js";
+import assert from "node:assert";
+
+//#region src/framework/framework_base_error.ts
+const FRAMEWORK_ERROR_SYMBOL = Symbol.for("FrameworkBaseError");
+var FrameworkBaseError = class extends EggBaseError {
+	serialNumber;
+	errorContext;
+	get module() {
+		throw new Error("module should be implement");
+	}
+	constructor(message, serialNumber, errorContext) {
+		super({
+			message,
+			serialNumber,
+			errorContext
+		});
+		assert(message, "message is required");
+		assert(serialNumber, "serialNumber is required");
+		this.serialNumber = `${serialNumber}`;
+		this.errorContext = errorContext ?? "";
+		this.code = `${this.module}_${this.serialNumber}`;
+		this[FRAMEWORK_ERROR_SYMBOL] = true;
+	}
+	static create(message, serialNumber, errorContext) {
+		const err = FrameworkErrorFormater.formatError(new this(message, serialNumber, errorContext));
+		Error.captureStackTrace(err, this.create);
+		return err;
+	}
+	static isFrameworkError(err) {
+		return err[FRAMEWORK_ERROR_SYMBOL] === true;
+	}
+};
+
+//#endregion
+export { FRAMEWORK_ERROR_SYMBOL, FrameworkBaseError };

package/dist/http/400.d.ts

@@ -0,0 +1,8 @@
+import { HttpError } from "./http_error.js";
+
+//#region src/http/400.d.ts
+declare class BadRequestError extends HttpError {
+  constructor(message?: string);
+}
+//#endregion
+export { BadRequestError };

package/dist/http/400.js

@@ -0,0 +1,18 @@
+import { HttpError } from "./http_error.js";
+
+//#region src/http/400.ts
+var BadRequestError = class extends HttpError {
+	constructor(message) {
+		const status = 400;
+		const code = "BAD_REQUEST";
+		message = message ?? "Bad Request";
+		super({
+			code,
+			message,
+			status
+		});
+	}
+};
+
+//#endregion
+export { BadRequestError };

package/dist/http/401.d.ts

@@ -0,0 +1,8 @@
+import { HttpError } from "./http_error.js";
+
+//#region src/http/401.d.ts
+declare class UnauthorizedError extends HttpError {
+  constructor(message?: string);
+}
+//#endregion
+export { UnauthorizedError };

package/dist/http/401.js

@@ -0,0 +1,18 @@
+import { HttpError } from "./http_error.js";
+
+//#region src/http/401.ts
+var UnauthorizedError = class extends HttpError {
+	constructor(message) {
+		const status = 401;
+		const code = "UNAUTHORIZED";
+		message = message ?? "Unauthorized";
+		super({
+			code,
+			message,
+			status
+		});
+	}
+};
+
+//#endregion
+export { UnauthorizedError };

package/dist/http/402.d.ts

@@ -0,0 +1,8 @@
+import { HttpError } from "./http_error.js";
+
+//#region src/http/402.d.ts
+declare class PaymentRequiredError extends HttpError {
+  constructor(message?: string);
+}
+//#endregion
+export { PaymentRequiredError };

package/dist/http/402.js

@@ -0,0 +1,18 @@
+import { HttpError } from "./http_error.js";
+
+//#region src/http/402.ts
+var PaymentRequiredError = class extends HttpError {
+	constructor(message) {
+		const status = 402;
+		const code = "PAYMENT_REQUIRED";
+		message = message ?? "Payment Required";
+		super({
+			code,
+			message,
+			status
+		});
+	}
+};
+
+//#endregion
+export { PaymentRequiredError };