npm package: @hyper-graph/exception
Description: This package provides util class BaseException.
Latest version: 1.1.0

# Exception utils package

This package provides util class BaseException.

## Install

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

## Basic usage

```ts
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:
```ts
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:
```ts
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:
```ts
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:
```ts
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
```ts
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:
```text
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`.