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:

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

Stack property

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.

InnerErrors property

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

Promise error handler shortcut

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:

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.

Coerce values to Error

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.

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`