Exception utils package

This package provides util class BaseException.

Install

npm install @hyper-graph/exception or yarn add @hyper-graph/exception

Basic usage

class CustomException extends BaseException {
    public constructor() {
        super('Your message');
    }
}

Features

Code

You can pass code to error class that can be used by clients for identify exception.

Stylization

BaseException class implements some extra methods like toString(), toJSON and [inpect.custom]. It helps to see pretty errors in logs.

Stack trace support

It understands then you run node with --enable-source-maps flag.

Without source map enabled:

Error:

console.log(new Error('Test error'))
/*
 Error: Test error
 at Object.<anonymous> (/path/to/project/packages/exception/dist/index.js:11:13)
 at Module._compile (internal/modules/cjs/loader.js:1063:30)
 at Object.Module._extensions..js (internal/modules/cjs/loader.js:1092:10)
 at Module.load (internal/modules/cjs/loader.js:928:32)
 at Function.Module._load (internal/modules/cjs/loader.js:769:14)
 at Function.executeUserEntryPoint [as runMain] (internal/modules/run_main.js:72:12)
 at internal/main/run_main_module.js:17:47
 */

BaseException:

class TestException extends BaseException {
    public constructor() {
        super('Test exception', 10);
    }
}

console.log(new TestException())
/*
 TestException [code: 10]: Test exception
 at Object.<anonymous> (/path/to/project/packages/exception/dist/index.js:12:13)
 */

With source map enabled:

Error:

console.log(new Error('Test error'))
/*
Error: Test error
    at Object.<anonymous> (/path/to/project/packages/exception/dist/index.js:11:13) // IDEs highlite it
      -> /path/to/project/packages/exception/src/index.ts:13:13 // IDEs don't highlite it.
    at Module._compile (internal/modules/cjs/loader.js:1063:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1092:10)
    at Module.load (internal/modules/cjs/loader.js:928:32)
    at Function.Module._load (internal/modules/cjs/loader.js:763:16)
    at Function.executeUserEntryPoint [as runMain] (internal/modules/run_main.js:72:12)
    at internal/main/run_main_module.js:17:47
 */

BaseException:

class TestException extends BaseException {
	public constructor() {
		super('Test exception', 10);
	}
}

console.log(new TestException())
/*
TestException [code: 10]: Test exception
  at Object.<anonymous> (/path/to/project/packages/exception/src/index.ts:14:13) // IDEs highlite it
 */

API

Types

JSONBaseException

type JSONBaseException = {
	name: string;
	code: Nullable<number>; 
	message: string;
	stack: string[];
};

• name - Name of extended class.
• code - Code that was passed into constructor. If you don't pass code, it will be null.
• message - Message that was passed into constructor.
• stack - Array of trimmed stack lines. Internal nodejs stack (started from internal/) won't be in this array

BaseException

constructor(message: string, code?: number)

You must pass any message to BaseException.constructor via super. You also can pass optional code in second argument. (Recommended)

constructor(message: string, code?: number)

• message - Error message what you want to associate with error.
• code - error code that can uniquely identify the error. Helpful for pass it to clients (Optional, but recommended)

isFromNextTick(): boolean

Return true then exception was generated in process.nextTick callback or deeper in a stack.

isFromImmediate(): boolean

Return true then exception was generated in setImmediate callback or deeper in a stack.

isFromTimer(): boolean

Return true then exception was generated in setTimeout or in setInterval callback or deeper in a stack.

toJSON(stackDepth: Nullable<number> = null): JSONBaseException

Serialize and return serialized exception. Result will be saved for using in next calls.

It also will be called in JSON.stringify method.

• stackDepth - argument that will return only first stackDepth elements from stack. Returns all stack then null is passed (this behaviour also uses for JSON.stringify).

toString(stackDepth: Nullable<number> = null): string

Return error in string presentation. Example:

TestException: Test message
    at SerializationTestSuite.commonTest (/path/to/place/where/was/erased)
    at Object.<anonymous> (/path/to/place/where/was/erased)

[inspect.custom](depth: Nullable<number>): string

Return stylized string (with red colour). Used by util.inspect and console methods (also through util.inspect).

• depth - argument that specify stack lines count. It provided by util.inspect method and can be specified in util.inspect.defaultOptions.depth.