ts-nested-error


Super lightweight crossplatform (browser compatible) dependency-free nested error implementation.

:zap: Rationale

Suppose you are handling some low-level error and need to throw a higher-level one while having its original cause attached to it for debug purposes.

This package provides an extremely concise C#-like NestedError implementation for you:

``ts
import { NestedError } from 'ts-nested-error';

try {
dataService.saveData(data);
} catch (err) {
throw new NestedError("DataService failed to save data", err);
}
`
This code will produce an error that when stringified shows the following message:
`
NestedError: DataService failed to save data
at someMethod (/path/to/code.js:line:column)
at ...

======= INNER ERROR =======

Error: Connection timed out
at someMethod (/path/to/code.js:line:column)
at ...
`

:scroll: Documentation

Everything is strongly typed and you may expect good inline documentation from VSCode.

:sunglasses: Features of NestedError

$3


Property .stack of NestedError is guaranteed to contain a string with error
callstack if it is supported by runtime or "${err.name}: ${err.message}" as a fallback.

$3

NestedError constructor automatically coerces the values passed after the first argument toError() object and saves them in .innerErrors array property.

$3

Suppose you invoke some async operation and don't want to to write verbose
error handling lambda to pass as onerror callback to .then() or .catch().

Static NestedError.rethrow(message) method is here to shorten you code:

`ts
userService.getPage().then(
data => console.log(Hooray! data: ${data}),
err => {
throw new NestedError('failed to fetch users page', err);
}
);

↓ ↓ ↓ ↓ ↓ ↓

userService.getPage().then(
data => console.log(Hooray! data: ${data}),
NestedError.rethrow('failed to fetch users page')
);
`
It just creates the same error handling callback that rethrows passed-in error with given message.




$3

Suppose you are handling an error within the catch clause.
Though it may seem very unlikely, the thrown value is not required to be instanceof Error.

Exported toError(value) free function ensures that for you.

It returns value itself if value instanceof Error, otherwise attempts to
stringify it and wrap into Error object to be returned.

`ts
const err = new Error('oops');

// noop if err instanceof Error
toError(err) === err;

// wrapped 42 into Error with warning message
(toError(42) instanceof Error) === true;

toError('non-error value').message === Value that is not an instance of Error was thrown: non-error value

``