Skip to content
/ terror Public

Base error class which will help you organize errors, generate informative logs and as result grep logs more effectively

License

Notifications You must be signed in to change notification settings

nodules/terror

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Terror NPM version Build Status

Development Dependency status

Base error class which will help you organize errors, generate informative logs and as result grep logs more effectively.

Trivial usage

var Terror = require('terror'),

    // declare error type with custom error codes and messages
    MyError = Terror.create('MyError', {
        STRANGE_THING_HAPPENS: 'Something strange happens'
    });

try {
    // ...

    if (typeof userInput === 'undefined') {
        // throw error
        throw new MyError(MyError.CODES.STRANGE_THING_HAPPENS);
        // or
        // throw MyError.createError(MyError.CODES.STRANGE_THING_HAPPENS);
    }
} catch (err) {
    // ensureError method returns err if it is an instance of MyError,
    // otherwise wrap Error instance in the MyError with default code UNKNOWN_ERROR
    MyError.ensureError(err)
        .log();
}

Constructor

new Terror(code, originalError);
new Terror(code, message);
new Terror(code);
new Terror();

Also can be called as a function, then calls self as the constructor internally and returns created instance.

Both arguments are not required:

  • if only code passed, message will got from Terror.MESSAGES hash by the code value as the key;
  • if code is absent, will be used default value Terror.CODES.UNKNOWN_ERROR.

Constructor methods

create(name, codes)

Returns constructor inherited from Terror. You must specify name for logging purpose.

Arguments:

  • {String} name – Error class name for logging;
  • {Object} [codes] - CODES hash { CODE_NAME: 'error message', … }

Example:

var AppError = Terror.create('AppError'),
    ControllerError = AppError.create('ControllerError', {
        IO_ERROR: 'Broken IO',
        FS_ERROR: 'Broken %fsName% file-system'
    });

extendCodes(codes)

Extends CODES and associated MESSAGES hashes using codes declaration. Method throws an error if codes uniqueness violated by extension.

Example:

var AppError = Terror
        .create('AppError')
        .extendCodes({
                BROKEN_CONFIG: 'Looks like configuration file is broken.',
                DB_CONNECTION_FAILED: 'Can not connect to database %db_host%'
        });

// now you can use AppError.CODES.BROKEN_CONFIG & AppError.CODES.DB_CONNECTION_FAILED to produce errors
new AppError(AppError.CODES.BROKEN_CONFIG);

setLogger(logger)

Set function which error class and its inheritors will use for logging. It called by log method with two arguments: message and level.

Example:

var log = [],
    logger = function(message, level) {
        log.push([ new Date(), level, message ].join());
    },
    MyError = Terror.create('MyError').setLogger(logger);

MyError.createError().log();

console.log(log.join('\n'));

createError(code, message | originalError | data)

Creates new Terror or its inheritor instance.

Arguments:

  • {Number} [code] – error code from CODES hash, Terror.CODES.UNKNOWN_ERROR used as default value;
  • {String|Error|Terror|Object} [message|originalError|data] ** if 2nd argument is String then use it as original error message; ** if 2nd argument is Error then use its message and call-stack to format original message; ** if 2nd argument is an Object then replace error message placeholders with provided data.

Example:

var MyError = Terror.create('MyError', {
        IO_ERROR: 'Broken IO',
        FS_ERROR: 'Broken %fsName% file-system'
    });

// valid createError calls

// "UNKNOWN_ERROR Terror: Unknown error"
Terror.createError();

// same as above
Terror.createError(Terror.CODES.UNKNOWN_ERROR);

// "UNKNOWN_ERROR MyError: Unknown error"
MyError.createError();

// "IO_ERROR MyError: Broken IO"
MyError.createError(MyError.CODES.IO_ERROR);

// "IO_ERROR MyError: Broken IO (Error: kbd int broken)"
MyError.createError(MyError.CODES.IO_ERROR, new Error('kbd int broken'));

// "FS_ERROR MyError: Broken vfat file-system"
MyError.createError(MyError.CODES.FS_ERROR, { fsName: 'vfat' });

// fails, because code IO_ERROR is not defined for Terror
Terror.createError(MyError.CODES.IO_ERROR);

ensureError(originalError, code)

Returns originalError if it's an instance of the owning class. Otherwise wrap originalError into new owning class instance using code or UNKNOWN_ERROR code if second argument is absent.

Example:

var MyError = Terror.create('MyError', {
        EMPTY_MESSAGE: 'Message string is empty',
        UNEXPECTED_ERROR: 'Unexpected error'
    }),
    arr = [ { msg: "hello" }, { msg: "" }, {} ];

arr.forEach(function(item) {
    try {
        if (item.msg.length > 0) {
            console.log(item.msg);
        } else {
            throw MyError.createError(MyError.CODES.EMPTY_MESSAGE);
        }
    } catch (err) {
        throw MyError.ensureError(err, MyError.CODES.UNEXPECTED_ERROR)
            .log(); // logging like MyError instance
    }
})

isTerror(error)

Checks whether the error is an instance of Terror class.

Example:

var err = new Error('average error here');
Terror.isTerror(err) === false;

var terr = Terror.ensureError(err);
Terror.isTerror(terr) === true;

is(code, error)

Checks whether the error is an instance of the context class and an error code equals the passed one.

Example:

var MyError = Terror.create('MyError', {
        XCODE: 'code X',
        ZCODE: 'code Z'
    });

MyError.is(MyError.CODES.XCODE, MyError.createError(MyError.CODES.XCODE)); // => true
MyError.is(MyError.CODES.ZCODE, MyError.createError(MyError.CODES.XCODE)); // => false
MyError.is(MyError.CODES.XCODE, Terror.createError()); // => false

Methods of prototype

log(level)

Log error with specified level. If method called twice or more for the same instance, logger will be called by first log call only.

Arguments:

  • {*} [level=constructor.DEFAULT_LOG_LEVEL] – any type accepted by logger.

Example:

var Terror = require('terror'),
    terr;

Terror.DEFAULT_LOG_LEVEL = 'INFO';

try {
    console.lag("hello!");
} catch (err) {
    terr = Terror.ensureError(err);
    terr.log()
        .log('warn')
        .log('error');
}

terr will be logged once with 'INFO' error level.

bind(data)

Fill an error message with values from data object properties.

Arguments:

  • {Object} data – hash, where key is a placeholder name to be replaced, value – a data to replace with.

Example:

var IOError = Terror.create('MyError', {
        IO_ERROR: 'Broken IO pipe "%pipe%"'
    });

IOError.createError(IOError.CODES.IO_ERROR)
    .bind({ pipe: 'main bus' })
    .log('PANIC');
// or
IOError.createError(IOError.CODES.IO_ERROR, { pipe: 'main bus' })
    .log('PANIC');

Internal, but useful prototype methods

Following methods used by built-in logger routine, but may be useful for any simple text logger.

logMultilineError(message, level, logger)

Formats error message and calls logger(formattedMessage).

Formatting is optimized for output call-stacks to the text files and future grep through.

Format:

LEVEL CODE CLASS: MESSAGE
>>>>>   CALL STACK ROW 1
…
>>>>>   CALL STACK ROW N

Example:

ERROR UNKNOWN_ERROR Terror: Unknown error (TypeError: Object #<Console> has no method 'lag')
>>>>>     at repl:2:9
>>>>>     at REPLServer.self.eval (repl.js:110:21)
>>>>>     at repl.js:249:20
>>>>>     at REPLServer.self.eval (repl.js:122:7)
>>>>>     at Interface.<anonymous> (repl.js:239:12)
>>>>>     at Interface.EventEmitter.emit (events.js:95:17)
>>>>>     at Interface._onLine (readline.js:202:10)
>>>>>     at Interface._line (readline.js:531:8)
>>>>>     at Interface._ttyWrite (readline.js:754:14)
>>>>>     at ReadStream.onkeypress (readline.js:99:10)

About

Base error class which will help you organize errors, generate informative logs and as result grep logs more effectively

Resources

License

Stars

Watchers

Forks

Packages

No packages published