node-api: extend type-tagging to externals

Since externals behave as JavaScript objects on the JavaScript side,
allow them to be type-tagged.

Signed-off-by: Gabriel Schulhof <gabrielschulhof@gmail.com>
PR-URL: #47141
Reviewed-By: Michael Dawson <midawson@redhat.com>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>

Author: gabrielschulhof

doc/api/n-api.md

@@ -733,13 +733,13 @@ napiVersion: 8
 -->
 
 A 128-bit value stored as two unsigned 64-bit integers. It serves as a UUID
-with which JavaScript objects can be "tagged" in order to ensure that they are
-of a certain type. This is a stronger check than [`napi_instanceof`][], because
-the latter can report a false positive if the object's prototype has been
-manipulated. Type-tagging is most useful in conjunction with [`napi_wrap`][]
-because it ensures that the pointer retrieved from a wrapped object can be
-safely cast to the native type corresponding to the type tag that had been
-previously applied to the JavaScript object.
+with which JavaScript objects or [externals][] can be "tagged" in order to
+ensure that they are of a certain type. This is a stronger check than
+[`napi_instanceof`][], because the latter can report a false positive if the
+object's prototype has been manipulated. Type-tagging is most useful in
+conjunction with [`napi_wrap`][] because it ensures that the pointer retrieved
+from a wrapped object can be safely cast to the native type corresponding to the
+type tag that had been previously applied to the JavaScript object.
 
 ```c
 typedef struct {
@@ -4967,7 +4967,7 @@ To this end, Node-API provides type-tagging capabilities.
 
 A type tag is a 128-bit integer unique to the addon. Node-API provides the
 `napi_type_tag` structure for storing a type tag. When such a value is passed
-along with a JavaScript object stored in a `napi_value` to
+along with a JavaScript object or [external][] stored in a `napi_value` to
 `napi_type_tag_object()`, the JavaScript object will be "marked" with the
 type tag. The "mark" is invisible on the JavaScript side. When a JavaScript
 object arrives into a native binding, `napi_check_object_type_tag()` can be used
@@ -5253,15 +5253,15 @@ napi_status napi_type_tag_object(napi_env env,
 ```
 
 * `[in] env`: The environment that the API is invoked under.
-* `[in] js_object`: The JavaScript object to be marked.
+* `[in] js_object`: The JavaScript object or [external][] to be marked.
 * `[in] type_tag`: The tag with which the object is to be marked.
 
 Returns `napi_ok` if the API succeeded.
 
-Associates the value of the `type_tag` pointer with the JavaScript object.
-`napi_check_object_type_tag()` can then be used to compare the tag that was
-attached to the object with one owned by the addon to ensure that the object
-has the right type.
+Associates the value of the `type_tag` pointer with the JavaScript object or
+[external][]. `napi_check_object_type_tag()` can then be used to compare the tag
+that was attached to the object with one owned by the addon to ensure that the
+object has the right type.
 
 If the object already has an associated type tag, this API will return
 `napi_invalid_arg`.
@@ -5283,7 +5283,8 @@ napi_status napi_check_object_type_tag(napi_env env,
 ```
 
 * `[in] env`: The environment that the API is invoked under.
-* `[in] js_object`: The JavaScript object whose type tag to examine.
+* `[in] js_object`: The JavaScript object or [external][] whose type tag to
+  examine.
 * `[in] type_tag`: The tag with which to compare any tag found on the object.
 * `[out] result`: Whether the type tag given matched the type tag on the
   object. `false` is also returned if no type tag was found on the object.
@@ -6453,6 +6454,8 @@ the add-on's file name during loading.
 [async_hooks `type`]: async_hooks.md#type
 [context-aware addons]: addons.md#context-aware-addons
 [docs]: https://github.com/nodejs/node-addon-api#api-documentation
+[external]: #napi_create_external
+[externals]: #napi_create_external
 [global scope]: globals.md
 [gyp-next]: https://github.com/nodejs/gyp-next
 [module scope]: modules.md#the-module-scope

test/js-native-api/test_object/test.js

@@ -165,12 +165,26 @@ assert.strictEqual(newObject.test_string, 'test string');
   const obj2 = test_object.TypeTaggedInstance(1);
   const obj3 = test_object.TypeTaggedInstance(2);
   const obj4 = test_object.TypeTaggedInstance(3);
+  const external = test_object.TypeTaggedExternal(2);
+  const plainExternal = test_object.PlainExternal();
+
+  // Verify that we do not allow type tag indices greater than the largest
+  // available index.
+  assert.throws(() => test_object.TypeTaggedInstance(39), {
+    name: 'RangeError',
+    message: 'Invalid type index',
+  });
+  assert.throws(() => test_object.TypeTaggedExternal(39), {
+    name: 'RangeError',
+    message: 'Invalid type index',
+  });
 
   // Verify that type tags are correctly accepted.
   assert.strictEqual(test_object.CheckTypeTag(0, obj1), true);
   assert.strictEqual(test_object.CheckTypeTag(1, obj2), true);
   assert.strictEqual(test_object.CheckTypeTag(2, obj3), true);
   assert.strictEqual(test_object.CheckTypeTag(3, obj4), true);
+  assert.strictEqual(test_object.CheckTypeTag(2, external), true);
 
   // Verify that wrongly tagged objects are rejected.
   assert.strictEqual(test_object.CheckTypeTag(0, obj2), false);
@@ -180,10 +194,19 @@ assert.strictEqual(newObject.test_string, 'test string');
   assert.strictEqual(test_object.CheckTypeTag(2, obj4), false);
   assert.strictEqual(test_object.CheckTypeTag(3, obj3), false);
   assert.strictEqual(test_object.CheckTypeTag(4, obj3), false);
+  assert.strictEqual(test_object.CheckTypeTag(0, external), false);
+  assert.strictEqual(test_object.CheckTypeTag(1, external), false);
+  assert.strictEqual(test_object.CheckTypeTag(3, external), false);
+  assert.strictEqual(test_object.CheckTypeTag(4, external), false);
 
   // Verify that untagged objects are rejected.
   assert.strictEqual(test_object.CheckTypeTag(0, {}), false);
   assert.strictEqual(test_object.CheckTypeTag(1, {}), false);
+  assert.strictEqual(test_object.CheckTypeTag(0, plainExternal), false);
+  assert.strictEqual(test_object.CheckTypeTag(1, plainExternal), false);
+  assert.strictEqual(test_object.CheckTypeTag(2, plainExternal), false);
+  assert.strictEqual(test_object.CheckTypeTag(3, plainExternal), false);
+  assert.strictEqual(test_object.CheckTypeTag(4, plainExternal), false);
 }
 
 {

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

@@ -605,13 +605,23 @@ static napi_value TestSeal(napi_env env,
 }
 
 // We create two type tags. They are basically 128-bit UUIDs.
-static const napi_type_tag type_tags[5] = {
-  { 0xdaf987b3cc62481a, 0xb745b0497f299531 },
-  { 0xbb7936c374084d9b, 0xa9548d0762eeedb9 },
-  { 0xa5ed9ce2e4c00c38, 0 },
-  { 0, 0 },
-  { 0xa5ed9ce2e4c00c38, 0xdaf987b3cc62481a },
+#define TYPE_TAG_COUNT 5
+static const napi_type_tag type_tags[TYPE_TAG_COUNT] = {
+    {0xdaf987b3cc62481a, 0xb745b0497f299531},
+    {0xbb7936c374084d9b, 0xa9548d0762eeedb9},
+    {0xa5ed9ce2e4c00c38, 0},
+    {0, 0},
+    {0xa5ed9ce2e4c00c38, 0xdaf987b3cc62481a},
 };
+#define VALIDATE_TYPE_INDEX(env, type_index)                                   \
+  do {                                                                         \
+    if ((type_index) >= TYPE_TAG_COUNT) {                                      \
+      NODE_API_CALL((env),                                                     \
+                    napi_throw_range_error((env),                              \
+                                           "NODE_API_TEST_INVALID_TYPE_INDEX", \
+                                           "Invalid type index"));             \
+    }                                                                          \
+  } while (0)
 
 static napi_value
 TypeTaggedInstance(napi_env env, napi_callback_info info) {