@util.js/errors

JavaScript utility methods for errors

@util.js/errors is part of Util.js.

Errors API

Kind: global class
Access: public

• Errors
  • .AsyncError
    • new AsyncError()
  • .RethrownError
    • new RethrownError(error, [message])
  • .catch(promise, [message]) ⇒ Promise

errors.AsyncError

Kind: instance class of Errors
Access: public

new AsyncError()

An error that preserves the stack trace of the thread that calls an asynchronous function.

Use catch to use this class. Use this class directly for instanceof checks.

errors.RethrownError

Kind: instance class of Errors
Access: public

new RethrownError(error, [message])

A wrapper of another error used for rethrowing.

This error preserves information about the original error and its stack trace.

A Stack Overflow article inspired this class.

Throws:

• TypeError if the given error is not defined

| Param | Type | Description | | --------- | ------------------- | ----------------------------------------- | | error | Error | The error to rethrow | | [message] | String | A human-readable description of the error |

Example

function throwATypeError() {
  throw new TypeError("Invalid Argument");
}

function rethrowTheTypeError() {
  try {
    throwATypeError();
  } catch (error) {
    throw new RethrownError(error, "Lorem Ipsum");
  }
}

try {
  rethrowTheTypeError();
} catch (error) {
  console.log(error.stack);
  // This outputs a stack trace like the following:
  //
  // RethrownError: Lorem Ipsum
  //     at rethrowTheTypeError (/root/utiljs/packages/utiljs-errors/test/ErrorsTest.js:16:15)
  // TypeError: Invalid Argument
  //     at throwATypeError (/root/utiljs/packages/utiljs-errors/test/ErrorsTest.js:10:13)
  //     at rethrowTheTypeError (/root/utiljs/packages/utiljs-errors/test/ErrorsTest.js:14:9)
  //     at Context.it (/root/utiljs/packages/utiljs-errors/test/ErrorsTest.js:20:7)
  //     ...
}

errors.catch(promise, [message]) ⇒ Promise

Wraps the given promise so that errors caught preserve the stack trace of the calling thread.

The example compares the stack trace of a rejected promise using this method and the stack trace of a rejected promise that does not use this method.

Kind: instance method of Errors
Returns: Promise - A promise that upon rejection wraps the error in an AsyncError and rethrows
Throws:

• TypeError If the given promise is not an instance of Promise

Access: public

| Param | Type | Description | | --------- | -------------------- | ----------------------------------------- | | promise | Promise | The promise to wrap | | [message] | String | A human-readable description of the error |

Example

const errors = require("@util.js/errors");
function rejectAPromise() {
  return Promise.reject(new TypeError("Fail!"));
}

errors
  .catch(rejectAPromise())
  .catch((error) => console.log("\n\nWith Caller Stack Trace\n" + error.stack));
// With Caller Stack Trace
// AsyncError: Fail!
//     at promise.catch.error (/root/utiljs/packages/utiljs-errors/lib/Errors.js:28:13)
//     at process._tickCallback (internal/process/next_tick.js:68:7)
//     at Function.Module.runMain (internal/modules/cjs/loader.js:746:11)
//     at startup (internal/bootstrap/node.js:240:19)
//     at bootstrapNodeJSCore (internal/bootstrap/node.js:564:3)
//     at runExample0 (/root/utiljs/packages/utiljs-errors/doc/README-examples.js:23:11)
//     at runExample (/root/utiljs/packages/utiljs-errors/doc/README-examples.js:12:7)
//     at Object.<anonymous> (/root/utiljs/packages/utiljs-errors/doc/README-examples.js:4:31)
//     at Module._compile (internal/modules/cjs/loader.js:702:30)
//     at Object.Module._extensions..js (internal/modules/cjs/loader.js:713:10)
//     at Module.load (internal/modules/cjs/loader.js:612:32)
//     at tryModuleLoad (internal/modules/cjs/loader.js:551:12)
//     at Function.Module._load (internal/modules/cjs/loader.js:543:3)
//     at Function.Module.runMain (internal/modules/cjs/loader.js:744:10)
// TypeError: Fail!
//     at rejectAPromise (/root/utiljs/packages/utiljs-errors/doc/README-examples.js:20:27)
//     at runExample0 (/root/utiljs/packages/utiljs-errors/doc/README-examples.js:23:12)
//     at runExample (/root/utiljs/packages/utiljs-errors/doc/README-examples.js:12:7)
//     at Object.<anonymous> (/root/utiljs/packages/utiljs-errors/doc/README-examples.js:4:31)
//     at Module._compile (internal/modules/cjs/loader.js:702:30)
//     at Object.Module._extensions..js (internal/modules/cjs/loader.js:713:10)
//     at Module.load (internal/modules/cjs/loader.js:612:32)
//     at tryModuleLoad (internal/modules/cjs/loader.js:551:12)
//     at Function.Module._load (internal/modules/cjs/loader.js:543:3)
//     at Function.Module.runMain (internal/modules/cjs/loader.js:744:10)

rejectAPromise().catch((error) =>
  console.log("\n\nWithout Caller Stack Trace\n" + error.stack)
);
// Without Caller Stack Trace
// TypeError: Fail!
//     at rejectAPromise (/root/utiljs/packages/utiljs-errors/doc/README-examples.js:20:27)
//     at runExample0 (/root/utiljs/packages/utiljs-errors/doc/README-examples.js:53:3)
//     at runExample (/root/utiljs/packages/utiljs-errors/doc/README-examples.js:12:7)
//     at Object.<anonymous> (/root/utiljs/packages/utiljs-errors/doc/README-examples.js:4:31)
//     at Module._compile (internal/modules/cjs/loader.js:702:30)
//     at Object.Module._extensions..js (internal/modules/cjs/loader.js:713:10)
//     at Module.load (internal/modules/cjs/loader.js:612:32)
//     at tryModuleLoad (internal/modules/cjs/loader.js:551:12)
//     at Function.Module._load (internal/modules/cjs/loader.js:543:3)
//     at Function.Module.runMain (internal/modules/cjs/loader.js:744:10)