Throwing errors in JavaScript

When you start writing your own JavaScript functions, it's a good idea to handle errors properly, especially if you expose your functions as an API to the outside world. Today, I'll show you how to throw errors in JavaScript using the throw statement.

As the MDN Web Docs explain, the throw statement throws a user-defined exception. This is different from an exception that the JavaScript interpreter throws internally. You can throw any expression you want.

Let's look at a trivial function that adds two numbers together and returns the result:

function sum(num1, num2) {
  return num1 + num2;
}

We want to throw an error if either of the arguments isn't a number.

Throwing a simple expression

To begin, we can throw a simple string:

function sum(num1, num2) {
  const type1 = typeof num1, type2 = typeof num2;

  if (type1 !== 'number' || type2 !== 'number') {
    throw `Expected two numbers; got ${type1} and ${type2}.`;
  }

  return num1 + num2;
}

This function uses the typeof operator to get the types of the two arguments. It saves them to the constants type1 and type2 respectively.

It then uses a conditional statement to check the types. If either of them isn't a number, it throws an error saying that it expected two numbers, but received something else.

For example, if we try to call the function with a number and a string, it throws an error:

sum(1, '2'); // Uncaught Expected two numbers; got number and string.

If we call the function with two numbers, it works as expected:

sum(1, 2); // 3

This is a good start, but we can do better.

Throwing an Error object

To improve the developer experience, we can construct an Error object and throw that instead:

function sum(num1, num2) {
  const type1 = typeof num1, type2 = typeof num2;

  if (type1 !== 'number' || type2 !== 'number') {
    throw new Error(`Expected two numbers; got ${type1} and ${type2}.`);
  }

  return num1 + num2;
}

The main benefit of this approach is that it provides a helpful stack trace in the console, making it easier for you to debug:

Uncaught Error: Expected two numbers; got number and string.
    sum file:///Users/kieranbarker/Desktop/tmp.js:5
    <anonymous> file:///Users/kieranbarker/Desktop/tmp.js:11

This is certainly an improvement, but we can still do better!

Throwing a TypeError object

We can make one final improvement by throwing a more specific Error object. There are several error types built into JavaScript, but we're going to throw a TypeError. This is perfect; its intended use is when a variable or parameter is not of a valid type!

function sum(num1, num2) {
  const type1 = typeof num1, type2 = typeof num2;

  if (type1 !== 'number' || type2 !== 'number') {
    throw new TypeError(`Expected two numbers; got ${type1} and ${type2}.`);
  }

  return num1 + num2;
}

The stack trace is pretty much the same, except it specifies that we have an uncaught TypeError, rather than just a generic Error:

Uncaught TypeError: Expected two numbers; got number and string.
    sum file:///Users/kieranbarker/Desktop/tmp.js:5
    <anonymous> file:///Users/kieranbarker/Desktop/tmp.js:11

This improves the developer experience even further by giving us a hint as to what we did wrong. Hopefully this will allow us to fix the problem more quickly.