Studio Fail

🚨 Fail with an Error object and a conventional code property.

Usage (async / await)

const{ failure,INVALID}=require('@studio/fail');functionread(filename,callback){if(!filename){// Easily fail with a conventional error:throwfailure('Missing filename',INVALID);}// ...}

Usage (callback)

constfs=require('fs');const{ fail, then,INVALID}=require('@studio/fail');functionread(filename,callback){if(!filename){// Easily fail with a conventional error:fail(callback,'Missing filename',INVALID);return;}// Wrap callbacks with and error handling, guarding from multiple invocations:fs.readFile(filename,'utf8',then(callback,(content)=>{// Non-undefined return value is passed to callback:returncontent.trim();}));}

Conventions

Errors should always have a code property with an uppercase error code. To simplify error handling, use the provided fail utility function and code constants.

Error codes follow these conventions:

• Fatal errors should have an error code starting with E_. This is the asynchronous equivalent to throw. The provided message is not supposed to be shown to the user.
• Other error codes have no prefix and are not considered fatal, for example a validation error. The provided message may be shown to the user.
• If no code property is provided, it defaults to E_FAILED.

The provided error codes can be handled generically. You may define additional error codes as needed.

Install

❯ npm i @studio/fail

API

• failure(message[, cause][, code[, properties]]): Create an Error with the given message and cause and code and properties. If no code is provided it defaults to E_FAILED. The cause must be an error object.
• fail(callback, message[, cause][, code[, properties]]): Creates a failure and invoked the given callback with it.
• isFatal(error): Whether the given error has a code property the starts with E_ or has no code property.
• then(callback, next): Create a callback function that invokes callback(err) if an error occurred and next(result) on success. Throws if the function is invoked more than once with error code E_FAILED and err as the cause. If next returns a non-undefined value, the callback is invoked with that result.

Error codes

• E_FAILED: Fatal error.
• INVALID: Invalid or missing argument or parameter.
• FORBIDDEN: User is not allowed to access.
• NOT_FOUND: Resource does not exist.

Examples

Throwing errors:

const{ failure,INVALID}=require('@studio/fail');// Fail with a message:throwfailure('Oups!');// The previous is the same as this:throwfailure('Oups!',E_FAILED);// Fail with `code` INVALID:throwfailure('Oups!',INVALID);// Fail with a `cause`:constcause=newError();throwfailure('Oups!',cause);// Fail with a `cause` and `code` INVALID:throwfailure('Oups!',cause,INVALID);// Fail with `properties` and `code` INVALID:throwfailure('Oups!',INVALID,{some: 42});

Invoking callbacks with errors:

const{ fail,FORBIDDEN}=require('@studio/fail');fail(callback,'Oups!',FORBIDDEN);

Related modules

• 👻 Studio Log is a tiny ndjson logger that is code and cause aware.
• 📦 Studio Changes is used to create the changelog for this module.

License

MIT

Made with ❤️ on 🌍