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 latest0.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:
-
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 });
-
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 fromname
- a string literal type for the error nameorigin
- a string literal type for the application/service which originated this errorclassification
- strongly typed Type/Subtype systemhttpStatus
- a numeric HTTP status code that can (and in some cases must) be setunderlying
- 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.