This chapter describes how JavaScript’s exception handling works. It begins with a general explanation of what exception handling is.

What Is Exception Handling?

In exception handling, you often group statements that are tightly coupled.

Let’s look at code without exception handling:

What is the best way to react to an error in at (2)? Clearly, the statement (1) should not be executed anymore. But we wouldn’t want to abort extractAllEntries(), either. Instead, it is enough to skip the current file and continue with the next one. To do that, we add exception handling to the previous code:

function extractAllEntries(fileNames) {
    var allEntries = new Entries();
    fileNames.forEach(function (fileName) {
        try {
            var entry = extractOneEntry(fileName);
            allEntries.add(entry);
        } catch (exception) {  // (2)
            errorLog.log('Error in '+fileName, exception);
        }
    });
}
function extractOneEntry(fileName) {
    var file = openFile(fileName);
    ...
}
function openFile(fileName) {
    if (!exists(fileName)) {
        throw new Error(+fileName); // (1)
    }
    ...
}

There are two aspects to exception handling:

• If there is a problem that can’t be handled meaningfully where it occurs, throw an exception.
• Find a place where errors can be handled: catch exceptions.

At (1), the following constructs are active:

    processFile()
        extractAllEntries(...)
            fileNames.forEach(...)
                function (fileName) { ... }
                    try { ... } catch (exception) { ... }
                        extractOneEntry(...)
                            openFile(...)

The throw statement at (1) walks up that tree and leaves all constructs until it encounters an active try statement. It then invokes that statement’s catch block and passes it the exception value.

Exception handling in JavaScript works like in most programming languages: a try statement groups statements and lets you intercept exceptions in those statements.

throw «value»;

Any JavaScript value can be thrown. For simplicity’s sake, many JavaScript programs just throw strings:

// Don't do this
if (somethingBadHappened) {
    throw 'Something bad happened';
}

Don’t do this. JavaScript has special constructorsError Constructors). Use those or subclass them (see ). Their advantage is that JavaScript automatically adds a stack trace (on most engines) and that they have room for additional context-specific properties. The simplest solution is to use the built-in constructor Error():

    throw new Error('Something bad happened');
}

The syntax of try-catch-finally looks as follows. try is mandatory, and at least one of catch and finally must be there, too:

try {
    «try_statements»
}
⟦catch («exceptionVar») {
   «catch_statements»
}⟧
⟦finally {
   «finally_statements»
}⟧

Here’s how it works:

• catch catches any exception that is thrown in try_statements, whether directly or in functions they invoke. Tip: If you want to distinguish between different kinds of exceptions, you can use the constructor property to switch over the exceptions’ constructors (see ).
• finally is always executed, no matter what happens in try_statements (or in functions they invoke). Use it for clean-up operations that should always be performed, no matter what happens in try_statements:

If one of the try_statements is a return, then the finally block is executed afterward (immediately before leaving the function or method; see the examples that follow).

Any value can be thrown:

function throwIt(exception) {
    try {
        throw exception
    } catch (e) {
        console.log('Caught: '+e);
    }
}

Here is the interaction:

> throwIt(3);
Caught: 3
> throwIt('hello');
Caught: hello
> throwIt(new Error('An error happened'));
Caught: Error: An error happened

finally is always executed:

function throwsError() {
    throw new Error('Sorry...');
}
function cleansUp() {
    try {
        throwsError();
    } finally {
        console.log('Performing clean-up');
    }
}

> cleansUp();
Performing clean-up
Error: Sorry...

finally is executed after

function idLog(x) {
    try {
        console.log(x);
        return 'result';
        console.log("FINALLY");
    }
}

Here is the interaction:

> idLog('arg')
arg
FINALLY
'result'

The return value is queued before executing finally:

By the time statement (1) is executed, the value of count has already been queued for returning:

> countUp()
0
> count
1

Error Constructors

ECMAScript standardizes the following error constructors. The descriptions are quoted from the ECMAScript 5 specification:

• Error is a generic constructor for errors. All other error constructors mentioned here are subconstructors.
• EvalError “is not currently used within this specification. This object remains for compatibility with previous editions of this specification.”
• RangeError “indicates a numeric value has exceeded the allowable range.” For example:

> new Array(-1)
RangeError: Invalid array length

• ReferenceError “indicates that an invalid reference value has been detected.” Usually, this is an unknown variable. For example:

> unknownVariable
ReferenceError: unknownVariable is not defined

• SyntaxError “indicates that a parsing error has occurred” either while parsing normal code or while parsing the argument of eval(). For example:

> 3..1
SyntaxError: Unexpected number '.1'. Parse error.
> eval('5 +')
SyntaxError: Unexpected end of script

• TypeError “indicates the actual type of an operand is different than the expected type.” For example:

> undefined.foo
TypeError: Cannot read property 'foo' of undefined

• URIError “indicates that one of the global URI handling functions was used in a way that is incompatible with its definition.” For example:

> decodeURI('%2')
URIError: URI malformed

Here are the properties of

• message
• The error message.
• name
• The name of the error.
• stack
• A stack trace. This is nonstandard, but is available on many platforms—for example, Chrome, Node.js, and Firefox.

The usual sources of

• Data: What values do variables have?
• Execution: In what line did the exception happen, and what function calls were active?

You can put some of the first item (data) into either the message or the properties of an exception object. The second item (execution) is supported on many JavaScript engines via stack traces, snapshots of the call stack when the exception objects were created. The following example prints a stack trace:

> catchIt()
Error
    at throwIt (~/examples/throwcatch.js:9:11)
    at catchIt (~/examples/throwcatch.js:3:9)
    at repl:1:5

Implementing Your Own Error Constructor

If you wantChapter 28 to learn how to do it.