koffi 2.3.17 → 2.3.19

package/CHANGELOG.md

@@ -4,6 +4,18 @@
 
 ### Koffi 2.3
 
+#### Koffi 2.3.19
+
+**Main fixes:**
+
+- Actually allow non-ambiguous [string] values for `void *` arguments
+
+#### Koffi 2.3.18
+
+**Main fixes:**
+
+- Fix possible crash on exit caused by unregistered callbacks
+
 #### Koffi 2.3.17
 
 **Main changes:**

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "koffi",
-    "version": "2.3.17",
-    "stable": "2.3.17",
+    "version": "2.3.19",
+    "stable": "2.3.19",
     "description": "Fast and simple C FFI (foreign function interface) for Node.js",
     "keywords": [
         "foreign",

package/src/koffi/src/call.cc

@@ -77,8 +77,10 @@ void CallData::Dispose()
             int16_t idx = used_trampolines[i];
             TrampolineInfo *trampoline = &shared.trampolines[idx];
 
+            RG_ASSERT(trampoline->instance == instance);
             RG_ASSERT(!trampoline->func.IsEmpty());
 
+            trampoline->instance = nullptr;
             trampoline->func.Reset();
             trampoline->recv.Reset();
 
@@ -979,19 +981,24 @@ bool CallData::PushPointer(Napi::Value value, const TypeInfo *type, int directio
             Size out_max_len = -1;
 
             if (value.IsArray()) {
-                if (RG_UNLIKELY(!type->ref.type->size)) {
-                    ThrowError<Napi::TypeError>(env, "Cannot pass %1 value to void *, use koffi.as()",
-                                                type->ref.type != instance->void_type ? "opaque" : "ambiguous");
-                    return false;
-                }
-
                 Napi::Array array = value.As<Napi::Array>();
                 Size len = PushIndirectString(array, type->ref.type, &ptr);
 
                 if (len >= 0) {
+                    if (RG_UNLIKELY(!type->ref.type->size && type->ref.type != instance->void_type)) {
+                        ThrowError<Napi::TypeError>(env, "Cannot pass [string] value to %1", type->name);
+                        return false;
+                    }
+
                     out_kind = (type->ref.type->size == 2) ? OutArgument::Kind::String16 : OutArgument::Kind::String;
                     out_max_len = len;
                 } else {
+                    if (RG_UNLIKELY(!type->ref.type->size)) {
+                        ThrowError<Napi::TypeError>(env, "Cannot pass %1 value to %2, use koffi.as()",
+                                                    type->ref.type != instance->void_type ? "opaque" : "ambiguous", type->name);
+                        return false;
+                    }
+
                     Size len = (Size)array.Length();
                     Size size = len * type->ref.type->size;
 
@@ -1024,8 +1031,8 @@ bool CallData::PushPointer(Napi::Value value, const TypeInfo *type, int directio
             } else if (RG_LIKELY(type->ref.type->primitive == PrimitiveKind::Record ||
                                  type->ref.type->primitive == PrimitiveKind::Union)) {
                 if (RG_UNLIKELY(!type->ref.type->size)) {
-                    ThrowError<Napi::TypeError>(env, "Cannot pass %1 value to void *, use koffi.as()",
-                                                type->ref.type != instance->void_type ? "opaque" : "ambiguous");
+                    ThrowError<Napi::TypeError>(env, "Cannot pass %1 value to %2, use koffi.as()",
+                                                type->ref.type != instance->void_type ? "opaque" : "ambiguous", type->name);
                     return false;
                 }
 
@@ -1225,6 +1232,7 @@ void *CallData::ReserveTrampoline(const FunctionInfo *proto, Napi::Function func
 
     TrampolineInfo *trampoline = &shared.trampolines[idx];
 
+    trampoline->instance = instance;
     trampoline->proto = proto;
     trampoline->func.Reset(func, 1);
     trampoline->recv.Reset();

package/src/koffi/src/ffi.cc

@@ -1654,6 +1654,7 @@ static Napi::Value RegisterCallback(const Napi::CallbackInfo &info)
 
     TrampolineInfo *trampoline = &shared.trampolines[idx];
 
+    trampoline->instance = instance;
     trampoline->proto = type->ref.proto;
     trampoline->func.Reset(func, 1);
     if (!IsNullOrUndefined(recv)) {
@@ -1954,10 +1955,8 @@ InstanceData::~InstanceData()
         for (int16_t idx = 0; idx < MaxTrampolines; idx++) {
             TrampolineInfo *trampoline = &shared.trampolines[idx];
 
-            if (trampoline->func.IsEmpty())
-                continue;
-
-            if (trampoline->func.Env().GetInstanceData<InstanceData>() == this) {
+            if (trampoline->instance == this) {
+                trampoline->instance = nullptr;
                 trampoline->func.Reset();
                 trampoline->recv.Reset();
             }

package/src/koffi/src/ffi.hh

@@ -305,6 +305,8 @@ RG_STATIC_ASSERT(DefaultMaxAsyncCalls >= DefaultResidentAsyncPools);
 RG_STATIC_ASSERT(MaxAsyncCalls >= DefaultMaxAsyncCalls);
 
 struct TrampolineInfo {
+    InstanceData *instance;
+
     const FunctionInfo *proto;
     Napi::FunctionReference func;
     Napi::Reference<Napi::Value> recv;

package/vendor/node-addon-api/CHANGELOG.md

@@ -1,5 +1,46 @@
 # node-addon-api Changelog
 
+## 2023-04-20 Version 6.1.0, @NickNaso
+
+### Notable changes
+
+#### API
+
+- Enforce type checks on `Napi::Value::As()`.
+- Added `Napi::TypeTaggable` class.
+- Defined `NAPI_HAS_THREADS` to make TSFN available on Emscripten.
+- Defined `NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED` and
+`Napi::Buffer::NewOrCopy()` to handle the support for external buffers.
+
+#### TEST
+
+- Added tests for `Napi::Reference<T>` class.
+- Added tests for copy/move semantics.
+- Added tests for `Napi::RangeError` and `Napi::TypeError` class.
+- Fixed inconsistent failure executing test suite.
+- Added tests for `Napi::ObjectReference<T>` class.
+- Added tests for `Napi::ObjectWrap<T>` class.
+
+### Documentation
+
+- Added documentation for `Napi::TypeTaggable`.
+- Some minor fixes all over the documentation.
+
+### Commits
+
+- \[[`5adb896782`](https://github.com/nodejs/node-addon-api/commit/5adb896782)] - **src**: enforce type checks on Napi::Value::As() (#1281) (Chengzhong Wu)
+- \[[`d9faac7ec2`](https://github.com/nodejs/node-addon-api/commit/d9faac7ec2)] - Fix exits/exists typo in docs for Env::AddCleanupHook() (#1306) (Mathias Stearn)
+- \[[`164459ca03`](https://github.com/nodejs/node-addon-api/commit/164459ca03)] - **doc**: update class hierarchy for TypeTaggable (Gabriel Schulhof) [#1303](https://github.com/nodejs/node-addon-api/pull/1303)
+- \[[`d01304437c`](https://github.com/nodejs/node-addon-api/commit/d01304437c)] - **src**: interject class TypeTaggable (Gabriel Schulhof) [#1298](https://github.com/nodejs/node-addon-api/pull/1298)
+- \[[`d4942ccd4f`](https://github.com/nodejs/node-addon-api/commit/d4942ccd4f)] - **test**: Complete test coverage for Reference\<T> class (#1277) (Jack)
+- \[[`a8ad7e7a7b`](https://github.com/nodejs/node-addon-api/commit/a8ad7e7a7b)] - **test**: Add tests for copy/move semantics (JckXia) [#1295](https://github.com/nodejs/node-addon-api/pull/1295)
+- \[[`e484327344`](https://github.com/nodejs/node-addon-api/commit/e484327344)] - Add test coverage for typed and range err (#1280) (Jack)
+- \[[`ebc7858593`](https://github.com/nodejs/node-addon-api/commit/ebc7858593)] - **test**: Update wait with a condition (#1297) (Jack)
+- \[[`0b53d885f5`](https://github.com/nodejs/node-addon-api/commit/0b53d885f5)] - **src**: define `NAPI_HAS_THREADS` (toyobayashi) [#1283](https://github.com/nodejs/node-addon-api/pull/1283)
+- \[[`464610babf`](https://github.com/nodejs/node-addon-api/commit/464610babf)] - **test**: complete objectRefs tests (JckXia) [#1274](https://github.com/nodejs/node-addon-api/pull/1274)
+- \[[`b16c762a19`](https://github.com/nodejs/node-addon-api/commit/b16c762a19)] - **src**: handle no support for external buffers (legendecas) [#1273](https://github.com/nodejs/node-addon-api/pull/1273)
+- \[[`61b8e28720`](https://github.com/nodejs/node-addon-api/commit/61b8e28720)] - **test**: Add test covg for obj wrap (#1269) (Jack)
+
 ## 2023-02-03 Version 6.0.0, @NickNaso
 
 ### Notable changes

package/vendor/node-addon-api/README.md

@@ -70,7 +70,7 @@ and node-addon-api.
 - **[Contributors](#contributors)**
 - **[License](#license)**
 
-## **Current version: 6.0.0**
+## **Current version: 6.1.0**
 
 (See [CHANGELOG.md](CHANGELOG.md) for complete Changelog)
 

package/vendor/node-addon-api/doc/array_buffer.md

@@ -23,6 +23,9 @@ Returns a new `Napi::ArrayBuffer` instance.
 
 ### New
 
+> When `NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED` is defined, this method is not available.
+> See [External Buffer][] for more information.
+
 Wraps the provided external data into a new `Napi::ArrayBuffer` instance.
 
 The `Napi::ArrayBuffer` instance does not assume ownership for the data and
@@ -48,6 +51,9 @@ Returns a new `Napi::ArrayBuffer` instance.
 
 ### New
 
+> When `NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED` is defined, this method is not available.
+> See [External Buffer][] for more information.
+
 Wraps the provided external data into a new `Napi::ArrayBuffer` instance.
 
 The `Napi::ArrayBuffer` instance does not assume ownership for the data and
@@ -74,6 +80,9 @@ Returns a new `Napi::ArrayBuffer` instance.
 
 ### New
 
+> When `NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED` is defined, this method is not available.
+> See [External Buffer][] for more information.
+
 Wraps the provided external data into a new `Napi::ArrayBuffer` instance.
 
 The `Napi::ArrayBuffer` instance does not assume ownership for the data and expects it
@@ -153,3 +162,4 @@ bool Napi::ArrayBuffer::IsDetached() const;
 Returns `true` if this `ArrayBuffer` has been detached.
 
 [`Napi::Object`]: ./object.md
+[External Buffer]: ./external_buffer.md

package/vendor/node-addon-api/doc/buffer.md

@@ -22,6 +22,9 @@ Returns a new `Napi::Buffer` object.
 
 ### New
 
+> When `NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED` is defined, this method is not available.
+> See [External Buffer][] for more information.
+
 Wraps the provided external data into a new `Napi::Buffer` object.
 
 The `Napi::Buffer` object does not assume ownership for the data and expects it to be
@@ -47,6 +50,9 @@ Returns a new `Napi::Buffer` object.
 
 ### New
 
+> When `NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED` is defined, this method is not available.
+> See [External Buffer][] for more information.
+
 Wraps the provided external data into a new `Napi::Buffer` object.
 
 The `Napi::Buffer` object does not assume ownership for the data and expects it
@@ -72,6 +78,9 @@ Returns a new `Napi::Buffer` object.
 
 ### New
 
+> When `NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED` is defined, this method is not available.
+> See [External Buffer][] for more information.
+
 Wraps the provided external data into a new `Napi::Buffer` object.
 
 The `Napi::Buffer` object does not assume ownership for the data and expects it to be
@@ -98,6 +107,93 @@ static Napi::Buffer<T> Napi::Buffer::New(napi_env env,
 
 Returns a new `Napi::Buffer` object.
 
+### NewOrCopy
+
+Wraps the provided external data into a new `Napi::Buffer` object. When the
+[external buffer][] is not supported, allocates a new `Napi::Buffer` object and
+copies the provided external data into it.
+
+The `Napi::Buffer` object does not assume ownership for the data and expects it to be
+valid for the lifetime of the object. Since the `Napi::Buffer` is subject to garbage
+collection this overload is only suitable for data which is static and never
+needs to be freed.
+
+This factory method will not provide the caller with an opportunity to free the
+data when the `Napi::Buffer` gets garbage-collected. If you need to free the
+data retained by the `Napi::Buffer` object please use other variants of the
+`Napi::Buffer::New` factory method that accept `Napi::Finalizer`, which is a
+function that will be invoked when the `Napi::Buffer` object has been
+destroyed.
+
+```cpp
+static Napi::Buffer<T> Napi::Buffer::NewOrCopy(napi_env env, T* data, size_t length);
+```
+
+- `[in] env`: The environment in which to create the `Napi::Buffer` object.
+- `[in] data`: The pointer to the external data to expose.
+- `[in] length`: The number of `T` elements in the external data.
+
+Returns a new `Napi::Buffer` object.
+
+### NewOrCopy
+
+Wraps the provided external data into a new `Napi::Buffer` object. When the
+[external buffer][] is not supported, allocates a new `Napi::Buffer` object and
+copies the provided external data into it and the `finalizeCallback` is invoked
+immediately.
+
+The `Napi::Buffer` object does not assume ownership for the data and expects it
+to be valid for the lifetime of the object. The data can only be freed once the
+`finalizeCallback` is invoked to indicate that the `Napi::Buffer` has been released.
+
+```cpp
+template <typename Finalizer>
+static Napi::Buffer<T> Napi::Buffer::NewOrCopy(napi_env env,
+                                               T* data,
+                                               size_t length,
+                                               Finalizer finalizeCallback);
+```
+
+- `[in] env`: The environment in which to create the `Napi::Buffer` object.
+- `[in] data`: The pointer to the external data to expose.
+- `[in] length`: The number of `T` elements in the external data.
+- `[in] finalizeCallback`: The function to be called when the `Napi::Buffer` is
+  destroyed. It must implement `operator()`, accept an Napi::Env, a `T*` (which is the
+  external data pointer), and return `void`.
+
+Returns a new `Napi::Buffer` object.
+
+### NewOrCopy
+
+Wraps the provided external data into a new `Napi::Buffer` object. When the
+[external buffer][] is not supported, allocates a new `Napi::Buffer` object and
+copies the provided external data into it and the `finalizeCallback` is invoked
+immediately.
+
+The `Napi::Buffer` object does not assume ownership for the data and expects it to be
+valid for the lifetime of the object. The data can only be freed once the
+`finalizeCallback` is invoked to indicate that the `Napi::Buffer` has been released.
+
+```cpp
+template <typename Finalizer, typename Hint>
+static Napi::Buffer<T> Napi::Buffer::NewOrCopy(napi_env env,
+                                               T* data,
+                                               size_t length,
+                                               Finalizer finalizeCallback,
+                                               Hint* finalizeHint);
+```
+
+- `[in] env`: The environment in which to create the `Napi::Buffer` object.
+- `[in] data`: The pointer to the external data to expose.
+- `[in] length`: The number of `T` elements in the external data.
+- `[in] finalizeCallback`: The function to be called when the `Napi::Buffer` is
+  destroyed. It must implement `operator()`, accept an Napi::Env, a `T*` (which is the
+  external data pointer) and `Hint*`, and return `void`.
+- `[in] finalizeHint`: The hint to be passed as the second parameter of the
+  finalize callback.
+
+Returns a new `Napi::Buffer` object.
+
 ### Copy
 
 Allocates a new `Napi::Buffer` object and copies the provided external data into it.
@@ -148,3 +244,4 @@ size_t Napi::Buffer::Length() const;
 Returns the number of `T` elements in the external data.
 
 [`Napi::Uint8Array`]: ./typed_array_of.md
+[External Buffer]: ./external_buffer.md

package/vendor/node-addon-api/doc/env.md

@@ -138,7 +138,7 @@ template <typename Hook>
 CleanupHook<Hook> AddCleanupHook(Hook hook);
 ```
 
-- `[in] hook`: A function to call when the environment exists. Accepts a
+- `[in] hook`: A function to call when the environment exits. Accepts a
   function of the form `void ()`.
 
 Registers `hook` as a function to be run once the current Node.js environment
@@ -156,7 +156,7 @@ template <typename Hook, typename Arg>
 CleanupHook<Hook, Arg> AddCleanupHook(Hook hook, Arg* arg);
 ```
 
-- `[in] hook`: A function to call when the environment exists. Accepts a
+- `[in] hook`: A function to call when the environment exits. Accepts a
   function of the form `void (Arg* arg)`.
 - `[in] arg`: A pointer to data that will be passed as the argument to `hook`.
 

package/vendor/node-addon-api/doc/external.md

@@ -1,6 +1,6 @@
 # External (template)
 
-Class `Napi::External<T>` inherits from class [`Napi::Value`][].
+Class `Napi::External<T>` inherits from class [`Napi::TypeTaggable`][].
 
 The `Napi::External` template class implements the ability to create a `Napi::Value` object with arbitrary C++ data. It is the user's responsibility to manage the memory for the arbitrary C++ data.
 
@@ -67,4 +67,4 @@ T* Napi::External::Data() const;
 
 Returns a pointer to the arbitrary C++ data held by the `Napi::External` object.
 
-[`Napi::Value`]: ./value.md
+[`Napi::TypeTaggable`]: ./type_taggable.md

package/vendor/node-addon-api/doc/external_buffer.md

@@ -0,0 +1,18 @@
+# External Buffer
+
+**Some runtimes other than Node.js have dropped support for external buffers**.
+On runtimes other than Node.js, node-api methods may return
+`napi_no_external_buffers_allowed` to indicate that external
+buffers are not supported. One such runtime is Electron as
+described in this issue
+[electron/issues/35801](https://github.com/electron/electron/issues/35801).
+
+In order to maintain broadest compatibility with all runtimes,
+you may define `NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED` in your addon before
+includes for the node-api and node-addon-api headers. Doing so will hide the
+functions that create external buffers. This will ensure a compilation error
+occurs if you accidentally use one of these methods.
+
+In node-addon-api, the `Napi::Buffer::NewOrCopy` provides a convenient way to
+create an external buffer, or allocate a new buffer and copy the data when the
+external buffer is not supported.

package/vendor/node-addon-api/doc/hierarchy.md

@@ -20,7 +20,7 @@
 | [`Napi::Env`][] |  |
 | [`Napi::Error`][] | [`Napi::ObjectReference`][], [`std::exception`][] |
 | [`Napi::EscapableHandleScope`][] |  |
-| [`Napi::External`][] | [`Napi::Value`][] |
+| [`Napi::External`][] | [`Napi::TypeTaggable`][] |
 | [`Napi::Function`][] | [`Napi::Object`][] |
 | [`Napi::FunctionReference`][] | [`Napi::Reference<Napi::Function>`][] |
 | [`Napi::HandleScope`][] |  |
@@ -28,7 +28,7 @@
 | [`Napi::MemoryManagement`][] |  |
 | [`Napi::Name`][] | [`Napi::Value`][] |
 | [`Napi::Number`][] | [`Napi::Value`][] |
-| [`Napi::Object`][] | [`Napi::Value`][] |
+| [`Napi::Object`][] | [`Napi::TypeTaggable`][] |
 | [`Napi::ObjectReference`][] | [`Napi::Reference<Napi::Object>`][] |
 | [`Napi::ObjectWrap`][] | [`Napi::InstanceWrap`][], [`Napi::Reference<Napi::Object>`][] |
 | [`Napi::Promise`][] | [`Napi::Object`][] |
@@ -38,6 +38,7 @@
 | [`Napi::String`][] | [`Napi::Name`][] |
 | [`Napi::Symbol`][] | [`Napi::Name`][] |
 | [`Napi::ThreadSafeFunction`][] |  |
+| [`Napi::TypeTaggable`][] | [`Napi::Value][] |
 | [`Napi::TypeError`][] | [`Napi::Error`][] |
 | [`Napi::TypedArray`][] | [`Napi::Object`][] |
 | [`Napi::TypedArrayOf`][] | [`Napi::TypedArray`][] |
@@ -83,6 +84,7 @@
 [`Napi::Symbol`]: ./symbol.md
 [`Napi::ThreadSafeFunction`]: ./threadsafe_function.md
 [`Napi::TypeError`]: ./type_error.md
+[`Napi::TypeTaggable`]: ./type_taggable.md
 [`Napi::TypedArray`]: ./typed_array.md
 [`Napi::TypedArrayOf`]: ./typed_array_of.md
 [`Napi::Uint8Array`]: ./typed_array_of.md

package/vendor/node-addon-api/doc/object.md

@@ -1,6 +1,6 @@
 # Object
 
-Class `Napi::Object` inherits from class [`Napi::Value`][].
+Class `Napi::Object` inherits from class [`Napi::TypeTaggable`][].
 
 The `Napi::Object` class corresponds to a JavaScript object. It is extended by the following node-addon-api classes that you may use when working with more specific types:
 
@@ -241,33 +241,6 @@ from being added to it and marking all existing properties as non-configurable.
 Values of present properties can still be changed as long as they are
 writable.
 
-### TypeTag()
-
-```cpp
-void Napi::Object::TypeTag(const napi_type_tag* type_tag) const;
-```
-
-- `[in] type_tag`: The tag with which this object is to be marked.
-
-The `Napi::Object::TypeTag()` method associates the value of the `type_tag`
-pointer with this JavaScript object. `Napi::Object::CheckTypeTag()` can then be
-used to compare the tag that was attached to this object with one owned by the
-addon to ensure that this object has the right type.
-
-### CheckTypeTag()
-
-```cpp
-bool Napi::Object::CheckTypeTag(const napi_type_tag* type_tag) const;
-```
-
-- `[in] type_tag`: The tag with which to compare any tag found on this object.
-
-The `Napi::Object::CheckTypeTag()` method compares the pointer given as
-`type_tag` with any that can be found on this JavaScript object. If no tag is
-found on this object or, if a tag is found but it does not match `type_tag`,
-then the return value is `false`. If a tag is found and it matches `type_tag`,
-then the return value is `true`.
-
 ### operator\[\]()
 
 ```cpp
@@ -434,5 +407,5 @@ void Increment(const CallbackInfo& info) {
 }
 ```
 
-[`Napi::Value`]: ./value.md
+[`Napi::TypeTaggable`]: ./type_taggable.md
 [`Napi::Value::From`]: ./value.md#from

package/vendor/node-addon-api/doc/type_taggable.md

@@ -0,0 +1,40 @@
+# TypeTaggable
+
+Class `Napi::TypeTaggable` inherits from class [`Napi::Value`][].
+
+The `Napi::TypeTaggable` class is the base class for [`Napi::Object`][] and
+[`Napi::External`][]. It adds type-tagging capabilities to both. It is an
+abstract-only base class.
+
+### TypeTag()
+
+```cpp
+void Napi::TypeTaggable::TypeTag(const napi_type_tag* type_tag) const;
+```
+
+- `[in] type_tag`: The tag with which this object or external is to be marked.
+
+The `Napi::TypeTaggable::TypeTag()` method associates the value of the
+`type_tag` pointer with this JavaScript object or external.
+`Napi::TypeTaggable::CheckTypeTag()` can then be used to compare the tag that
+was attached with one owned by the add-on to ensure that this object or external
+has the right type.
+
+### CheckTypeTag()
+
+```cpp
+bool Napi::TypeTaggable::CheckTypeTag(const napi_type_tag* type_tag) const;
+```
+
+- `[in] type_tag`: The tag with which to compare any tag found on this object or
+  external.
+
+The `Napi::TypeTaggable::CheckTypeTag()` method compares the pointer given as
+`type_tag` with any that can be found on this JavaScript object or external. If
+no tag is found or if a tag is found but it does not match `type_tag`, then the
+return value is `false`. If a tag is found and it matches `type_tag`, then the
+return value is `true`.
+
+[`Napi::Value`]: ./value.md
+[`Napi::Object`]: ./object.md
+[`Napi::External`]: ./external.md

package/vendor/node-addon-api/doc/value.md

@@ -78,7 +78,13 @@ Casts to another type of `Napi::Value`, when the actual type is known or
 assumed.
 
 This conversion does not coerce the type. Calling any methods inappropriate for
-the actual value type will throw `Napi::Error`.
+the actual value type will throw `Napi::Error`. When C++ exceptions are
+disabled, the thrown error will not be reflected before control returns to
+JavaScript.
+
+In order to enforce expected type, use `Napi::Value::Is*()` methods to check
+the type before calling `Napi::Value::As()`, or compile with definition
+`NODE_ADDON_API_ENABLE_TYPE_CHECK_ON_AS` to enforce type checks.
 
 ### Env