node-api: extend type-tagging to externals

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 {
@@ -4953,7 +4953,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
@@ -5239,15 +5239,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`.
@@ -5269,7 +5269,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.
@@ -6438,6 +6439,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,15 @@ 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(12);
+  const plainExternal = test_object.PlainExternal();
 
   // 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(12, external), true);
 
   // Verify that wrongly tagged objects are rejected.
   assert.strictEqual(test_object.CheckTypeTag(0, obj2), false);
@@ -180,10 +183,12 @@ 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(19, 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(12, plainExternal), false);
 }
 
 {

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

@@ -627,6 +627,29 @@ TypeTaggedInstance(napi_env env, napi_callback_info info) {
   return instance;
 }
 
+static napi_value PlainExternal(napi_env env, napi_callback_info info) {
+  napi_value instance;
+
+  NODE_API_CALL(env, napi_create_external(env, NULL, NULL, NULL, &instance));
+
+  return instance;
+}
+
+static napi_value TypeTaggedExternal(napi_env env, napi_callback_info info) {
+  size_t argc = 1;
+  uint32_t type_index;
+  napi_value instance, which_type;
+
+  NODE_API_CALL(env,
+                napi_get_cb_info(env, info, &argc, &which_type, NULL, NULL));
+  NODE_API_CALL(env, napi_get_value_uint32(env, which_type, &type_index));
+  NODE_API_CALL(env, napi_create_external(env, NULL, NULL, NULL, &instance));
+  NODE_API_CALL(env,
+                napi_type_tag_object(env, instance, &type_tags[type_index]));
+
+  return instance;
+}
+
 static napi_value
 CheckTypeTag(napi_env env, napi_callback_info info) {
   size_t argc = 2;
@@ -648,31 +671,36 @@ CheckTypeTag(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("Get", Get),
-    DECLARE_NODE_API_PROPERTY("GetNamed", GetNamed),
-    DECLARE_NODE_API_PROPERTY("GetPropertyNames", GetPropertyNames),
-    DECLARE_NODE_API_PROPERTY("GetSymbolNames", GetSymbolNames),
-    DECLARE_NODE_API_PROPERTY("GetEnumerableWritableNames", GetEnumerableWritableNames),
-    DECLARE_NODE_API_PROPERTY("GetOwnWritableNames", GetOwnWritableNames),
-    DECLARE_NODE_API_PROPERTY("GetEnumerableConfigurableNames", GetEnumerableConfigurableNames),
-    DECLARE_NODE_API_PROPERTY("GetOwnConfigurableNames", GetOwnConfigurableNames),
-    DECLARE_NODE_API_PROPERTY("Set", Set),
-    DECLARE_NODE_API_PROPERTY("SetNamed", SetNamed),
-    DECLARE_NODE_API_PROPERTY("Has", Has),
-    DECLARE_NODE_API_PROPERTY("HasNamed", HasNamed),
-    DECLARE_NODE_API_PROPERTY("HasOwn", HasOwn),
-    DECLARE_NODE_API_PROPERTY("Delete", Delete),
-    DECLARE_NODE_API_PROPERTY("New", New),
-    DECLARE_NODE_API_PROPERTY("Inflate", Inflate),
-    DECLARE_NODE_API_PROPERTY("Wrap", Wrap),
-    DECLARE_NODE_API_PROPERTY("Unwrap", Unwrap),
-    DECLARE_NODE_API_PROPERTY("TestSetProperty", TestSetProperty),
-    DECLARE_NODE_API_PROPERTY("TestHasProperty", TestHasProperty),
-    DECLARE_NODE_API_PROPERTY("TypeTaggedInstance", TypeTaggedInstance),
-    DECLARE_NODE_API_PROPERTY("CheckTypeTag", CheckTypeTag),
-    DECLARE_NODE_API_PROPERTY("TestGetProperty", TestGetProperty),
-    DECLARE_NODE_API_PROPERTY("TestFreeze", TestFreeze),
-    DECLARE_NODE_API_PROPERTY("TestSeal", TestSeal),
+      DECLARE_NODE_API_PROPERTY("Get", Get),
+      DECLARE_NODE_API_PROPERTY("GetNamed", GetNamed),
+      DECLARE_NODE_API_PROPERTY("GetPropertyNames", GetPropertyNames),
+      DECLARE_NODE_API_PROPERTY("GetSymbolNames", GetSymbolNames),
+      DECLARE_NODE_API_PROPERTY("GetEnumerableWritableNames",
+                                GetEnumerableWritableNames),
+      DECLARE_NODE_API_PROPERTY("GetOwnWritableNames", GetOwnWritableNames),
+      DECLARE_NODE_API_PROPERTY("GetEnumerableConfigurableNames",
+                                GetEnumerableConfigurableNames),
+      DECLARE_NODE_API_PROPERTY("GetOwnConfigurableNames",
+                                GetOwnConfigurableNames),
+      DECLARE_NODE_API_PROPERTY("Set", Set),
+      DECLARE_NODE_API_PROPERTY("SetNamed", SetNamed),
+      DECLARE_NODE_API_PROPERTY("Has", Has),
+      DECLARE_NODE_API_PROPERTY("HasNamed", HasNamed),
+      DECLARE_NODE_API_PROPERTY("HasOwn", HasOwn),
+      DECLARE_NODE_API_PROPERTY("Delete", Delete),
+      DECLARE_NODE_API_PROPERTY("New", New),
+      DECLARE_NODE_API_PROPERTY("Inflate", Inflate),
+      DECLARE_NODE_API_PROPERTY("Wrap", Wrap),
+      DECLARE_NODE_API_PROPERTY("Unwrap", Unwrap),
+      DECLARE_NODE_API_PROPERTY("TestSetProperty", TestSetProperty),
+      DECLARE_NODE_API_PROPERTY("TestHasProperty", TestHasProperty),
+      DECLARE_NODE_API_PROPERTY("TypeTaggedInstance", TypeTaggedInstance),
+      DECLARE_NODE_API_PROPERTY("TypeTaggedExternal", TypeTaggedExternal),
+      DECLARE_NODE_API_PROPERTY("PlainExternal", PlainExternal),
+      DECLARE_NODE_API_PROPERTY("CheckTypeTag", CheckTypeTag),
+      DECLARE_NODE_API_PROPERTY("TestGetProperty", TestGetProperty),
+      DECLARE_NODE_API_PROPERTY("TestFreeze", TestFreeze),
+      DECLARE_NODE_API_PROPERTY("TestSeal", TestSeal),
   };
 
   init_test_null(env, exports);