yerror

It helps to know why you got an error.

A robust Error subclass with error codes, typed debug values, and recursive stack traces using native Error.cause.

Usage

First, require me where you could throw errors:

import YError from 'yerror';

Then, emit errors with a bonus: parameters!

function doSomething(pay, action) {
  if (parseInt(pay, 10) !== pay) {
    throw new YError('E_BAD_PAY', [pay, action]);
  }
}

doSomething('nuts', 'code');

// YError: E_BAD_PAY (["nuts", "code"])
//   at doSomething (/home/nfroidure/nfroidure/yerror/test.js:5:11)
//   at Object.<anonymous> (/home/nfroidure/nfroidure/yerror/test.js:9:1)
//   (...)

You don't have to use constant like error messages, we use this convention mainly for i18n reasons.

Also, you could want to wrap errors and keep a valuable stack trace:

function doSomethingAsync(pay, action) {
  return new Promise(function (resolve, reject) {
    try {
      doSomething(pay, action);
      resolve();
    } catch (err) {
      reject(YError.bump(err));
    }
  });
}

doSomethingAsync('nuts', 'code').catch(function (err) {
  console.log(err.stack);
});

// YError: E_BAD_PAY (nuts, code)
//    at doSomething (/home/nfroidure/nfroidure/yerror/test.js:5:11)
//    (...)
// Caused by: YError: E_BAD_TRANSACTION (pay)
//    at Function.YError.wrap (/home/nfroidure/nfroidure/yerror/src/index.js:41:12)
//    at /home/nfroidure/nfroidure/yerror/test.js:16:21
//    at doSomethingAsync (/home/nfroidure/nfroidure/yerror/test.js:11:11)
//    (...)

Global Error Registry

You can now get full autocompletion and type-safety for your error codes and their debug data.

import { YError } from 'yerror';

declare module 'yerror' {
  interface YErrorRegistry {
    E_USER_NOT_FOUND: [userId: string];
  }
}

// TypeScript will now enforce the correct arguments:
throw new YError('E_USER_NOT_FOUND', ['123']);

// Users of you own code will then be able to cast errors
try {
  getUser('123');
} catch (err) {
  if (hasYErrorCode(err, 'E_USER_NOT_FOUND')) {
    console.log(err.debug[0]);
  }
}

API

Classes

Functions

YError ⇐ Error

A YError class able to contain some debug and print better stack traces

Kind: global class
Extends: Error

• YError ⇐ Error
  • new YError([errorCode], [debug], options)
  • .wrap(err, [errorCode], [debug]) ⇒ YError
  • .cast(err, [errorCode], [debug]) ⇒ YError
  • .bump(err, [errorCode], [debug]) ⇒ YError

new YError([errorCode], [debug], options)

Creates a new YError with an error code and some debug as debug values.

| Param | Type | Default | Description | | --- | --- | --- | --- | | [errorCode] | string | "'E_UNEXPECTED'" | The error code corresponding to the actual error | | [debug] | any | | Some additional debugging values The error options | | options | Object | | The error options |

YError.wrap(err, [errorCode], [debug]) ⇒ YError

Wraps any error and output a YError with an error code and some debug as debug values.

Kind: static method of YError
Returns: YError - The wrapped error

| Param | Type | Default | Description | | --- | --- | --- | --- | | err | Error | | The error to wrap | | [errorCode] | string | "'E_UNEXPECTED'" | The error code corresponding to the actual error | | [debug] | any | | Some additional debugging values |

YError.cast(err, [errorCode], [debug]) ⇒ YError

Return a YError as is or wraps any other error and output a YError with a code and some debug as debug values.

Kind: static method of YError
Returns: YError - The wrapped error

| Param | Type | Default | Description | | --- | --- | --- | --- | | err | Error | | The error to cast | | [errorCode] | string | "'E_UNEXPECTED'" | The error code corresponding to the actual error | | [debug] | any | | Some additional debugging values |

YError.bump(err, [errorCode], [debug]) ⇒ YError

Same than YError.wrap() but preserves the code and the debug values of the error if it is already an instance of the YError constructor.

Kind: static method of YError
Returns: YError - The wrapped error

| Param | Type | Default | Description | | --- | --- | --- | --- | | err | Error | | The error to bump | | [errorCode] | string | "'E_UNEXPECTED'" | The error code corresponding to the actual error | | [debug] | any | | Some additional debugging values |

printStackTrace(err) ⇒ string

Allow to print a stack from anything (especially caught errors that may or may not contain errors 🤷).

Kind: global function
Returns: string - The stack trace if any

| Param | Type | Description | | --- | --- | --- | | err | Error | The error to print |

hasYErrorCode(err, code) ⇒ boolean

Allow to check a YError code and cast the error.

Kind: global function
Returns: boolean - The result

| Param | Type | Description | | --- | --- | --- | | err | Error | The error to cast | | code | Error | The code to check |

pickYErrorWithCode(err, code) ⇒ boolean

Allow to check all errors for a YError code and return the casted the error.

Kind: global function
Returns: boolean - The result

| Param | Type | Description | | --- | --- | --- | | err | Error | The error to cast | | code | Error | The code to check |

Authors

• Nicolas Froidure (formerly at SimpliField)

License

MIT