Errors

A collection of utilities for working with JavaScript/TypeScript errors.

Table of contents

• Installation
• WrappedError
• Errors Utility Functions
  • .wrap
  • .wraps
  • .unwrap

Installation

npm install @mvf4z7/errors

WrappedError

An error class that can be used to wrap an existing error object with a new one. The new error has it's own error message, but the stack trace is composed of the newly created error and the wrapped error.

const error = new Error('message');
const wrappedError = new WrappedError('Additional message', error);

WrappedError.causedBy

A reference to the original error that was wrapped.

const error = new Error('message');
const wrappedError = new WrappedError('additional message', error);

wrappedError.causedBy === error; // true

WrappedError.stack

Because WrappedError extends the built in Error class, a WrappedError instance stores a stack trace that can be referenced through the stack property. A WrappedError's stack trace is composed of the stack trace of the WrappedError's own stack trace, as well as the stack trace of the error that was was wrapped.

function fetchUsers() {
  throw new Error('Network error!');
}

try {
  try {
    fetchUsers();
  } catch (error) {
    throw new WrappedError('Failed to fetch users', error);
  }
} catch (error) {
  console.log(error.stack);

  /* error.stack value
  
  WrappedError: Failed to fetch users
      at Object.<anonymous> (/Users/john-doe/Code/errors-test/index.js:11:11)
      at Module._compile (internal/modules/cjs/loader.js:1068:30)
      at Object.Module._extensions..js (internal/modules/cjs/loader.js:1097:10)
      at Module.load (internal/modules/cjs/loader.js:933:32)
      at Function.Module._load (internal/modules/cjs/loader.js:774:14)
      at Function.executeUserEntryPoint [as runMain] (internal/modules/run_main.js:72:12)
      at internal/main/run_main_module.js:17:47
  Caused by: Error: Network error!
      at fetchUsers (/Users/john-doe/Code/errors-test/index.js:4:9)
      at Object.<anonymous> (/Users/john-doe/Code/errors-test/index.js:9:5)
      at Module._compile (internal/modules/cjs/loader.js:1068:30)
      at Object.Module._extensions..js (internal/modules/cjs/loader.js:1097:10)
      at Module.load (internal/modules/cjs/loader.js:933:32)
      at Function.Module._load (internal/modules/cjs/loader.js:774:14)
      at Function.executeUserEntryPoint [as runMain] (internal/modules/run_main.js:72:12)
      at internal/main/run_main_module.js:17:47

    */
}

Errors utility functions

.wrap(message: string, error: Error) : WrappedError

A shorthand function for creating an instance of WrappedError. See the WrappedError docs for more details on the returned error object.

try {
  const id = 123;
  getFooById(id);
} catch (error) {
  throw Errors.wrap(`Failed to get Foo with ID ${id}.`, error);
}

.wraps<T extends Error>(error: Error, ErrorClass: ClassType<T>): boolean

Tests if the provided error object is an instance of the provided error class or wraps an error of the provided error class. If the provided error object is an instance of the WrappedError class or another class that extends WrappedError, the errors causeBy property will be recursively checked for instances of the provided error class.

class CustomError extends Error {
  constructor() {
    super('A meaningful error message');
    this.name = 'CustomError';
  }
}

const customError = new CustomerError();
const wrappedError = Errors.wrap('Additional error message', customError);

Errors.wraps(customError, CustomError); // true
Errors.wraps(wrappedError, CustomError); // true
Errors.wraps(customError, TypeError); // false
Errors.wraps(wrappedError, TypeError); // false

.unwrap<T extends Error>(error: Error, ErrorClass: ClassType<T>): T | null

If the provided error object is an instance of WrappedError then the error's causedBy property is unwrapped recursively until an instance of ErrorClass is found, at which time it is returned. If the provided error is not an instance of WrappedError, the error will be returned if it is an instance of ErrorClass.

In either scenario, if an instance of ErrorClass is not found then null is returned.

class CustomError extends Error {
  constructor() {
    super('A meaningful error message');
    this.name = 'CustomError';
  }
}

const customError = new CustomError();
const wrapped = Errors.wrap('Additional error message', customError);
const wrappedTwice = Errors.wrap(
  'Yet another error message',
  wrappedCustomError
);

Errors.unwrap(wrapped, CustomError); // customError
Errors.unwrap(wrappedTwice, CustomError); // customError
Errors.unwrap(customError, CustomError); // customError

Errors.unwrap(wrapped, TypeError); // null
Errors.unwrap(customError, TypeError); // null