feat(neon): Extractors

Extractors allow quickly getting JavaScript arguments as Rust values. In addition to immediate ergonomics and performance improvements, extractors set a foundation for future proc macros.

.cargo/config.toml

@@ -1,7 +1,7 @@
 [alias]
 # Neon defines mutually exclusive feature flags which prevents using `cargo clippy --all-features`
 # The following aliases simplify linting the entire workspace
-neon-check = " check  --all --all-targets --features napi-experimental,futures,external-buffers"
-neon-clippy = "clippy --all --all-targets --features napi-experimental,futures,external-buffers -- -A clippy::missing_safety_doc"
-neon-test = "  test   --all               --features=doc-dependencies,doc-comment,napi-experimental,futures,external-buffers"
-neon-doc = "   rustdoc -p neon            --features=doc-dependencies,napi-experimental,futures,external-buffers,sys -- --cfg docsrs"
+neon-check = " check  --all --all-targets --features napi-experimental,futures,external-buffers,serde"
+neon-clippy = "clippy --all --all-targets --features napi-experimental,futures,external-buffers,serde -- -A clippy::missing_safety_doc"
+neon-test = "  test   --all               --features=doc-dependencies,doc-comment,napi-experimental,futures,external-buffers,serde"
+neon-doc = "   rustdoc -p neon            --features=doc-dependencies,napi-experimental,futures,external-buffers,sys,serde -- --cfg docsrs"

crates/neon/Cargo.toml

@@ -32,6 +32,8 @@ aquamarine = { version = "0.3.2", optional = true }
 easy-cast = { version = "0.5.2", optional = true }
 doc-comment = { version = "0.3.3", optional = true }
 send_wrapper = "0.6.0"
+serde = { version = "1.0.197", optional = true }
+serde_json = { version = "1.0.114", optional = true }
 
 [dependencies.tokio]
 version = "1.34.0"
@@ -42,6 +44,9 @@ optional = true
 [features]
 default = ["napi-8"]
 
+# Enable extracting values by serializing to JSON
+serde = ["dep:serde", "dep:serde_json"]
+
 # Enable the creation of external binary buffers. This is disabled by default
 # since these APIs fail at runtime in environments that enable the V8 memory
 # cage (such as Electron: https://www.electronjs.org/blog/v8-memory-cage).

crates/neon/src/context/internal.rs

@@ -20,7 +20,7 @@ impl From<raw::Env> for Env {
 
 thread_local! {
     #[allow(unused)]
-    pub(crate) static IS_RUNNING: RefCell<bool> = RefCell::new(false);
+    pub(crate) static IS_RUNNING: RefCell<bool> = const { RefCell::new(false) };
 }
 
 impl Env {

crates/neon/src/context/mod.rs

@@ -157,6 +157,7 @@ use crate::{
     types::{
         boxed::{Finalize, JsBox},
         error::JsError,
+        extract::FromArgs,
         private::ValueInternal,
         Deferred, JsArray, JsArrayBuffer, JsBoolean, JsBuffer, JsFunction, JsNull, JsNumber,
         JsObject, JsPromise, JsString, JsUndefined, JsValue, StringResult, Value,
@@ -212,6 +213,36 @@ impl CallbackInfo<'_> {
             local
         }
     }
+
+    pub(crate) fn argv_exact<'b, C: Context<'b>, const N: usize>(
+        &self,
+        cx: &mut C,
+    ) -> [Handle<'b, JsValue>; N] {
+        use std::ptr;
+
+        let mut argv = [JsValue::new_internal(ptr::null_mut()); N];
+        let mut argc = argv.len();
+
+        // # Safety
+        // * Node-API fills empty slots with `undefined
+        // * `Handle` and `JsValue` are transparent wrappers around a raw pointer
+        unsafe {
+            assert_eq!(
+                sys::get_cb_info(
+                    cx.env().to_raw(),
+                    self.info,
+                    &mut argc,
+                    argv.as_mut_ptr().cast(),
+                    ptr::null_mut(),
+                    ptr::null_mut(),
+                ),
+                sys::Status::Ok,
+            );
+        }
+
+        // Empty values will be filled with `undefined`
+        argv
+    }
 }
 
 /// Indicates whether a function was called with `new`.
@@ -683,6 +714,55 @@ impl<'a> FunctionContext<'a> {
     pub fn this_value(&mut self) -> Handle<'a, JsValue> {
         JsValue::new_internal(self.info.this(self))
     }
+
+    /// Extract Rust data from the JavaScript arguments.
+    ///
+    /// This is frequently more efficient and ergonomic than getting arguments
+    /// individually. See the [`extract`](crate::types::extract) module documentation
+    /// for more examples.
+    ///
+    /// ```
+    /// # use neon::{prelude::*, types::extract::*};
+    /// fn add(mut cx: FunctionContext) -> JsResult<JsNumber> {
+    ///     let (a, b): (f64, f64) = cx.args()?;
+    ///
+    ///     Ok(cx.number(a + b))
+    /// }
+    /// ```
+    pub fn args<T>(&mut self) -> NeonResult<T>
+    where
+        T: FromArgs<'a>,
+    {
+        T::from_args(self)
+    }
+
+    /// Extract Rust data from the JavaScript arguments.
+    ///
+    /// Similar to [`FunctionContext::args`], but does not throw a JavaScript exception on errors. Useful
+    /// for function overloading.
+    ///
+    /// ```
+    /// # use neon::{prelude::*, types::extract::*};
+    /// fn combine(mut cx: FunctionContext) -> JsResult<JsValue> {
+    ///     if let Some((a, b)) = cx.args_opt::<(f64, f64)>()? {
+    ///         return Ok(cx.number(a + b).upcast());
+    ///     }
+    ///
+    ///     let (a, b): (String, String) = cx.args()?;
+    ///
+    ///     Ok(cx.string(a + &b).upcast())
+    /// }
+    /// ```
+    pub fn args_opt<T>(&mut self) -> NeonResult<Option<T>>
+    where
+        T: FromArgs<'a>,
+    {
+        T::from_args_opt(self)
+    }
+
+    pub(crate) fn argv<const N: usize>(&mut self) -> [Handle<'a, JsValue>; N] {
+        self.info.argv_exact(self)
+    }
 }
 
 impl<'a> ContextInternal<'a> for FunctionContext<'a> {

crates/neon/src/lib.rs

@@ -78,6 +78,8 @@
 //! [supported]: https://github.com/neon-bindings/neon#platform-support
 #![cfg_attr(docsrs, feature(doc_cfg))]
 
+extern crate core;
+
 pub mod context;
 pub mod event;
 pub mod handle;
@@ -88,6 +90,7 @@ pub mod reflect;
 pub mod result;
 #[cfg(not(feature = "sys"))]
 mod sys;
+#[cfg_attr(docsrs, doc(cfg(feature = "napi-6")))]
 #[cfg(feature = "napi-6")]
 pub mod thread;
 // To use the #[aquamarine] attribute on the top-level neon::types module docs, we have to

crates/neon/src/types_impl/bigint.rs

@@ -428,8 +428,8 @@ unsafe impl TransparentNoCopyWrapper for JsBigInt {
 }
 
 impl private::ValueInternal for JsBigInt {
-    fn name() -> String {
-        "BigInt".to_string()
+    fn name() -> &'static str {
+        "BigInt"
     }
 
     fn is_typeof<Other: Value>(env: Env, other: &Other) -> bool {

crates/neon/src/types_impl/boxed.rs

@@ -183,8 +183,8 @@ unsafe impl<T: 'static> TransparentNoCopyWrapper for JsBox<T> {
 }
 
 impl<T: 'static> ValueInternal for JsBox<T> {
-    fn name() -> String {
-        any::type_name::<Self>().to_string()
+    fn name() -> &'static str {
+        any::type_name::<Self>()
     }
 
     fn is_typeof<Other: Value>(env: Env, other: &Other) -> bool {

crates/neon/src/types_impl/buffer/types.rs

@@ -124,8 +124,8 @@ unsafe impl TransparentNoCopyWrapper for JsBuffer {
 }
 
 impl ValueInternal for JsBuffer {
-    fn name() -> String {
-        "Buffer".to_string()
+    fn name() -> &'static str {
+        "Buffer"
     }
 
     fn is_typeof<Other: Value>(env: Env, other: &Other) -> bool {
@@ -341,8 +341,8 @@ unsafe impl TransparentNoCopyWrapper for JsArrayBuffer {
 }
 
 impl ValueInternal for JsArrayBuffer {
-    fn name() -> String {
-        "JsArrayBuffer".to_string()
+    fn name() -> &'static str {
+        "JsArrayBuffer"
     }
 
     fn is_typeof<Other: Value>(env: Env, other: &Other) -> bool {
@@ -791,8 +791,8 @@ macro_rules! impl_typed_array {
         impl Object for JsTypedArray<$etyp> {}
 
         impl ValueInternal for JsTypedArray<$etyp> {
-            fn name() -> String {
-                stringify!($typ).to_string()
+            fn name() -> &'static str {
+                stringify!($typ)
             }
 
             fn is_typeof<Other: Value>(env: Env, other: &Other) -> bool {

crates/neon/src/types_impl/date.rs

@@ -160,8 +160,8 @@ impl JsDate {
 }
 
 impl ValueInternal for JsDate {
-    fn name() -> String {
-        "object".to_string()
+    fn name() -> &'static str {
+        "object"
     }
 
     fn is_typeof<Other: Value>(env: Env, other: &Other) -> bool {

crates/neon/src/types_impl/error.rs

@@ -48,8 +48,8 @@ unsafe impl TransparentNoCopyWrapper for JsError {
 }
 
 impl ValueInternal for JsError {
-    fn name() -> String {
-        "Error".to_string()
+    fn name() -> &'static str {
+        "Error"
     }
 
     fn is_typeof<Other: Value>(env: Env, other: &Other) -> bool {