brilliant-errors

Brilliant Errors

Note: the version 6.x of this library had moved to newer dependencies wand the callsites library only support the ESM module system these days but because we were packaging up in both ESM and CJS it was causing errors. I had intended to keep CJS around for a while longer but in most cases you really should be preferring ESM anyway. In version 7.x and going forward we are only publishing version ESM. If you still need CJS you can use the latest 0.5.x release.

The base errors you get from Javascript leave a lot to be desired and this library attempts to provide a consistent way to provide solid meta information on errors raised in Typescript/Javascript projects.

This library provides two configurators for errors:

1. createError - the default error type provides an Error with strongly typed classification but does not require an HTTP status code for errors (you are allowed to add the HTTP status code)

   type ErrorType = "not-allowed" | "unexpected" | "missing-info";
   const MyError = createError<ErrorType>(e => e.name("MyError").origin("my-app"));
   
   // instantiation
   const error = new MyError("I've fallen and I can't get up", "unexpected/old-age");
   
   // static initializers for edge cases
   const error = MyError.withUnderlying(err, "No really, I can't get up", "unexpected/fer-fucks-sake");
   const error = MyError.withHttpCode(500, "Not worth repeating", "unexpected/web-fall");
   
   // options hash (means you can get to everything if you need it)
   const error = new MyError("Just stop it", "not-allowed/shit-happens", { underlying: err, httpStatus: 500 });
   

2. createHttpError - an HTTP error produces errors which are guarenteed to have an HTTP status code as part of their payload but they also follow the Type/Subtype conventions in the base error.

   const HttpError = createHttpError<ErrorType, SubType>(e => 
       e.name("HttpError")
        .origin("my-network-app")
        .defaultType("missing-info")
   );
   
   // instantiotion
   const error = new HttpError(403, "couldn't find member's id", "no-membership-id");
   

All errors have the following attributes:

• kind - a string literal type for the error family the error originates from
• name - a string literal type for the error name
• origin - a string literal type for the application/service which originated this error
• classification - strongly typed Type/Subtype system
• httpStatus - a numeric HTTP status code that can (and in some cases must) be set
• underlying - all errors can store an underlying error and the wrapper error requires it

They also have brilliant .toJSON() and message outputs which shine above the plain old vanilla JS error.

For a repo which wants to use these configurators, you will create a file in your repo for the new error and then configure it something like this:

src/error/MyError.ts:

export default MyError = createLibraryError('MyError', { ... });

All options in the configurators are strongly typed which includes full documentatory information so rather than try to repeat that here we emplore you to use the built-in Typescript documentation within your code editor of choice.