utiljs-errors

JavaScript utility methods for errors

utiljs-errors is part of Util.js.

Errors API

Kind: global class
Access: public

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

errors.AsyncError

Kind: instance class of Errors
Access: public

new Errors#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 Errors#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) ⇒ 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

Param	Type	Description
promise	Promise	The promise to wrap

Example

const errors = require("utiljs-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)