node-api: support SharedArrayBuffer in napi_create_typedarray

Signed-off-by: umuoy1 <burningdian@gmail.com>
PR-URL: #62710
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
Reviewed-By: Vladimir Morozov <vmorozov@microsoft.com>
Signed-off-by: Juan José Arboleda <soyjuanarbol@gmail.com>

Author: umuoy1

doc/api/n-api.md

@@ -2734,6 +2734,10 @@ Language Specification.
 <!-- YAML
 added: v8.0.0
 napiVersion: 1
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/62710
+    description: Added support for `SharedArrayBuffer`.
 -->
 
 ```c
@@ -2748,21 +2752,25 @@ napi_status napi_create_typedarray(napi_env env,
 * `[in] env`: The environment that the API is invoked under.
 * `[in] type`: Scalar datatype of the elements within the `TypedArray`.
 * `[in] length`: Number of elements in the `TypedArray`.
-* `[in] arraybuffer`: `ArrayBuffer` underlying the typed array.
-* `[in] byte_offset`: The byte offset within the `ArrayBuffer` from which to
-  start projecting the `TypedArray`.
+* `[in] arraybuffer`: `ArrayBuffer` or `SharedArrayBuffer` underlying the
+  typed array.
+* `[in] byte_offset`: The byte offset within the `ArrayBuffer` or
+  `SharedArrayBuffer` from which to start projecting the `TypedArray`.
 * `[out] result`: A `napi_value` representing a JavaScript `TypedArray`.
 
 Returns `napi_ok` if the API succeeded.
 
 This API creates a JavaScript `TypedArray` object over an existing
-`ArrayBuffer`. `TypedArray` objects provide an array-like view over an
-underlying data buffer where each element has the same underlying binary scalar
-datatype.
+`ArrayBuffer` or `SharedArrayBuffer`. `TypedArray` objects provide an
+array-like view over an underlying data buffer where each element has the same
+underlying binary scalar datatype.
+
+It is required that `(length * size_of_element) + byte_offset` is less than or
+equal to the size in bytes of the `ArrayBuffer` or `SharedArrayBuffer` passed
+in. If not, a `RangeError` exception is raised.
 
-It's required that `(length * size_of_element) + byte_offset` should
-be <= the size in bytes of the array passed in. If not, a `RangeError` exception
-is raised.
+For element sizes greater than 1, `byte_offset` is required to be a multiple
+of the element size. If not, a `RangeError` exception is raised.
 
 JavaScript `TypedArray` objects are described in
 [Section TypedArray objects][] of the ECMAScript Language Specification.
@@ -3439,7 +3447,8 @@ napi_status napi_get_typedarray_info(napi_env env,
   the `byte_offset` value so that it points to the first element in the
   `TypedArray`. If the length of the array is `0`, this may be `NULL` or
   any other pointer value.
-* `[out] arraybuffer`: The `ArrayBuffer` underlying the `TypedArray`.
+* `[out] arraybuffer`: The `ArrayBuffer` or `SharedArrayBuffer` underlying the
+  `TypedArray`.
 * `[out] byte_offset`: The byte offset within the underlying native array
   at which the first element of the arrays is located. The value for the data
   parameter has already been adjusted so that data points to the first element

src/js_native_api_v8.cc

@@ -3204,62 +3204,69 @@ napi_status NAPI_CDECL napi_create_typedarray(napi_env env,
   CHECK_ARG(env, result);
 
   v8::Local<v8::Value> value = v8impl::V8LocalValueFromJsValue(arraybuffer);
-  RETURN_STATUS_IF_FALSE(env, value->IsArrayBuffer(), napi_invalid_arg);
+  auto create_typedarray = [&](auto buffer) -> napi_status {
+    v8::Local<v8::TypedArray> typedArray;
+
+    switch (type) {
+      case napi_int8_array:
+        CREATE_TYPED_ARRAY(
+            env, Int8Array, 1, buffer, byte_offset, length, typedArray);
+        break;
+      case napi_uint8_array:
+        CREATE_TYPED_ARRAY(
+            env, Uint8Array, 1, buffer, byte_offset, length, typedArray);
+        break;
+      case napi_uint8_clamped_array:
+        CREATE_TYPED_ARRAY(
+            env, Uint8ClampedArray, 1, buffer, byte_offset, length, typedArray);
+        break;
+      case napi_int16_array:
+        CREATE_TYPED_ARRAY(
+            env, Int16Array, 2, buffer, byte_offset, length, typedArray);
+        break;
+      case napi_uint16_array:
+        CREATE_TYPED_ARRAY(
+            env, Uint16Array, 2, buffer, byte_offset, length, typedArray);
+        break;
+      case napi_int32_array:
+        CREATE_TYPED_ARRAY(
+            env, Int32Array, 4, buffer, byte_offset, length, typedArray);
+        break;
+      case napi_uint32_array:
+        CREATE_TYPED_ARRAY(
+            env, Uint32Array, 4, buffer, byte_offset, length, typedArray);
+        break;
+      case napi_float32_array:
+        CREATE_TYPED_ARRAY(
+            env, Float32Array, 4, buffer, byte_offset, length, typedArray);
+        break;
+      case napi_float64_array:
+        CREATE_TYPED_ARRAY(
+            env, Float64Array, 8, buffer, byte_offset, length, typedArray);
+        break;
+      case napi_bigint64_array:
+        CREATE_TYPED_ARRAY(
+            env, BigInt64Array, 8, buffer, byte_offset, length, typedArray);
+        break;
+      case napi_biguint64_array:
+        CREATE_TYPED_ARRAY(
+            env, BigUint64Array, 8, buffer, byte_offset, length, typedArray);
+        break;
+      default:
+        return napi_set_last_error(env, napi_invalid_arg);
+    }
 
-  v8::Local<v8::ArrayBuffer> buffer = value.As<v8::ArrayBuffer>();
-  v8::Local<v8::TypedArray> typedArray;
+    *result = v8impl::JsValueFromV8LocalValue(typedArray);
+    return GET_RETURN_STATUS(env);
+  };
 
-  switch (type) {
-    case napi_int8_array:
-      CREATE_TYPED_ARRAY(
-          env, Int8Array, 1, buffer, byte_offset, length, typedArray);
-      break;
-    case napi_uint8_array:
-      CREATE_TYPED_ARRAY(
-          env, Uint8Array, 1, buffer, byte_offset, length, typedArray);
-      break;
-    case napi_uint8_clamped_array:
-      CREATE_TYPED_ARRAY(
-          env, Uint8ClampedArray, 1, buffer, byte_offset, length, typedArray);
-      break;
-    case napi_int16_array:
-      CREATE_TYPED_ARRAY(
-          env, Int16Array, 2, buffer, byte_offset, length, typedArray);
-      break;
-    case napi_uint16_array:
-      CREATE_TYPED_ARRAY(
-          env, Uint16Array, 2, buffer, byte_offset, length, typedArray);
-      break;
-    case napi_int32_array:
-      CREATE_TYPED_ARRAY(
-          env, Int32Array, 4, buffer, byte_offset, length, typedArray);
-      break;
-    case napi_uint32_array:
-      CREATE_TYPED_ARRAY(
-          env, Uint32Array, 4, buffer, byte_offset, length, typedArray);
-      break;
-    case napi_float32_array:
-      CREATE_TYPED_ARRAY(
-          env, Float32Array, 4, buffer, byte_offset, length, typedArray);
-      break;
-    case napi_float64_array:
-      CREATE_TYPED_ARRAY(
-          env, Float64Array, 8, buffer, byte_offset, length, typedArray);
-      break;
-    case napi_bigint64_array:
-      CREATE_TYPED_ARRAY(
-          env, BigInt64Array, 8, buffer, byte_offset, length, typedArray);
-      break;
-    case napi_biguint64_array:
-      CREATE_TYPED_ARRAY(
-          env, BigUint64Array, 8, buffer, byte_offset, length, typedArray);
-      break;
-    default:
-      return napi_set_last_error(env, napi_invalid_arg);
+  if (value->IsArrayBuffer()) {
+    return create_typedarray(value.As<v8::ArrayBuffer>());
+  } else if (value->IsSharedArrayBuffer()) {
+    return create_typedarray(value.As<v8::SharedArrayBuffer>());
+  } else {
+    return napi_set_last_error(env, napi_invalid_arg);
   }
-
-  *result = v8impl::JsValueFromV8LocalValue(typedArray);
-  return GET_RETURN_STATUS(env);
 }
 
 napi_status NAPI_CDECL napi_get_typedarray_info(napi_env env,

test/js-native-api/test_typedarray/binding.gyp

@@ -5,6 +5,12 @@
       "sources": [
         "test_typedarray.c"
       ]
+    },
+    {
+      "target_name": "test_typedarray_sharedarraybuffer",
+      "sources": [
+        "test_typedarray_sharedarraybuffer.c"
+      ]
     }
   ]
 }

test/js-native-api/test_typedarray/test_sharedarraybuffer.js

@@ -0,0 +1,109 @@
+'use strict';
+
+// Verify SharedArrayBuffer-backed typed arrays can be created through
+// napi_create_typedarray() while preserving existing ArrayBuffer behavior.
+
+const common = require('../../common');
+const assert = require('assert');
+
+const test_typedarray_sharedarraybuffer =
+  require(`./build/${common.buildType}/test_typedarray_sharedarraybuffer`);
+
+const typedArrayCases = [
+  { type: Int8Array, values: [-1, 0, 127] },
+  { type: Uint8Array, values: [1, 2, 255] },
+  { type: Uint8ClampedArray, values: [0, 128, 255] },
+  { type: Int16Array, values: [-1, 0, 32767] },
+  { type: Uint16Array, values: [1, 2, 65535] },
+  { type: Int32Array, values: [-1, 0, 123456789] },
+  { type: Uint32Array, values: [1, 2, 4294967295] },
+  { type: Float32Array, values: [0.5, -1.5, 42.25] },
+  { type: Float64Array, values: [0.5, -1.5, 42.25] },
+  { type: BigInt64Array, values: [1n, -2n, 123456789n] },
+  { type: BigUint64Array, values: [1n, 2n, 123456789n] },
+];
+
+function createBuffer(Type, BufferType, length) {
+  const byteOffset = Type.BYTES_PER_ELEMENT;
+  const byteLength = byteOffset + (length * Type.BYTES_PER_ELEMENT);
+  return {
+    buffer: new BufferType(byteLength),
+    byteOffset,
+  };
+}
+
+function createTypedArray(Type, buffer, byteOffset, length) {
+  const template = new Type(buffer, byteOffset, length);
+  return test_typedarray_sharedarraybuffer.CreateTypedArray(template, buffer);
+}
+
+function verifyTypedArray(Type, buffer, byteOffset, values) {
+  const theArray = createTypedArray(Type, buffer, byteOffset, values.length);
+  const theArrayBuffer =
+    test_typedarray_sharedarraybuffer.GetArrayBuffer(theArray);
+
+  assert.ok(theArray instanceof Type);
+  assert.strictEqual(theArray.buffer, buffer);
+  assert.strictEqual(theArrayBuffer, buffer);
+  assert.strictEqual(theArray.byteOffset, byteOffset);
+  assert.strictEqual(theArray.length, values.length);
+
+  theArray.set(values);
+  assert.deepStrictEqual(Array.from(new Type(buffer, byteOffset, values.length)),
+                         values);
+}
+
+// Keep the existing ArrayBuffer behavior covered while focusing this test
+// on SharedArrayBuffer-backed TypedArray creation.
+{
+  const { buffer, byteOffset } = createBuffer(Uint8Array, ArrayBuffer, 3);
+  verifyTypedArray(Uint8Array, buffer, byteOffset, [1, 2, 3]);
+}
+
+// Verify all TypedArray variants can be created from SharedArrayBuffer.
+typedArrayCases.forEach(({ type, values }) => {
+  const { buffer, byteOffset } = createBuffer(type, SharedArrayBuffer,
+                                              values.length);
+  verifyTypedArray(type, buffer, byteOffset, values);
+});
+
+// Test for creating TypedArrays with SharedArrayBuffer and invalid range.
+for (const { type, values } of typedArrayCases) {
+  const { buffer, byteOffset } = createBuffer(type, SharedArrayBuffer,
+                                              values.length);
+  const template = new type(buffer, byteOffset, values.length);
+
+  assert.throws(() => {
+    test_typedarray_sharedarraybuffer.CreateTypedArray(
+      template, buffer, values.length + 1, byteOffset);
+  }, RangeError);
+}
+
+// Test for creating TypedArrays with SharedArrayBuffer and invalid alignment.
+for (const { type, values } of typedArrayCases) {
+  if (type.BYTES_PER_ELEMENT <= 1) {
+    continue;
+  }
+
+  const { buffer, byteOffset } = createBuffer(type, SharedArrayBuffer,
+                                              values.length);
+  const template = new type(buffer, byteOffset, values.length);
+
+  assert.throws(() => {
+    test_typedarray_sharedarraybuffer.CreateTypedArray(
+      template, buffer, 1, byteOffset + 1);
+  }, RangeError);
+}
+
+// Test invalid arguments.
+{
+  const template = new Uint8Array(1);
+
+  assert.throws(() => {
+    test_typedarray_sharedarraybuffer.CreateTypedArray(template, {});
+  }, { name: 'Error', message: 'Invalid argument' });
+
+  assert.throws(() => {
+    test_typedarray_sharedarraybuffer.CreateTypedArray(template, 1);
+  }, { name: 'Error', message: 'Invalid argument' });
+}

test/js-native-api/test_typedarray/test_typedarray_sharedarraybuffer.c

@@ -0,0 +1,79 @@
+// Verify napi_create_typedarray() accepts SharedArrayBuffer-backed views
+// without changing its existing error handling.
+
+#include <js_native_api.h>
+#include "../common.h"
+#include "../entry_point.h"
+
+static napi_value CreateTypedArray(napi_env env, napi_callback_info info) {
+  size_t argc = 4;
+  napi_value args[4];
+  NODE_API_CALL(env, napi_get_cb_info(env, info, &argc, args, NULL, NULL));
+
+  NODE_API_ASSERT(env, argc == 2 || argc == 4, "Wrong number of arguments");
+
+  bool is_typedarray;
+  NODE_API_CALL(env, napi_is_typedarray(env, args[0], &is_typedarray));
+  NODE_API_ASSERT(env,
+                  is_typedarray,
+                  "Wrong type of arguments. Expects a typed array as first "
+                  "argument.");
+
+  napi_typedarray_type type;
+  size_t length;
+  size_t byte_offset;
+  NODE_API_CALL(env,
+                napi_get_typedarray_info(
+                    env, args[0], &type, &length, NULL, NULL, &byte_offset));
+
+  if (argc == 4) {
+    uint32_t uint32_length;
+    NODE_API_CALL(env, napi_get_value_uint32(env, args[2], &uint32_length));
+    length = uint32_length;
+
+    uint32_t uint32_byte_offset;
+    NODE_API_CALL(env,
+                  napi_get_value_uint32(env, args[3], &uint32_byte_offset));
+    byte_offset = uint32_byte_offset;
+  }
+
+  napi_value typedarray;
+  NODE_API_CALL(env,
+                napi_create_typedarray(
+                    env, type, length, args[1], byte_offset, &typedarray));
+
+  return typedarray;
+}
+
+static napi_value GetArrayBuffer(napi_env env, napi_callback_info info) {
+  size_t argc = 1;
+  napi_value args[1];
+  NODE_API_CALL(env, napi_get_cb_info(env, info, &argc, args, NULL, NULL));
+
+  NODE_API_ASSERT(env, argc == 1, "Wrong number of arguments");
+
+  napi_value arraybuffer;
+  NODE_API_CALL(env,
+                napi_get_typedarray_info(
+                    env, args[0], NULL, NULL, NULL, &arraybuffer, NULL));
+
+  return arraybuffer;
+}
+
+EXTERN_C_START
+napi_value Init(napi_env env, napi_value exports) {
+  napi_property_descriptor descriptors[] = {
+      DECLARE_NODE_API_PROPERTY("CreateTypedArray", CreateTypedArray),
+      DECLARE_NODE_API_PROPERTY("GetArrayBuffer", GetArrayBuffer),
+  };
+
+  NODE_API_CALL(
+      env,
+      napi_define_properties(env,
+                             exports,
+                             sizeof(descriptors) / sizeof(*descriptors),
+                             descriptors));
+
+  return exports;
+}
+EXTERN_C_END