There is unfortunately no "official" way to achieve this basic functionality in Javascript. I'll share the three most common solutions I've seen in different packages, and how to implement them in modern Javascript (es6+), along with some of their pros and cons.
1. Subclass the Error class
Subclassing an instance of "Error" has become much easier in es6. Just do the following:
class FileNotFoundException extends Error {
constructor(message) {
super(message);
// Not required, but makes uncaught error messages nicer.
this.name = 'FileNotFoundException';
}
}
Complete example:
class FileNotFoundException extends Error {
constructor(message) {
super(message);
// Not required, but makes uncaught error messages nicer.
this.name = 'FileNotFoundException';
}
}
// Example usage
function readFile(path) {
throw new FileNotFoundException(`The file ${path} was not found`);
}
try {
readFile('./example.txt');
} catch (err) {
if (err instanceof FileNotFoundException) {
// Handle the custom exception
console.log(`Could not find the file. Reason: ${err.message}`);
} else {
// Rethrow it - we don't know how to handle it
// The stacktrace won't be changed, because
// that information is attached to the error
// object when it's first constructed.
throw err;
}
}
If you don't like setting this.name to a hard-coded string, you can instead set it to this.constructor.name, which will give the name of your class. This has the advantage that any subclasses of your custom exception wouldn't need to also update this.name, as this.constructor.name will be the name of the subclass.
Subclassed exceptions have the advantage that they can provide better editor support (such as autocomplete) compared to some of the alternative solutions. You can easily add custom behavior to a specific exception type, such as additional functions, alternative constructor parameters, etc. It also tends to be easier to support typescript when providing custom behavior or data.
There's a lot of discussion about how to properly subclass Error out there. For example, the above solution might not work if you're using a transpiler. Some recommend using the platform-specific captureStackTrace() if it's available (I didn't notice any difference in the error when I used it though - maybe it's not as relevant anymore 🤷♂️). To read up more, see this MDN page and This Stackoverflow answer.
Many browser APIs go this route and throw custom exceptions (as can be seen here)
Note that this solution may not work if you are transpiling down to to es5. In Babel version 6, instanceof simply wouldn't work with subclassed builtins. In version 7, they still warn that subclassing built-ins may lead to unexpected issues. It's just not possible to 100% accurately transpile code like this, so all transpilers have to choose between different trade-offs.
2. Adding a distinguishing property to the Error
The idea is really simple. Create your error, add an extra property such as "code" to your error, then throw it.
const error = new Error(`The file ${path} was not found`);
error.code = 'NotFound';
throw error;
Complete example:
function readFile(path) {
const error = new Error(`The file ${path} was not found`);
error.code = 'NotFound';
throw error;
}
try {
readFile('./example.txt');
} catch (err) {
if (err.code === 'NotFound') {
console.log(`Could not find the file. Reason: ${err.message}`);
} else {
throw err;
}
}
You can, of course, make a helper function to remove some of the boilerplate and ensure consistency.
This solution has the advantage that you don't need to export a list of all possible exceptions your package may throw. You can imagine how awkward that can get if, for example, your package had been using a NotFound exception to indicate that a particular function was unable to find the intended resource. You want to add an addUserToGroup() function that ideally would throw a UserNotFound or GroupNotFound exception depending on which resource wasn't found. With subclassed exceptions, you'll be left with a sticky decision to make (Should you add two new error classes, just for this function? Or maybe add an optional property on the NotFoundError class providing more info about what wasn't found?). With codes on an error object, you can just do it.
This is the route node's fs module takes to exceptions. If you're trying to read a non-existent file, it'll throw an instance of Error with some additional properties, such as code, which it'll set to "ENOENT" for that specific exception.
3. Return your exception.
Who says you have to throw them? In some scenarios, it might make the most sense to just return what went wrong.
function readFile(path) {
if (itFailed()) {
return { exCode: 'NotFound' };
} else {
return { data: 'Contents of file' };
}
}
When dealing with a lot of exceptions, a solution such as this could make the most sense. It's simple to do, and can help self-document which functions give which exceptions, which makes for much more robust code. The downside is that it can add a lot of bloat to your code.
complete example:
function readFile(path) {
if (Math.random() > 0.5) {
return { exCode: 'NotFound' };
} else {
return { data: 'Contents of file' };
}
}
function main() {
const { data, exCode } = readFile('./example.txt');
if (exCode === 'NotFound') {
console.log('Could not find the file.');
return;
} else if (exCode) {
// We don't know how to handle this exCode, so throw an error
throw new Error(`Unhandled exception when reading file: ${exCode}`);
}
console.log(`Contents of file: ${data}`);
}
main();
A non-solution
Some of these solutions feel like a lot of work. It's tempting to just throw an object literal, e.g. throw { code: 'NotFound' }. Don't do this! Stack trace information gets attached to error objects. If one of these object literals ever slips through and becomes an uncaught exception, you won't have a stacktrace to know where or how it happened. Debugging in general will be much more difficult. Some browsers may show a stacktrace in the console if one of these objects go uncaught, but this is just an optional convinience they provide, not all platforms provide this convinience, and it's not always accurate, e.g. if this object got caught and rethrown the browser will likely give the wrong stacktrace.
Upcoming solutions
The JavaScript committee is working on a couple of proposals that will make exception handling much nicer to work with. The details of how these proposals will work are still in flux, and are actively being discussed, so I won't dive into too much detail until things settle down, but here's a rough taste of things to come:
The biggest change to come will be the Pattern Matching proposal, which is intended to be a better "switch", among other things. With it, you'd easily be able to match against different styles of errors with simple syntax.
Here's a taste of what this might look like:
try {
...
} catch (err) {
match (err) {
// Checks if `err` is an instance of UserNotFound
when (${UserNotFound}): console.error('The user was not found!');
// Checks if it has a correct code property set to "ENOENT"
when ({ code: 'ENOENT' }): console.error('...');
// Handles everything else
else: throw err;
}
}
Pattern matching with the return-your-exception route grants you the ability to do exception handling in a style very similar to how it's often done in functional languages. The only thing missing would be the "either" type, but a TypeScript union type fulfills a very similar role.
const result = match (divide(x, y)) {
// (Please refer to the proposal for a more in-depth
// explanation of this syntax)
when ({ type: 'RESULT', value }): value + 1
when ({ type: 'DivideByZero' }): -1
}
There's also some very early discussion about bringing this pattern-matching syntax right into the try-catch syntax, to allow you to do something akin to this:
try {
doSomething();
} CatchPatten (UserNotFoundError & err) {
console.error('The user was not found! ' + err);
} CatchPatten ({ type: 'ENOENT' }) {
console.error('File not found!');
} catch (err) {
throw err;
}
Update
For those who needed a way to self-document which functions threw which exceptions, along with ways to ensure this self-documentation stayed honest, I previously recommended in this answer a small package I threw together to help you keep track of which exceptions a given function might throw. While this package does the job, now days I would simply recommend using TypeScript with the "return your exception" route for maximum exception safety. With the help of a TypeScript union type, you can easily document which exceptions a particular function will return, and TypeScript can help you keep this documentation honest, giving you type-errors when things go wrong.
