errorish

errorish

For those times you have an error-ish but what you really want is an Error

If you come to find it useful, consider starring the project and/or following its author to show your ❤️

Install

npm install errorish

Use cases

There are essentially three use cases for errorish:

• You need to make sure any object is actually an error, as expected.
• You need to make sure an Error has a message, name, and stack properties.
• You want to catch errors and throw a different Error:
  • with a different message and specific data that might be made public,
  • while preserving information about the original exception that caused your program to fail,
  • on different levels of the call stack, but keeping only the first one of its kind throwed.

Documentation

These are all of errorish's functions -see docs:

• ensure ensures any is an Error, otherwise creating one -optionally, it can also have a normalization step, which is enabled by default.
• normalize ensures an Error has a message, name, and stack properties -filling them if they're not defined.
• rejects parses a help string and returns an object with options, aliases, arguments, and descriptions.
• throws parses a help string and returns an object with options, aliases, arguments, and descriptions.

Options can be passed directly to these functions, though they will be merged in all cases with the defaults -you can use scope.set to set these.

Additionally, you might want to create particular scopes with a different set of default options depending on your use case.

Usage

Ensuring any is an error -otherwise create it

Return an error from any error-ish

import { ensure } from 'errorish';

ensure(Error('Foo bar')); // Error: Foo bar

ensure('Foo bar'); // Errorish: Foo bar
ensure({ message: 'Foo bar' }); // Errorish: Foo bar

// As this is a number, it will use the default message
ensure(10); // Errorish: An error occurred
// We can also allow numbers -or any other type- to be stringified
ensure(10, { allow: ['string', 'number'] }); // Errorish: 10

// Errors will always preserve the original source
ensure(10).source; // 10

// Additionally, we can pass some data to errors
ensure(10, null, { foo: 'bar' }).data; // { foo: 'bar' }

Throw or reject with an error-ish

throws and rejects run ensure over your error-ish and throw or reject with it -these are just convenience functions over ensure:

import { rejects } from 'errorish';

Promise.reject(10).catch(rejects) // Reject<Errorish: An error occurred>

// Options for `rejects` and `throws` also take a `case` field which,
// if false, will make them to have a void response
Promise.reject(10).catch(err => rejects(err, { case: false })); // Resolve<undefined>

Normalizing errors

Normalization is performed by default by ensure, but it can also be run independently:

import { normalize } from 'errorish';

normalize(Error()); // Error: An error occurred
normalize(Error(), { message: 'Foo bar' }); // Error: Foo bar

Catching and throwing errors to be made public

import { Errorish, scope } from 'errorish';

// As we might want to preserve the defaults for the root scope,
// we'll create a new scope we'll name `ish`.
// For that scope, we'll set Errorish as the class errors
// will be ensured against, so even when an actual `Error` is passed,
// if not an `Errorish`, a new one will be created.
const ish = scope.set('ish', { Error: Errorish, allow: [] });

function authorize() {
  throw Error(`Error with details I'd rather not expose`);
}

function example() {
  try {
    authorize();
  } catch (err) {
    // As an `Error` is not an instance of `Errorish`, one will be
    // created with message `Server failed running your example`
    // and data `{ code: 500 }`
    throw ish.ensure(
      err,
      { message: `Authorization for example failed` },
      { code: 401 }
    );
  }
}

function server() {
  try {
    example();
  } catch (err) {
    // As example already throwed an `Errorish`, the same one will be
    // preserved, ignoring the more general-purpose message and code
    throw ish.ensure(err, { message: 'Server failed' }, { code: 500 });
  }
}

try {
  server();
} catch (e) {
  console.log(e.message); // Authorization for example failed
  console.log(e.data); // { code: 401 }
  console.log(e.source); // Error: Error with details I'd rather not expose
}

Changelog

0.1.0 (2019-04-18)

Bug Fixes

• ensure, normalize: prevents defaults object mutation when options are passed (3a66c02)

Features

• adds ensure (ac388c0)
• adds entry point exports (bec50c0)
• ensure: implements stringify (8518cd5)
• adds Errorish (d68f3a7)
• adds normalize (bc68ac6)
• ensure: implements trunk (e8bd0da)
• ensure: improves typings (f44a664)
• scope: adds defaults (f9770a4)
• scope: adds scope getter/setter (69431e3)
• scope: scope.set returns the scope (f1976a8)
• adds rejects (109cd57)
• adds throws (d8cef9e)
• throws,rejects: evaluates options.case when property exists; improves typings (5cb7d9c)
• types: adds ICoreOptions (84d4529)