Nasty Popsicle Machine

    egg-errors
    TypeScript icon, indicating that this package has built-in type declarations

    2.3.1 • Public • Published

    egg-errors

    NPM version build status Test coverage David deps Known Vulnerabilities npm download

    Errors for Egg.js.

    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

    $ npm i egg-errors --save

    Usage

    Create an Error

    const { EggError, EggException } = require('egg-errors');
    let err = new EggError('egg error');
    console.log(EggError.getType(err)); // ERROR

    Create an Exception

    err = new EggException('egg exception');
    console.log(EggException.getType(err)); // EXCEPTION

    You can import an error from an normal error object

    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.

    const { EggBaseError } = require('egg-errors');
    
    class CustomError extends EggBaseError {
      constructor(message) {
        super({ message, code: 'CUSTOM_CODE' });
      }
     }

    or using typescript you can customize ErrorOptions.

    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.

    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;

    const { ForbiddenError } = require('egg-errors');
    const err = new ForbiddenError('your request is forbidden');
    console.log(err.status); // 403

    Support short name too:

    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 moduleserialNumber and errorContext

    FrameworkBaseError could not be used directly, framework/plugin should extends like this

    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

    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.

    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

    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

    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.

    License

    MIT

    Keywords

    none

    Install

    npm i egg-errors

    DownloadsWeekly Downloads

    88,047

    Version

    2.3.1

    License

    MIT

    Unpacked Size

    95.7 kB

    Total Files

    112

    Last publish

    Collaborators

    • atian25
    • wanghx
    • popomore
    • mansonchor
    • mansonchor.zzw