feat(napi): support External for compact mode and add JsExternal as deprecated (#2125)

crates/macro/src/compat_macro.rs

@@ -77,13 +77,23 @@ pub fn get_execute_js_code(new_fn_name: Ident, function_kind: FunctionKind) -> T
   let return_token_stream = match function_kind {
     FunctionKind::Contextless => {
       quote! {
-        Ok(Some(v)) => unsafe { v.raw() },
+        Ok(Some(v)) => unsafe {
+          napi::bindgen_prelude::ToNapiValue::to_napi_value(raw_env, v).unwrap_or_else(|e| {
+            napi::JsError::from(e).throw_into(raw_env);
+            ptr::null_mut()
+          })
+        },
         Ok(None) => ptr::null_mut(),
       }
     }
     FunctionKind::JsFunction => {
       quote! {
-        Ok(v) => unsafe { v.raw() },
+        Ok(v) => unsafe {
+          napi::bindgen_prelude::ToNapiValue::to_napi_value(raw_env, v).unwrap_or_else(|e| {
+            napi::JsError::from(e).throw_into(raw_env);
+            ptr::null_mut()
+          })
+        },
       }
     }
   };

crates/napi/src/env.rs

@@ -1,3 +1,5 @@
+#![allow(deprecated)]
+
 use std::any::{type_name, TypeId};
 use std::convert::TryInto;
 use std::ffi::CString;

crates/napi/src/js_values/mod.rs

@@ -98,6 +98,7 @@ impl TypeName for JsSymbol {
 
 impl ValidateNapiValue for JsSymbol {}
 
+#[deprecated(since = "3.0.0", note = "Please use `External` instead")]
 pub struct JsExternal(pub(crate) Value);
 
 impl TypeName for JsExternal {

examples/napi-compat-mode/src/cleanup_env.rs

@@ -1,22 +1,20 @@
 use napi::{
-  CallContext, CleanupEnvHook, ContextlessResult, Env, JsExternal, JsObject, JsUndefined, Result,
+  bindgen_prelude::External, CallContext, CleanupEnvHook, ContextlessResult, Env, JsObject,
+  JsUndefined, Result,
 };
 
 #[contextless_function]
-fn add_cleanup_hook(mut env: Env) -> ContextlessResult<JsExternal> {
+fn add_cleanup_hook(mut env: Env) -> ContextlessResult<External<CleanupEnvHook<()>>> {
   let hook = env.add_env_cleanup_hook((), |_| {
     println!("cleanup hook executed");
   })?;
-  env.create_external(hook, None).map(Some)
+  Ok(Some(External::new(hook)))
 }
 
 #[js_function(1)]
 fn remove_cleanup_hook(ctx: CallContext) -> Result<JsUndefined> {
-  let hook_external = ctx.get::<JsExternal>(0)?;
-  let hook = *ctx
-    .env
-    .get_value_external::<CleanupEnvHook<()>>(&hook_external)?;
-  ctx.env.remove_env_cleanup_hook(hook)?;
+  let hook = ctx.get::<&External<CleanupEnvHook<()>>>(0)?;
+  ctx.env.remove_env_cleanup_hook(**hook)?;
   ctx.env.get_undefined()
 }
 

examples/napi-compat-mode/src/external.rs

@@ -1,30 +1,29 @@
 use std::convert::TryInto;
 
-use napi::{CallContext, JsExternal, JsNumber, JsObject, Result};
+use napi::{bindgen_prelude::External, CallContext, JsNumber, JsObject, Result};
 
 struct NativeObject {
   count: i32,
 }
 
 #[js_function(1)]
-pub fn create_external(ctx: CallContext) -> Result<JsExternal> {
+pub fn create_external(ctx: CallContext) -> Result<External<NativeObject>> {
   let count = ctx.get::<JsNumber>(0)?.try_into()?;
   let native = NativeObject { count };
-  ctx.env.create_external(native, None)
+  Ok(External::new(native))
 }
 
 #[js_function(1)]
-pub fn create_external_with_hint(ctx: CallContext) -> Result<JsExternal> {
+pub fn create_external_with_hint(ctx: CallContext) -> Result<External<NativeObject>> {
   let count = ctx.get::<JsNumber>(0)?.try_into()?;
   let native = NativeObject { count };
-  ctx.env.create_external(native, Some(5))
+  Ok(External::new_with_size_hint(native, 5))
 }
 
 #[js_function(1)]
 pub fn get_external_count(ctx: CallContext) -> Result<JsNumber> {
-  let attached_obj = ctx.get::<JsExternal>(0)?;
-  let native_object = ctx.env.get_value_external::<NativeObject>(&attached_obj)?;
-  ctx.env.create_int32(native_object.count)
+  let attached_obj = ctx.get::<&External<NativeObject>>(0)?;
+  ctx.env.create_int32(attached_obj.count)
 }
 
 pub fn register_js(exports: &mut JsObject) -> Result<()> {