From 3b8f8083730973c00a9b1a76674bb117c6623467 Mon Sep 17 00:00:00 2001
From: Ben Noordhuis <info@bnoordhuis.nl>
Date: Tue, 7 Apr 2026 11:11:15 +0200
Subject: [PATCH 1/5] node-api: add napi_create_external_sharedarraybuffer

Creates a SharedArrayBuffer from externally managed memory.

Fixes: https://github.com/nodejs/node/issues/62259
---
 doc/api/n-api.md                        | 37 +++++++++++++++++++
 src/js_native_api.h                     |  9 +++++
 src/js_native_api_v8.cc                 | 49 +++++++++++++++++++++++++
 test/node-api/test_buffer/test.js       | 10 +++++
 test/node-api/test_buffer/test_buffer.c | 25 +++++++++++++
 5 files changed, 130 insertions(+)

diff --git a/doc/api/n-api.md b/doc/api/n-api.md
index 269492b480fd20..9d5be3a69d554d 100644
--- a/doc/api/n-api.md
+++ b/doc/api/n-api.md
@@ -2575,6 +2575,43 @@ object just created has been garbage collected.
 JavaScript `ArrayBuffer`s are described in
 [Section ArrayBuffer objects][] of the ECMAScript Language Specification.
 
+#### `napi_create_external_sharedarraybuffer`
+
+<!-- YAML
+added: TODO
+napiVersion: 1
+-->
+
+```c
+napi_status
+napi_create_external_sharedarraybuffer(napi_env env,
+                                       void* external_data,
+                                       size_t byte_length,
+                                       void (*finalize_cb)(
+                                          void* external_data,
+                                          void* finalize_hint),
+                                       void* finalize_hint,
+                                       napi_value* result)
+```
+
+* `[in] env`: The environment that the API is invoked under.
+* `[in] external_data`: Pointer to the underlying byte buffer of the
+  `SharedArrayBuffer`.
+* `[in] byte_length`: The length in bytes of the underlying buffer.
+* `[in] finalize_cb`: Optional callback to call when the `SharedArrayBuffer` is
+   being collected. Because a `SharedArrayBuffer` can outlive the environment
+   it was created in, the callback does not get receive a reference to `env`.
+* `[in] finalize_hint`: Optional hint to pass to the finalize callback during
+  collection.
+* `[out] result`: A `napi_value` representing a JavaScript `SharedArrayBuffer`.
+
+Returns `napi_ok` if the API succeeded.
+
+Create a `SharedArrayBuffer` with externally managed memory.
+
+See the entry on [`napi_create_external_arraybuffer`][] for runtime
+compatibility.
+
 #### `napi_create_external_buffer`
 
 <!-- YAML
diff --git a/src/js_native_api.h b/src/js_native_api.h
index 31eee1234e1d2f..66242248f7d483 100644
--- a/src/js_native_api.h
+++ b/src/js_native_api.h
@@ -437,6 +437,15 @@ napi_create_external_arraybuffer(napi_env env,
                                  node_api_basic_finalize finalize_cb,
                                  void* finalize_hint,
                                  napi_value* result);
+NAPI_EXTERN napi_status NAPI_CDECL
+napi_create_external_sharedarraybuffer(napi_env env,
+                                       void* external_data,
+                                       size_t byte_length,
+                                       void (*finalize_cb)(
+                                          void* external_data,
+                                          void* finalize_hint),
+                                       void* finalize_hint,
+                                       napi_value* result);
 #endif  // NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED
 NAPI_EXTERN napi_status NAPI_CDECL napi_get_arraybuffer_info(
     napi_env env, napi_value arraybuffer, void** data, size_t* byte_length);
diff --git a/src/js_native_api_v8.cc b/src/js_native_api_v8.cc
index a944c18518471a..8c014fc3e5ed84 100644
--- a/src/js_native_api_v8.cc
+++ b/src/js_native_api_v8.cc
@@ -136,6 +136,42 @@ napi_status NewExternalString(napi_env env,
   return status;
 }
 
+napi_status NewExternalSharedArrayBuffer(napi_env env,
+                                         void* external_data,
+                                         size_t byte_length,
+                                         void (*finalize_cb)(
+                                            void* external_data,
+                                            void* finalize_hint),
+                                         void* finalize_hint,
+                                         napi_value* result) {
+  struct FinalizerData {
+    void (*cb)(void* external_data, void* finalize_hint);
+    void* hint;
+  };
+  auto deleter = [](void* external_data, size_t length, void* deleter_data) {
+    if (auto fd = static_cast<FinalizerData*>(deleter_data)) {
+      fd->cb(external_data, fd->hint);
+      delete fd;
+    }
+  };
+  FinalizerData* deleter_data = nullptr;
+  if (finalize_cb != nullptr) {
+    deleter_data = new FinalizerData { finalize_cb, finalize_hint };
+  }
+  auto unique_backing_store =
+      v8::SharedArrayBuffer::NewBackingStore(
+          external_data, byte_length, deleter,
+          reinterpret_cast<void*>(deleter_data));
+  CHECK(!!unique_backing_store);  // Cannot fail.
+  auto shared_backing_store =
+      std::shared_ptr<v8::BackingStore>(std::move(unique_backing_store));
+  auto shared_array_buffer =
+      v8::SharedArrayBuffer::New(env->isolate, shared_backing_store);
+  CHECK_MAYBE_EMPTY(env, shared_array_buffer, napi_generic_failure);
+  *result = v8impl::JsValueFromV8LocalValue(shared_array_buffer);
+  return napi_clear_last_error(env);
+}
+
 class TrackedStringResource : private RefTracker {
  public:
   TrackedStringResource(napi_env env,
@@ -3134,6 +3170,19 @@ napi_create_external_arraybuffer(napi_env env,
       env, buffer, nullptr, nullptr, nullptr, result, nullptr);
 }
 
+napi_status NAPI_CDECL
+napi_create_external_sharedarraybuffer(napi_env env,
+                                       void* external_data,
+                                       size_t byte_length,
+                                       void (*finalize_cb)(
+                                          void* external_data,
+                                          void* finalize_hint),
+                                       void* finalize_hint,
+                                       napi_value* result) {
+  return v8impl::NewExternalSharedArrayBuffer(
+      env, external_data, byte_length, finalize_cb, finalize_hint, result);
+}
+
 napi_status NAPI_CDECL napi_get_arraybuffer_info(napi_env env,
                                                  napi_value arraybuffer,
                                                  void** data,
diff --git a/test/node-api/test_buffer/test.js b/test/node-api/test_buffer/test.js
index c51eddabc183e6..f244c54e20048e 100644
--- a/test/node-api/test_buffer/test.js
+++ b/test/node-api/test_buffer/test.js
@@ -26,6 +26,16 @@ const tick = require('util').promisify(require('../../common/tick'));
   console.log('gc2');
   assert.strictEqual(binding.getDeleterCallCount(), 2);
 
+  // Caveat emptor: it's indeterminate when the SharedArrayBuffer's backing
+  // store is reclaimed; at least some of the time it happens even before
+  // calling gc().
+  let sab = binding.newExternalSharedArrayBuffer();
+  sab = null;
+  global.gc();
+  await tick(10);
+  console.log('gc3');
+  assert.strictEqual(binding.getDeleterCallCount(), 3);
+
   // To test this doesn't crash
   binding.invalidObjectAsBuffer({});
 
diff --git a/test/node-api/test_buffer/test_buffer.c b/test/node-api/test_buffer/test_buffer.c
index 9cfda6334fb3ef..bcfc60ded84727 100644
--- a/test/node-api/test_buffer/test_buffer.c
+++ b/test/node-api/test_buffer/test_buffer.c
@@ -58,6 +58,29 @@ static napi_value newExternalBuffer(napi_env env, napi_callback_info info) {
   return theBuffer;
 }
 
+static char externalSharedArrayBufferData[1];
+
+static void freeExternalSharedArrayBuffer(void* data, void* hint) {
+  (void)hint;
+  NODE_API_BASIC_ASSERT_RETURN_VOID(
+      data == (void*)externalSharedArrayBufferData,
+      "SharedArrayBuffer points to wrong data");
+  deleterCallCount++;
+}
+
+static napi_value newExternalSharedArrayBuffer(napi_env env,
+                                               napi_callback_info info) {
+  napi_value sab;
+  NODE_API_CALL(env,
+      napi_create_external_sharedarraybuffer(env,
+                                             externalSharedArrayBufferData,
+                                             1,
+                                             freeExternalSharedArrayBuffer,
+                                             NULL,
+                                             &sab));
+  return sab;
+}
+
 static napi_value getDeleterCallCount(napi_env env, napi_callback_info info) {
   napi_value callCount;
   NODE_API_CALL(env, napi_create_int32(env, deleterCallCount, &callCount));
@@ -171,6 +194,8 @@ static napi_value Init(napi_env env, napi_value exports) {
   napi_property_descriptor methods[] = {
       DECLARE_NODE_API_PROPERTY("newBuffer", newBuffer),
       DECLARE_NODE_API_PROPERTY("newExternalBuffer", newExternalBuffer),
+      DECLARE_NODE_API_PROPERTY("newExternalSharedArrayBuffer",
+                                newExternalSharedArrayBuffer),
       DECLARE_NODE_API_PROPERTY("getDeleterCallCount", getDeleterCallCount),
       DECLARE_NODE_API_PROPERTY("copyBuffer", copyBuffer),
       DECLARE_NODE_API_PROPERTY("bufferHasInstance", bufferHasInstance),

From 6bc42e260fbd9f588868bc3e259cd7a5afba3bb8 Mon Sep 17 00:00:00 2001
From: Ben Noordhuis <info@bnoordhuis.nl>
Date: Tue, 7 Apr 2026 11:21:05 +0200
Subject: [PATCH 2/5] squash! lint

---
 src/js_native_api.h                     | 16 +++++-----
 src/js_native_api_v8.cc                 | 42 ++++++++++++-------------
 test/node-api/test_buffer/test_buffer.c |  3 +-
 3 files changed, 29 insertions(+), 32 deletions(-)

diff --git a/src/js_native_api.h b/src/js_native_api.h
index 66242248f7d483..e2bcaa8e5bbc44 100644
--- a/src/js_native_api.h
+++ b/src/js_native_api.h
@@ -437,15 +437,13 @@ napi_create_external_arraybuffer(napi_env env,
                                  node_api_basic_finalize finalize_cb,
                                  void* finalize_hint,
                                  napi_value* result);
-NAPI_EXTERN napi_status NAPI_CDECL
-napi_create_external_sharedarraybuffer(napi_env env,
-                                       void* external_data,
-                                       size_t byte_length,
-                                       void (*finalize_cb)(
-                                          void* external_data,
-                                          void* finalize_hint),
-                                       void* finalize_hint,
-                                       napi_value* result);
+NAPI_EXTERN napi_status NAPI_CDECL napi_create_external_sharedarraybuffer(
+    napi_env env,
+    void* external_data,
+    size_t byte_length,
+    void (*finalize_cb)(void* external_data, void* finalize_hint),
+    void* finalize_hint,
+    napi_value* result);
 #endif  // NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED
 NAPI_EXTERN napi_status NAPI_CDECL napi_get_arraybuffer_info(
     napi_env env, napi_value arraybuffer, void** data, size_t* byte_length);
diff --git a/src/js_native_api_v8.cc b/src/js_native_api_v8.cc
index 8c014fc3e5ed84..fc85c2b232051c 100644
--- a/src/js_native_api_v8.cc
+++ b/src/js_native_api_v8.cc
@@ -136,14 +136,13 @@ napi_status NewExternalString(napi_env env,
   return status;
 }
 
-napi_status NewExternalSharedArrayBuffer(napi_env env,
-                                         void* external_data,
-                                         size_t byte_length,
-                                         void (*finalize_cb)(
-                                            void* external_data,
-                                            void* finalize_hint),
-                                         void* finalize_hint,
-                                         napi_value* result) {
+napi_status NewExternalSharedArrayBuffer(
+    napi_env env,
+    void* external_data,
+    size_t byte_length,
+    void (*finalize_cb)(void* external_data, void* finalize_hint),
+    void* finalize_hint,
+    napi_value* result) {
   struct FinalizerData {
     void (*cb)(void* external_data, void* finalize_hint);
     void* hint;
@@ -156,12 +155,13 @@ napi_status NewExternalSharedArrayBuffer(napi_env env,
   };
   FinalizerData* deleter_data = nullptr;
   if (finalize_cb != nullptr) {
-    deleter_data = new FinalizerData { finalize_cb, finalize_hint };
+    deleter_data = new FinalizerData{finalize_cb, finalize_hint};
   }
-  auto unique_backing_store =
-      v8::SharedArrayBuffer::NewBackingStore(
-          external_data, byte_length, deleter,
-          reinterpret_cast<void*>(deleter_data));
+  auto unique_backing_store = v8::SharedArrayBuffer::NewBackingStore(
+      external_data,
+      byte_length,
+      deleter,
+      reinterpret_cast<void*>(deleter_data));
   CHECK(!!unique_backing_store);  // Cannot fail.
   auto shared_backing_store =
       std::shared_ptr<v8::BackingStore>(std::move(unique_backing_store));
@@ -3170,15 +3170,13 @@ napi_create_external_arraybuffer(napi_env env,
       env, buffer, nullptr, nullptr, nullptr, result, nullptr);
 }
 
-napi_status NAPI_CDECL
-napi_create_external_sharedarraybuffer(napi_env env,
-                                       void* external_data,
-                                       size_t byte_length,
-                                       void (*finalize_cb)(
-                                          void* external_data,
-                                          void* finalize_hint),
-                                       void* finalize_hint,
-                                       napi_value* result) {
+napi_status NAPI_CDECL napi_create_external_sharedarraybuffer(
+    napi_env env,
+    void* external_data,
+    size_t byte_length,
+    void (*finalize_cb)(void* external_data, void* finalize_hint),
+    void* finalize_hint,
+    napi_value* result) {
   return v8impl::NewExternalSharedArrayBuffer(
       env, external_data, byte_length, finalize_cb, finalize_hint, result);
 }
diff --git a/test/node-api/test_buffer/test_buffer.c b/test/node-api/test_buffer/test_buffer.c
index bcfc60ded84727..4f2fc886323435 100644
--- a/test/node-api/test_buffer/test_buffer.c
+++ b/test/node-api/test_buffer/test_buffer.c
@@ -71,7 +71,8 @@ static void freeExternalSharedArrayBuffer(void* data, void* hint) {
 static napi_value newExternalSharedArrayBuffer(napi_env env,
                                                napi_callback_info info) {
   napi_value sab;
-  NODE_API_CALL(env,
+  NODE_API_CALL(
+      env,
       napi_create_external_sharedarraybuffer(env,
                                              externalSharedArrayBufferData,
                                              1,

From 32fe1543c19728844e5cbc752cbc2fce6db44c5c Mon Sep 17 00:00:00 2001
From: Ben Noordhuis <info@bnoordhuis.nl>
Date: Tue, 7 Apr 2026 11:40:41 +0200
Subject: [PATCH 3/5] squash! more lint

---
 test/node-api/test_buffer/test.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/test/node-api/test_buffer/test.js b/test/node-api/test_buffer/test.js
index f244c54e20048e..dc87eee10045c9 100644
--- a/test/node-api/test_buffer/test.js
+++ b/test/node-api/test_buffer/test.js
@@ -30,7 +30,7 @@ const tick = require('util').promisify(require('../../common/tick'));
   // store is reclaimed; at least some of the time it happens even before
   // calling gc().
   let sab = binding.newExternalSharedArrayBuffer();
-  sab = null;
+  sab = null;  // eslint-disable-line no-unused-vars
   global.gc();
   await tick(10);
   console.log('gc3');

From 5578c1aaae84551d32f1b81e8f5a63eef8929013 Mon Sep 17 00:00:00 2001
From: Ben Noordhuis <info@bnoordhuis.nl>
Date: Tue, 7 Apr 2026 11:49:16 +0200
Subject: [PATCH 4/5] squash! more lint

---
 doc/api/n-api.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/api/n-api.md b/doc/api/n-api.md
index 9d5be3a69d554d..6062749e6fbf58 100644
--- a/doc/api/n-api.md
+++ b/doc/api/n-api.md
@@ -2578,7 +2578,7 @@ JavaScript `ArrayBuffer`s are described in
 #### `napi_create_external_sharedarraybuffer`
 
 <!-- YAML
-added: TODO
+added: REPLACEME
 napiVersion: 1
 -->
 

From 5d2dd37cdbde4dff1135bfb08ddc0a2644b34922 Mon Sep 17 00:00:00 2001
From: Ben Noordhuis <info@bnoordhuis.nl>
Date: Tue, 7 Apr 2026 12:13:31 +0200
Subject: [PATCH 5/5] squash! more more lint

---
 doc/api/n-api.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/api/n-api.md b/doc/api/n-api.md
index 6062749e6fbf58..dcf426884b7d71 100644
--- a/doc/api/n-api.md
+++ b/doc/api/n-api.md
@@ -2599,8 +2599,8 @@ napi_create_external_sharedarraybuffer(napi_env env,
   `SharedArrayBuffer`.
 * `[in] byte_length`: The length in bytes of the underlying buffer.
 * `[in] finalize_cb`: Optional callback to call when the `SharedArrayBuffer` is
-   being collected. Because a `SharedArrayBuffer` can outlive the environment
-   it was created in, the callback does not get receive a reference to `env`.
+  being collected. Because a `SharedArrayBuffer` can outlive the environment
+  it was created in, the callback does not get receive a reference to `env`.
 * `[in] finalize_hint`: Optional hint to pass to the finalize callback during
   collection.
 * `[out] result`: A `napi_value` representing a JavaScript `SharedArrayBuffer`.