7.0 KiB
Error handling
Error handling represents one of the most important considerations when implementing a Node.js native add-on. When an error occurs in your C++ code you have to handle and dispatch it correctly. node-addon-api uses return values and JavaScript exceptions for error handling. You can choose return values or exception handling based on the mechanism that works best for your add-on.
The Napi::Error is a persistent reference (for more info see: Napi::ObjectReference)
to a JavaScript error object. Use of this class depends on whether C++
exceptions are enabled at compile time.
If C++ exceptions are enabled (for more info see: Setup), then the
Napi::Error class extends std::exception and enables integrated
error-handling for C++ exceptions and JavaScript exceptions.
The following sections explain the approach for each case:
In most cases when an error occurs, the addon should do whatever clean is possible and then return to JavaScript so that they error can be propagated. In less frequent cases the addon may be able to recover from the error, clear the error and then continue.
Handling Errors With C++ Exceptions
When C++ exceptions are enabled try/catch can be used to catch exceptions thrown from calls to JavaScript and then they can either be handled or rethrown before returning from a native method.
If a node-addon-api call fails without executing any JavaScript code (for example due to
an invalid argument), then node-addon-api automatically converts and throws
the error as a C++ exception of type Napi::Error.
If a JavaScript function called by C++ code via node-addon-api throws a JavaScript
exception, then node-addon-api automatically converts and throws it as a C++
exception of type Napi:Error on return from the JavaScript code to the native
method.
If a C++ exception of type Napi::Error escapes from a N-API C++ callback, then
the N-API wrapper automatically converts and throws it as a JavaScript exception.
On return from a native method, node-addon-api will automatically convert a pending C++ exception to a JavaScript exception.
When C++ exceptions are enabled try/catch can be used to catch exceptions thrown from calls to JavaScript and then they can either be handled or rethrown before returning from a native method.
Examples with C++ exceptions enabled
Throwing a C++ exception
Env env = ...
throw Napi::Error::New(env, "Example exception");
// other C++ statements
// ...
The statements following the throw statement will not be executed. The exception
will bubble up as a C++ exception of type Napi::Error, until it is either caught
while still in C++, or else automatically propagated as a JavaScript exception
when returning to JavaScript.
Propagating a N-API C++ exception
Napi::Function jsFunctionThatThrows = someObj.As<Napi::Function>();
Napi::Value result = jsFunctionThatThrows({ arg1, arg2 });
// other C++ statements
// ...
The C++ statements following the call to the JavaScript function will not be
executed. The exception will bubble up as a C++ exception of type Napi::Error,
until it is either caught while still in C++, or else automatically propagated as
a JavaScript exception when returning to JavaScript.
Handling a N-API C++ exception
Napi::Function jsFunctionThatThrows = someObj.As<Napi::Function>();
Napi::Value result;
try {
result = jsFunctionThatThrows({ arg1, arg2 });
} catch (const Error& e) {
cerr << "Caught JavaScript exception: " + e.what();
}
Since the exception was caught here, it will not be propagated as a JavaScript exception.
Handling Errors Without C++ Exceptions
If C++ exceptions are disabled (for more info see: Setup), then the
Napi::Error class does not extend std::exception. This means that any calls to
node-addon-api function do not throw a C++ exceptions. Instead, it raises
pending JavaScript exceptions and returns an empty Napi::Value.
The calling code should check env.IsExceptionPending() before attempting to use a
returned value, and may use methods on the Napi::Env class
to check for, get, and clear a pending JavaScript exception (for more info see: Env).
If the pending exception is not cleared, it will be thrown when the native code
returns to JavaScript.
Examples with C++ exceptions disabled
Throwing a JS exception
Napi::Env env = ...
Napi::Error::New(env, "Example exception").ThrowAsJavaScriptException();
return;
After throwing a JavaScript exception, the code should generally return immediately from the native callback, after performing any necessary cleanup.
Propagating a N-API JS exception
Napi::Env env = ...
Napi::Function jsFunctionThatThrows = someObj.As<Napi::Function>();
Napi::Value result = jsFunctionThatThrows({ arg1, arg2 });
if (env.IsExceptionPending()) {
Error e = env.GetAndClearPendingException();
return e.Value();
}
If env.IsExceptionPending() returns true a JavaScript exception is pending. To let the exception propagate, the code should generally return immediately from the native callback, after performing any necessary cleanup.
Handling a N-API JS exception
Napi::Env env = ...
Napi::Function jsFunctionThatThrows = someObj.As<Napi::Function>();
Napi::Value result = jsFunctionThatThrows({ arg1, arg2 });
if (env.IsExceptionPending()) {
Napi::Error e = env.GetAndClearPendingException();
cerr << "Caught JavaScript exception: " + e.Message();
}
Since the exception was cleared here, it will not be propagated as a JavaScript exception after the native callback returns.
Calling N-API directly from a node-addon-api addon
node-addon-api provides macros for throwing errors in response to non-OK
napi_status results when calling N-API
functions from within a native addon. These macros are defined differently
depending on whether C++ exceptions are enabled or not, but are available for
use in either case.
NAPI_THROW(e, ...)
This macro accepts a Napi::Error, throws it, and returns the value given as
the last parameter. If C++ exceptions are enabled (by defining
NAPI_CPP_EXCEPTIONS during the build), the return value will be ignored.
NAPI_THROW_IF_FAILED(env, status, ...)
This macro accepts a Napi::Env and a napi_status. It constructs an error
from the napi_status, throws it, and returns the value given as the last
parameter. If C++ exceptions are enabled (by defining NAPI_CPP_EXCEPTIONS
during the build), the return value will be ignored.
NAPI_THROW_IF_FAILED_VOID(env, status)
This macro accepts a Napi::Env and a napi_status. It constructs an error
from the napi_status, throws it, and returns.
NAPI_FATAL_IF_FAILED(status, location, message)
This macro accepts a napi_status, a C string indicating the location where the
error occurred, and a second C string for the message to display.