doc,test: improve SharedArrayBuffer typedarray test and docs

Signed-off-by: umuoy1 <burningdian@gmail.com>

Author: umuoy1

doc/api/n-api.md

@@ -2748,6 +2748,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
@@ -2779,6 +2783,9 @@ 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.
 
+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.
 

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

@@ -9,102 +9,102 @@ const assert = require('assert');
 const test_typedarray_sharedarraybuffer =
   require(`./build/${common.buildType}/test_typedarray_sharedarraybuffer`);
 
-// Test for creating Uint8Array with ArrayBuffer
-{
-  const buffer = new ArrayBuffer(16);
-  const theArray =
-    test_typedarray_sharedarraybuffer.CreateUint8Array(buffer, 4, 6);
-  const theArrayBuffer =
-    test_typedarray_sharedarraybuffer.GetArrayBuffer(theArray);
-
-  assert.ok(theArray instanceof Uint8Array);
-  assert.strictEqual(theArray.buffer, buffer);
-  assert.ok(theArrayBuffer instanceof ArrayBuffer);
-  assert.strictEqual(theArrayBuffer, buffer);
-  assert.strictEqual(theArray.byteOffset, 4);
-  assert.strictEqual(theArray.length, 6);
+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: Float16Array, values: [0.5, -1.5, 42.25] },
+  { 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,
+  };
+}
 
-  theArray.set([1, 2, 3, 4, 5, 6]);
-  assert.deepStrictEqual(Array.from(new Uint8Array(buffer, 4, 6)),
-                         [1, 2, 3, 4, 5, 6]);
+function createTypedArray(Type, buffer, byteOffset, length) {
+  const template = new Type(buffer, byteOffset, length);
+  return test_typedarray_sharedarraybuffer.CreateTypedArray(template, buffer);
 }
 
-// Test for creating Uint8Array with SharedArrayBuffer
-{
-  const buffer = new SharedArrayBuffer(16);
-  const theArray =
-    test_typedarray_sharedarraybuffer.CreateUint8Array(buffer, 4, 6);
+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 Uint8Array);
+  assert.ok(theArray instanceof Type);
   assert.strictEqual(theArray.buffer, buffer);
-  assert.ok(theArrayBuffer instanceof SharedArrayBuffer);
   assert.strictEqual(theArrayBuffer, buffer);
-  assert.strictEqual(theArray.byteOffset, 4);
-  assert.strictEqual(theArray.length, 6);
+  assert.strictEqual(theArray.byteOffset, byteOffset);
+  assert.strictEqual(theArray.length, values.length);
 
-  theArray.set([6, 5, 4, 3, 2, 1]);
-  assert.deepStrictEqual(Array.from(new Uint8Array(buffer, 4, 6)),
-                         [6, 5, 4, 3, 2, 1]);
+  theArray.set(values);
+  assert.deepStrictEqual(Array.from(new Type(buffer, byteOffset, values.length)),
+                         values);
 }
 
-// Test for creating Uint16Array with SharedArrayBuffer
+// Keep the existing ArrayBuffer behavior covered while focusing this test
+// on SharedArrayBuffer-backed TypedArray creation.
 {
-  const buffer = new SharedArrayBuffer(24);
-  const theArray =
-    test_typedarray_sharedarraybuffer.CreateUint16Array(buffer, 4, 4);
-
-  assert.ok(theArray instanceof Uint16Array);
-  assert.strictEqual(theArray.buffer, buffer);
-  assert.strictEqual(theArray.byteOffset, 4);
-  assert.strictEqual(theArray.length, 4);
-
-  theArray.set([1, 2, 3, 65535]);
-  assert.deepStrictEqual(Array.from(new Uint16Array(buffer, 4, 4)),
-                         [1, 2, 3, 65535]);
+  const { buffer, byteOffset } = createBuffer(Uint8Array, ArrayBuffer, 3);
+  verifyTypedArray(Uint8Array, buffer, byteOffset, [1, 2, 3]);
 }
 
-// Test for creating Int32Array with SharedArrayBuffer
-{
-  const buffer = new SharedArrayBuffer(32);
-  const theArray =
-    test_typedarray_sharedarraybuffer.CreateInt32Array(buffer, 8, 3);
-
-  assert.ok(theArray instanceof Int32Array);
-  assert.strictEqual(theArray.buffer, buffer);
-  assert.strictEqual(theArray.byteOffset, 8);
-  assert.strictEqual(theArray.length, 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);
+});
 
-  theArray.set([-1, 0, 123456789]);
-  assert.deepStrictEqual(Array.from(new Int32Array(buffer, 8, 3)),
-                         [-1, 0, 123456789]);
-}
-
-// Test for creating TypedArrays with SharedArrayBuffer and invalid range
-{
-  const buffer = new SharedArrayBuffer(8);
+// 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.CreateUint8Array(buffer, 9, 0);
+    test_typedarray_sharedarraybuffer.CreateTypedArray(
+      template, buffer, values.length + 1, byteOffset);
   }, RangeError);
+}
 
-  assert.throws(() => {
-    test_typedarray_sharedarraybuffer.CreateUint16Array(buffer, 0, 5);
-  }, 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.CreateUint16Array(buffer, 1, 1);
+    test_typedarray_sharedarraybuffer.CreateTypedArray(
+      template, buffer, 1, byteOffset + 1);
   }, RangeError);
 }
 
-// Test invalid arguments
+// Test invalid arguments.
 {
+  const template = new Uint8Array(1);
+
   assert.throws(() => {
-    test_typedarray_sharedarraybuffer.CreateUint8Array({}, 0, 1);
+    test_typedarray_sharedarraybuffer.CreateTypedArray(template, {});
   }, { name: 'Error', message: 'Invalid argument' });
 
   assert.throws(() => {
-    test_typedarray_sharedarraybuffer.CreateUint8Array(1, 0, 1);
+    test_typedarray_sharedarraybuffer.CreateTypedArray(template, 1);
   }, { name: 'Error', message: 'Invalid argument' });
 }

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

@@ -5,41 +5,46 @@
 #include "../common.h"
 #include "../entry_point.h"
 
-static napi_value CreateTypedArray(napi_env env,
-                                   napi_callback_info info,
-                                   napi_typedarray_type type) {
-  size_t argc = 3;
-  napi_value args[3];
+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 == 3, "Wrong number of arguments");
+  NODE_API_ASSERT(env, argc == 2 || argc == 4, "Wrong number of arguments");
 
-  uint32_t byte_offset;
-  NODE_API_CALL(env, napi_get_value_uint32(env, args[1], &byte_offset));
+  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.");
 
-  uint32_t length;
-  NODE_API_CALL(env, napi_get_value_uint32(env, args[2], &length));
+  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[0], byte_offset, &typedarray));
+                    env, type, length, args[1], byte_offset, &typedarray));
 
   return typedarray;
 }
 
-static napi_value CreateUint8Array(napi_env env, napi_callback_info info) {
-  return CreateTypedArray(env, info, napi_uint8_array);
-}
-
-static napi_value CreateUint16Array(napi_env env, napi_callback_info info) {
-  return CreateTypedArray(env, info, napi_uint16_array);
-}
-
-static napi_value CreateInt32Array(napi_env env, napi_callback_info info) {
-  return CreateTypedArray(env, info, napi_int32_array);
-}
-
 static napi_value GetArrayBuffer(napi_env env, napi_callback_info info) {
   size_t argc = 1;
   napi_value args[1];
@@ -58,9 +63,7 @@ static napi_value GetArrayBuffer(napi_env env, napi_callback_info info) {
 EXTERN_C_START
 napi_value Init(napi_env env, napi_value exports) {
   napi_property_descriptor descriptors[] = {
-      DECLARE_NODE_API_PROPERTY("CreateUint8Array", CreateUint8Array),
-      DECLARE_NODE_API_PROPERTY("CreateUint16Array", CreateUint16Array),
-      DECLARE_NODE_API_PROPERTY("CreateInt32Array", CreateInt32Array),
+      DECLARE_NODE_API_PROPERTY("CreateTypedArray", CreateTypedArray),
       DECLARE_NODE_API_PROPERTY("GetArrayBuffer", GetArrayBuffer),
   };