koffi 2.3.16 → 2.3.18

package/CHANGELOG.md

@@ -4,6 +4,19 @@
 
 ### Koffi 2.3
 
+#### Koffi 2.3.18
+
+**Main fixes:**
+
+- Fix possible crash on exit caused by unregistered callbacks
+
+#### Koffi 2.3.17
+
+**Main changes:**
+
+- Allow strings for input `void *`, `int8_t *` and `int16_t *` pointer arguments
+- Support using `[string]` (single-element string arrays) for polymorphic input/output arguments
+
 #### Koffi 2.3.16
 
 **Main changes:**
@@ -13,7 +26,7 @@
 
 **Other changes:**
 
-- Support null in koffi.free() and koffi.address()
+- Support null in `koffi.free()` and `koffi.address()`
 
 #### Koffi 2.3.15
 

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "koffi",
-    "version": "2.3.16",
-    "stable": "2.3.16",
+    "version": "2.3.18",
+    "stable": "2.3.18",
     "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();
 
@@ -147,7 +149,7 @@ bool CallData::PushString(Napi::Value value, int directions, const char **out_st
 {
     if (value.IsString()) {
         if (RG_UNLIKELY(directions & 2)) {
-            ThrowError<Napi::TypeError>(env, "Unexpected %1 value, expected string", GetValueType(instance, value));
+            ThrowError<Napi::TypeError>(env, "Unexpected %1 value, expected [string]", GetValueType(instance, value));
             return false;
         }
 
@@ -200,6 +202,7 @@ bool CallData::PushString(Napi::Value value, int directions, const char **out_st
             napi_status status = napi_create_reference(env, array, 1, &out->ref);
             RG_ASSERT(status == napi_ok);
 
+            out->kind = OutArgument::Kind::Array;
             out->ptr = (const uint8_t *)*out_str;
             out->type = type;
         }
@@ -301,6 +304,7 @@ bool CallData::PushString16(Napi::Value value, int directions, const char16_t **
             napi_status status = napi_create_reference(env, array, 1, &out->ref);
             RG_ASSERT(status == napi_ok);
 
+            out->kind = OutArgument::Kind::Array;
             out->ptr = (const uint8_t *)*out_str16;
             out->type = type;
         }
@@ -973,6 +977,9 @@ bool CallData::PushPointer(Napi::Value value, const TypeInfo *type, int directio
         case napi_object: {
             uint8_t *ptr = nullptr;
 
+            OutArgument::Kind out_kind;
+            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()",
@@ -981,17 +988,25 @@ bool CallData::PushPointer(Napi::Value value, const TypeInfo *type, int directio
                 }
 
                 Napi::Array array = value.As<Napi::Array>();
+                Size len = PushIndirectString(array, type->ref.type, &ptr);
 
-                Size len = (Size)array.Length();
-                Size size = len * type->ref.type->size;
+                if (len >= 0) {
+                    out_kind = (type->ref.type->size == 2) ? OutArgument::Kind::String16 : OutArgument::Kind::String;
+                    out_max_len = len;
+                } else {
+                    Size len = (Size)array.Length();
+                    Size size = len * type->ref.type->size;
 
-                ptr = AllocHeap(size, 16);
+                    ptr = AllocHeap(size, 16);
 
-                if (directions & 1) {
-                    if (!PushNormalArray(array, len, type, ptr))
-                        return false;
-                } else {
-                    memset_safe(ptr, 0, size);
+                    if (directions & 1) {
+                        if (!PushNormalArray(array, len, type, ptr))
+                            return false;
+                    } else {
+                        memset_safe(ptr, 0, size);
+                    }
+
+                    out_kind = OutArgument::Kind::Array;
                 }
             } else if (IsRawBuffer(value)) {
                 Span<uint8_t> buffer = GetRawBuffer(value);
@@ -1006,6 +1021,8 @@ bool CallData::PushPointer(Napi::Value value, const TypeInfo *type, int directio
                     ptr = buffer.ptr;
                     directions = 1;
                 }
+
+                out_kind = OutArgument::Kind::Buffer;
             } else if (RG_LIKELY(type->ref.type->primitive == PrimitiveKind::Record ||
                                  type->ref.type->primitive == PrimitiveKind::Union)) {
                 if (RG_UNLIKELY(!type->ref.type->size)) {
@@ -1031,6 +1048,8 @@ bool CallData::PushPointer(Napi::Value value, const TypeInfo *type, int directio
 
                     memset_safe(ptr, 0, type->size);
                 }
+
+                out_kind = OutArgument::Kind::Object;
             } else {
                 goto unexpected;
             }
@@ -1041,14 +1060,36 @@ bool CallData::PushPointer(Napi::Value value, const TypeInfo *type, int directio
                 napi_status status = napi_create_reference(env, value, 1, &out->ref);
                 RG_ASSERT(status == napi_ok);
 
+                out->kind = out_kind;
                 out->ptr = ptr;
                 out->type = type->ref.type;
+                out->max_len = out_max_len;
             }
 
             *out_ptr = ptr;
             return true;
         } break;
 
+        case napi_string: {
+            RG_ASSERT(type->primitive == PrimitiveKind::Pointer);
+
+            if (RG_UNLIKELY(directions & 2))
+                goto unexpected;
+
+            if (type->ref.type == instance->void_type) {
+                PushStringValue(value, (const char **)out_ptr);
+                return true;
+            } else if (type->ref.type->primitive == PrimitiveKind::Int8) {
+                PushStringValue(value, (const char **)out_ptr);
+                return true;
+            } else if (type->ref.type->primitive == PrimitiveKind::Int16) {
+                PushString16Value(value, (const char16_t **)out_ptr);
+                return true;
+            } else {
+                goto unexpected;
+            }
+        } break;
+
         case napi_number: {
             Napi::Number number = value.As<Napi::Number>();
             intptr_t ptr = (intptr_t)number.Int32Value();
@@ -1075,6 +1116,27 @@ unexpected:
     return false;
 }
 
+Size CallData::PushIndirectString(Napi::Array array, const TypeInfo *ref, uint8_t **out_ptr)
+{
+    if (array.Length() != 1)
+        return -1;
+
+    Napi::Value value = array[0u];
+
+    if (!value.IsString())
+        return -1;
+
+    if (ref == instance->void_type) {
+        return PushStringValue(value, (const char **)out_ptr);
+    } else if (ref->primitive == PrimitiveKind::Int8) {
+        return PushStringValue(value, (const char **)out_ptr);
+    } else if (ref->primitive == PrimitiveKind::Int16) {
+        return PushString16Value(value, (const char16_t **)out_ptr);
+    } else {
+        return -1;
+    }
+}
+
 static inline Napi::Value GetReferenceValue(Napi::Env env, napi_ref ref)
 {
     napi_value value;
@@ -1091,21 +1153,55 @@ void CallData::PopOutArguments()
         Napi::Value value = GetReferenceValue(env, out.ref);
         RG_ASSERT(!value.IsEmpty());
 
-        if (value.IsArray()) {
-            Napi::Array array(env, value);
-            DecodeNormalArray(array, out.ptr, out.type);
-        } else if (IsRawBuffer(value)) {
-            Span<uint8_t> buffer = GetRawBuffer(value);
-            DecodeBuffer(buffer, out.ptr, out.type);
-        } else {
-            Napi::Object obj = value.As<Napi::Object>();
-
-            if (CheckValueTag(instance, value, &MagicUnionMarker)) {
-                MagicUnion *u = MagicUnion::Unwrap(obj);
-                u->SetRaw(out.ptr);
-            } else {
-                DecodeObject(obj, out.ptr, out.type);
-            }
+        switch (out.kind) {
+            case OutArgument::Kind::Array: {
+                RG_ASSERT(value.IsArray());
+
+                Napi::Array array(env, value);
+                DecodeNormalArray(array, out.ptr, out.type);
+            } break;
+
+            case OutArgument::Kind::Buffer: {
+                RG_ASSERT(IsRawBuffer(value));
+
+                Span<uint8_t> buffer = GetRawBuffer(value);
+                DecodeBuffer(buffer, out.ptr, out.type);
+            } break;
+
+            case OutArgument::Kind::String: {
+                Napi::Array array(env, value);
+
+                RG_ASSERT(array.IsArray());
+                RG_ASSERT(array.Length() == 1);
+
+                Size len = strnlen((const char *)out.ptr, out.max_len);
+                Napi::String str = Napi::String::New(env, (const char *)out.ptr, len);
+
+                array.Set(0u, str);
+            } break;
+
+            case OutArgument::Kind::String16: {
+                Napi::Array array(env, value);
+
+                RG_ASSERT(array.IsArray());
+                RG_ASSERT(array.Length() == 1);
+
+                Size len = WideStringLength((const char16_t *)out.ptr, out.max_len);
+                Napi::String str = Napi::String::New(env, (const char16_t *)out.ptr, len);
+
+                array.Set(0u, str);
+            } break;
+
+            case OutArgument::Kind::Object: {
+                Napi::Object obj = value.As<Napi::Object>();
+
+                if (CheckValueTag(instance, value, &MagicUnionMarker)) {
+                    MagicUnion *u = MagicUnion::Unwrap(obj);
+                    u->SetRaw(out.ptr);
+                } else {
+                    DecodeObject(obj, out.ptr, out.type);
+                }
+            } break;
         }
     }
 }
@@ -1131,6 +1227,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/call.hh

@@ -37,9 +37,21 @@ struct BackRegisters;
 // But on Windows i386, without it, the alignment may not be correct (compiler bug?).
 class alignas(8) CallData {
     struct OutArgument {
+        enum class Kind {
+            Array,
+            Buffer,
+            String,
+            String16,
+            Object
+        };
+
+        Kind kind;
+
         napi_ref ref;
         const uint8_t *ptr;
         const TypeInfo *type;
+
+        Size max_len; // Only for indirect strings
     };
 
     Napi::Env env;
@@ -116,6 +128,7 @@ private:
     bool PushBuffer(Span<const uint8_t> buffer, Size size, const TypeInfo *type, uint8_t *origin);
     bool PushStringArray(Napi::Value value, const TypeInfo *type, uint8_t *origin);
     bool PushPointer(Napi::Value value, const TypeInfo *type, int directions, void **out_ptr);
+    Size PushIndirectString(Napi::Array array, const TypeInfo *ref, uint8_t **out_ptr);
 
     void PopOutArguments();
 

package/src/koffi/src/ffi.cc

@@ -605,8 +605,10 @@ static Napi::Value EncodePointerDirection(const Napi::CallbackInfo &info, int di
     if (!type)
         return env.Null();
 
-    if (type->primitive != PrimitiveKind::Pointer) {
-        ThrowError<Napi::TypeError>(env, "Unexpected %1 type, expected pointer type", type->name);
+    if (type->primitive != PrimitiveKind::Pointer &&
+            type->primitive != PrimitiveKind::String &&
+            type->primitive != PrimitiveKind::String16) {
+        ThrowError<Napi::TypeError>(env, "Unexpected %1 type, expected pointer or string type", type->name);
         return env.Null();
     }
 
@@ -653,9 +655,9 @@ static Napi::Value CreateDisposableType(const Napi::CallbackInfo &info)
     const TypeInfo *src = ResolveType(info[named]);
     if (!src)
         return env.Null();
-    if (src->primitive != PrimitiveKind::String &&
-            src->primitive != PrimitiveKind::String16 &&
-            src->primitive != PrimitiveKind::Pointer) {
+    if (src->primitive != PrimitiveKind::Pointer &&
+            src->primitive != PrimitiveKind::String &&
+            src->primitive != PrimitiveKind::String16) {
         ThrowError<Napi::TypeError>(env, "Unexpected %1 type, expected pointer or string type", src->name);
         return env.Null();
     }
@@ -1652,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)) {
@@ -1952,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();
             }
@@ -1982,8 +1983,10 @@ static Napi::Value CastValue(const Napi::CallbackInfo &info)
     const TypeInfo *type = ResolveType(info[1]);
     if (RG_UNLIKELY(!type))
         return env.Null();
-    if (type->primitive != PrimitiveKind::Pointer) {
-        ThrowError<Napi::TypeError>(env, "Only pointer types can be used for casting");
+    if (type->primitive != PrimitiveKind::Pointer &&
+            type->primitive != PrimitiveKind::String &&
+            type->primitive != PrimitiveKind::String16) {
+        ThrowError<Napi::TypeError>(env, "Only pointer or string types can be used for casting");
         return env.Null();
     }
 

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/src/koffi/src/util.cc

@@ -647,7 +647,7 @@ void DecodeObject(Napi::Object obj, const uint8_t *origin, const TypeInfo *type)
     }
 }
 
-static Size WideStringLength(const char16_t *str16, Size max)
+Size WideStringLength(const char16_t *str16, Size max)
 {
     Size len = 0;
 

package/src/koffi/src/util.hh

@@ -154,6 +154,8 @@ T GetNumber(Napi::Value value)
     RG_UNREACHABLE();
 }
 
+Size WideStringLength(const char16_t *str16, Size max);
+
 Napi::Object DecodeObject(Napi::Env env, const uint8_t *origin, const TypeInfo *type);
 void DecodeObject(Napi::Object obj, const uint8_t *origin, const TypeInfo *type);
 Napi::Value DecodeArray(Napi::Env env, const uint8_t *origin, const TypeInfo *type);

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