node-addon-api 8.5.0 → 8.7.0

package/README.md

@@ -19,7 +19,7 @@ and exception handling semantics with low overhead.
 API references are available in the [doc](doc/README.md) directory.
 
 <!-- x-release-please-start-version -->
-## Current version: 8.5.0
+## Current version: 8.7.0
 <!-- x-release-please-end -->
 
 (See [CHANGELOG.md](CHANGELOG.md) for complete Changelog)

package/common.gypi

@@ -5,7 +5,7 @@
   },
   'conditions': [
     ['NAPI_VERSION!=""', { 'defines': ['NAPI_VERSION=<@(NAPI_VERSION)'] } ],
-    ['NAPI_VERSION==2147483647', { 'defines': ['NAPI_EXPERIMENTAL'] } ],
+    ['NAPI_VERSION==2147483647', { 'defines': ['NAPI_EXPERIMENTAL', 'NODE_API_EXPERIMENTAL_NO_WARNING'] } ],
     ['disable_deprecated=="true"', {
       'defines': ['NODE_ADDON_API_DISABLE_DEPRECATED']
     }],

package/napi-inl.h

@@ -21,6 +21,12 @@
 #include <type_traits>
 #include <utility>
 
+#if defined(__clang__) || defined(__GNUC__)
+#define NAPI_NO_SANITIZE_VPTR __attribute__((no_sanitize("vptr")))
+#else
+#define NAPI_NO_SANITIZE_VPTR
+#endif
+
 namespace Napi {
 
 #ifdef NAPI_CPP_CUSTOM_NAMESPACE
@@ -934,6 +940,19 @@ inline bool Value::IsExternal() const {
   return Type() == napi_external;
 }
 
+#ifdef NODE_API_EXPERIMENTAL_HAS_SHAREDARRAYBUFFER
+inline bool Value::IsSharedArrayBuffer() const {
+  if (IsEmpty()) {
+    return false;
+  }
+
+  bool result;
+  napi_status status = node_api_is_sharedarraybuffer(_env, _value, &result);
+  NAPI_THROW_IF_FAILED(_env, status, false);
+  return result;
+}
+#endif
+
 template <typename T>
 inline T Value::As() const {
 #ifdef NODE_ADDON_API_ENABLE_TYPE_CHECK_ON_AS
@@ -1180,6 +1199,13 @@ inline Date Date::New(napi_env env, double val) {
   return Date(env, value);
 }
 
+inline Date Date::New(napi_env env, std::chrono::system_clock::time_point tp) {
+  using namespace std::chrono;
+  auto ms = static_cast<double>(
+      duration_cast<milliseconds>(tp.time_since_epoch()).count());
+  return Date::New(env, ms);
+}
+
 inline void Date::CheckCast(napi_env env, napi_value value) {
   NAPI_CHECK(value != nullptr, "Date::CheckCast", "empty value");
 
@@ -1947,6 +1973,19 @@ inline MaybeOrValue<bool> Object::Seal() const {
 }
 #endif  // NAPI_VERSION >= 8
 
+inline MaybeOrValue<Object> Object::GetPrototype() const {
+  napi_value result;
+  napi_status status = napi_get_prototype(_env, _value, &result);
+  NAPI_RETURN_OR_THROW_IF_FAILED(_env, status, Object(_env, result), Object);
+}
+
+#ifdef NODE_API_EXPERIMENTAL_HAS_SET_PROTOTYPE
+inline MaybeOrValue<bool> Object::SetPrototype(const Object& value) const {
+  napi_status status = node_api_set_prototype(_env, _value, value);
+  NAPI_RETURN_OR_THROW_IF_FAILED(_env, status, status == napi_ok, bool);
+}
+#endif
+
 ////////////////////////////////////////////////////////////////////////////////
 // External class
 ////////////////////////////////////////////////////////////////////////////////
@@ -2068,6 +2107,55 @@ inline uint32_t Array::Length() const {
   return result;
 }
 
+#ifdef NODE_API_EXPERIMENTAL_HAS_SHAREDARRAYBUFFER
+////////////////////////////////////////////////////////////////////////////////
+// SharedArrayBuffer class
+////////////////////////////////////////////////////////////////////////////////
+
+inline SharedArrayBuffer::SharedArrayBuffer() : Object() {}
+
+inline SharedArrayBuffer::SharedArrayBuffer(napi_env env, napi_value value)
+    : Object(env, value) {}
+
+inline void SharedArrayBuffer::CheckCast(napi_env env, napi_value value) {
+  NAPI_CHECK(value != nullptr, "SharedArrayBuffer::CheckCast", "empty value");
+
+  bool result;
+  napi_status status = node_api_is_sharedarraybuffer(env, value, &result);
+  NAPI_CHECK(status == napi_ok,
+             "SharedArrayBuffer::CheckCast",
+             "node_api_is_sharedarraybuffer failed");
+  NAPI_CHECK(
+      result, "SharedArrayBuffer::CheckCast", "value is not sharedarraybuffer");
+}
+
+inline SharedArrayBuffer SharedArrayBuffer::New(napi_env env,
+                                                size_t byteLength) {
+  napi_value value;
+  void* data;
+  napi_status status =
+      node_api_create_sharedarraybuffer(env, byteLength, &data, &value);
+  NAPI_THROW_IF_FAILED(env, status, SharedArrayBuffer());
+
+  return SharedArrayBuffer(env, value);
+}
+
+inline void* SharedArrayBuffer::Data() {
+  void* data;
+  napi_status status = napi_get_arraybuffer_info(_env, _value, &data, nullptr);
+  NAPI_THROW_IF_FAILED(_env, status, nullptr);
+  return data;
+}
+
+inline size_t SharedArrayBuffer::ByteLength() {
+  size_t length;
+  napi_status status =
+      napi_get_arraybuffer_info(_env, _value, nullptr, &length);
+  NAPI_THROW_IF_FAILED(_env, status, 0);
+  return length;
+}
+#endif  // NODE_API_EXPERIMENTAL_HAS_SHAREDARRAYBUFFER
+
 ////////////////////////////////////////////////////////////////////////////////
 // ArrayBuffer class
 ////////////////////////////////////////////////////////////////////////////////
@@ -2221,6 +2309,39 @@ inline DataView DataView::New(napi_env env,
   return DataView(env, value);
 }
 
+#ifdef NODE_API_EXPERIMENTAL_HAS_SHAREDARRAYBUFFER
+inline DataView DataView::New(napi_env env,
+                              Napi::SharedArrayBuffer arrayBuffer) {
+  return New(env, arrayBuffer, 0, arrayBuffer.ByteLength());
+}
+
+inline DataView DataView::New(napi_env env,
+                              Napi::SharedArrayBuffer arrayBuffer,
+                              size_t byteOffset) {
+  if (byteOffset > arrayBuffer.ByteLength()) {
+    NAPI_THROW(RangeError::New(
+                   env, "Start offset is outside the bounds of the buffer"),
+               DataView());
+  }
+  return New(
+      env, arrayBuffer, byteOffset, arrayBuffer.ByteLength() - byteOffset);
+}
+
+inline DataView DataView::New(napi_env env,
+                              Napi::SharedArrayBuffer arrayBuffer,
+                              size_t byteOffset,
+                              size_t byteLength) {
+  if (byteOffset + byteLength > arrayBuffer.ByteLength()) {
+    NAPI_THROW(RangeError::New(env, "Invalid DataView length"), DataView());
+  }
+  napi_value value;
+  napi_status status =
+      napi_create_dataview(env, byteLength, arrayBuffer, byteOffset, &value);
+  NAPI_THROW_IF_FAILED(env, status, DataView());
+  return DataView(env, value);
+}
+#endif  // NODE_API_EXPERIMENTAL_HAS_SHAREDARRAYBUFFER
+
 inline void DataView::CheckCast(napi_env env, napi_value value) {
   NAPI_CHECK(value != nullptr, "DataView::CheckCast", "empty value");
 
@@ -2244,6 +2365,10 @@ inline DataView::DataView(napi_env env, napi_value value) : Object(env, value) {
 }
 
 inline Napi::ArrayBuffer DataView::ArrayBuffer() const {
+  return Buffer().As<Napi::ArrayBuffer>();
+}
+
+inline Napi::Value DataView::Buffer() const {
   napi_value arrayBuffer;
   napi_status status = napi_get_dataview_info(_env,
                                               _value /* dataView */,
@@ -2251,8 +2376,8 @@ inline Napi::ArrayBuffer DataView::ArrayBuffer() const {
                                               nullptr /* data */,
                                               &arrayBuffer /* arrayBuffer */,
                                               nullptr /* byteOffset */);
-  NAPI_THROW_IF_FAILED(_env, status, Napi::ArrayBuffer());
-  return Napi::ArrayBuffer(_env, arrayBuffer);
+  NAPI_THROW_IF_FAILED(_env, status, Napi::Value());
+  return Napi::Value(_env, arrayBuffer);
 }
 
 inline size_t DataView::ByteOffset() const {
@@ -3741,8 +3866,8 @@ inline MaybeOrValue<bool> ObjectReference::Set(const std::string& utf8name,
   return Value().Set(utf8name, value);
 }
 
-inline MaybeOrValue<bool> ObjectReference::Set(const std::string& utf8name,
-                                               std::string& utf8value) const {
+inline MaybeOrValue<bool> ObjectReference::Set(
+    const std::string& utf8name, const std::string& utf8value) const {
   HandleScope scope(_env);
   return Value().Set(utf8name, utf8value);
 }
@@ -4717,7 +4842,8 @@ inline napi_value InstanceWrap<T>::WrappedMethod(
 ////////////////////////////////////////////////////////////////////////////////
 
 template <typename T>
-inline ObjectWrap<T>::ObjectWrap(const Napi::CallbackInfo& callbackInfo) {
+inline NAPI_NO_SANITIZE_VPTR ObjectWrap<T>::ObjectWrap(
+    const Napi::CallbackInfo& callbackInfo) {
   napi_env env = callbackInfo.Env();
   napi_value wrapper = callbackInfo.This();
   napi_status status;
@@ -4731,7 +4857,7 @@ inline ObjectWrap<T>::ObjectWrap(const Napi::CallbackInfo& callbackInfo) {
 }
 
 template <typename T>
-inline ObjectWrap<T>::~ObjectWrap() {
+inline NAPI_NO_SANITIZE_VPTR ObjectWrap<T>::~ObjectWrap() {
   // If the JS object still exists at this point, remove the finalizer added
   // through `napi_wrap()`.
   if (!IsEmpty() && !_finalized) {
@@ -4744,8 +4870,12 @@ inline ObjectWrap<T>::~ObjectWrap() {
   }
 }
 
+// with RTTI turned on, modern compilers check to see if virtual function
+// pointers are stripped of RTTI by void casts. this is intrinsic to how Unwrap
+// works, so we inject a compiler pragma to turn off that check just for the
+// affected methods. this compiler check is on by default in Android NDK 29.
 template <typename T>
-inline T* ObjectWrap<T>::Unwrap(Object wrapper) {
+inline NAPI_NO_SANITIZE_VPTR T* ObjectWrap<T>::Unwrap(Object wrapper) {
   void* unwrapped;
   napi_status status = napi_unwrap(wrapper.Env(), wrapper, &unwrapped);
   NAPI_THROW_IF_FAILED(wrapper.Env(), status, nullptr);
@@ -7030,4 +7160,6 @@ inline void BasicEnv::PostFinalizer(FinalizerType finalizeCallback,
 
 }  // namespace Napi
 
+#undef NAPI_NO_SANITIZE_VPTR
+
 #endif  // SRC_NAPI_INL_H_

package/napi.h

@@ -17,6 +17,7 @@
 #if NAPI_HAS_THREADS
 #include <mutex>
 #endif  // NAPI_HAS_THREADS
+#include <chrono>
 #include <string>
 #include <vector>
 
@@ -359,10 +360,10 @@ class BasicEnv {
   // ... occurs when comparing foo.Env() == bar.Env() or foo.Env() == nullptr
   bool operator==(const BasicEnv& other) const {
     return _env == other._env;
-  };
+  }
   bool operator==(std::nullptr_t /*other*/) const {
     return _env == nullptr;
-  };
+  }
 
 #if NAPI_VERSION > 2
   template <typename Hook, typename Arg = void>
@@ -543,6 +544,9 @@ class Value {
   bool IsDataView() const;    ///< Tests if a value is a JavaScript data view.
   bool IsBuffer() const;      ///< Tests if a value is a Node buffer.
   bool IsExternal() const;  ///< Tests if a value is a pointer to external data.
+#ifdef NODE_API_EXPERIMENTAL_HAS_SHAREDARRAYBUFFER
+  bool IsSharedArrayBuffer() const;
+#endif
 
   /// Casts to another type of `Napi::Value`, when the actual type is known or
   /// assumed.
@@ -682,6 +686,12 @@ class Date : public Value {
                   double value   ///< Number value
   );
 
+  /// Creates a new Date value from a std::chrono::system_clock::time_point.
+  static Date New(
+      napi_env env,  ///< Node-API environment
+      std::chrono::system_clock::time_point time_point  ///< Time point value
+  );
+
   static void CheckCast(napi_env env, napi_value value);
 
   Date();  ///< Creates a new _empty_ Date instance.
@@ -1115,6 +1125,12 @@ class Object : public TypeTaggable {
   /// https://tc39.es/ecma262/#sec-proxy-object-internal-methods-and-internal-slots-getprototypeof
   MaybeOrValue<bool> Seal() const;
 #endif  // NAPI_VERSION >= 8
+
+  MaybeOrValue<Object> GetPrototype() const;
+
+#ifdef NODE_API_EXPERIMENTAL_HAS_SET_PROTOTYPE
+  MaybeOrValue<bool> SetPrototype(const Object& value) const;
+#endif
 };
 
 template <typename T>
@@ -1202,6 +1218,21 @@ class Object::iterator {
 };
 #endif  // NODE_ADDON_API_CPP_EXCEPTIONS
 
+#ifdef NODE_API_EXPERIMENTAL_HAS_SHAREDARRAYBUFFER
+class SharedArrayBuffer : public Object {
+ public:
+  SharedArrayBuffer();
+  SharedArrayBuffer(napi_env env, napi_value value);
+
+  static SharedArrayBuffer New(napi_env env, size_t byteLength);
+
+  static void CheckCast(napi_env env, napi_value value);
+
+  void* Data();
+  size_t ByteLength();
+};
+#endif
+
 /// A JavaScript array buffer value.
 class ArrayBuffer : public Object {
  public:
@@ -1432,13 +1463,37 @@ class DataView : public Object {
                       size_t byteOffset,
                       size_t byteLength);
 
+#ifdef NODE_API_EXPERIMENTAL_HAS_SHAREDARRAYBUFFER
+  static DataView New(napi_env env, Napi::SharedArrayBuffer arrayBuffer);
+  static DataView New(napi_env env,
+                      Napi::SharedArrayBuffer arrayBuffer,
+                      size_t byteOffset);
+  static DataView New(napi_env env,
+                      Napi::SharedArrayBuffer arrayBuffer,
+                      size_t byteOffset,
+                      size_t byteLength);
+#endif
+
   static void CheckCast(napi_env env, napi_value value);
 
   DataView();  ///< Creates a new _empty_ DataView instance.
   DataView(napi_env env,
            napi_value value);  ///< Wraps a Node-API value primitive.
 
-  Napi::ArrayBuffer ArrayBuffer() const;  ///< Gets the backing array buffer.
+  // Gets the backing `ArrayBuffer`.
+  //
+  // If this `DataView` is not backed by an `ArrayBuffer`, this method will
+  // terminate the process with a fatal error when using
+  // `NODE_ADDON_API_ENABLE_TYPE_CHECK_ON_AS` or exhibit undefined behavior
+  // otherwise. Use `Buffer()` instead to get the backing buffer without
+  // assuming its type.
+  Napi::ArrayBuffer ArrayBuffer() const;
+
+  // Gets the backing buffer (an `ArrayBuffer` or `SharedArrayBuffer`).
+  //
+  // Use `IsArrayBuffer()` or `IsSharedArrayBuffer()` to check the type of the
+  // backing buffer prior to casting with `As<T>()`.
+  Napi::Value Buffer() const;
   size_t ByteOffset()
       const;  ///< Gets the offset into the buffer where the array starts.
   size_t ByteLength() const;  ///< Gets the length of the array in bytes.
@@ -1715,7 +1770,7 @@ class ObjectReference : public Reference<Object> {
   MaybeOrValue<bool> Set(const std::string& utf8name, napi_value value) const;
   MaybeOrValue<bool> Set(const std::string& utf8name, Napi::Value value) const;
   MaybeOrValue<bool> Set(const std::string& utf8name,
-                         std::string& utf8value) const;
+                         const std::string& utf8value) const;
   MaybeOrValue<bool> Set(const std::string& utf8name, bool boolValue) const;
   MaybeOrValue<bool> Set(const std::string& utf8name, double numberValue) const;
 
@@ -3108,8 +3163,8 @@ class AsyncProgressWorkerBase : public AsyncWorker {
 
     AsyncProgressWorkerBase* asyncprogressworker() {
       return _asyncprogressworker;
-    };
-    DataType* data() { return _data; };
+    }
+    DataType* data() { return _data; }
 
    private:
     AsyncProgressWorkerBase* _asyncprogressworker;

package/package.json

@@ -472,7 +472,7 @@
     "lint:fix": "eslint --fix && node tools/clang-format --fix"
   },
   "pre-commit": "lint",
-  "version": "8.5.0",
+  "version": "8.7.0",
   "support": true,
   "engines": {
     "node": "^18 || ^20 || >= 21"