Move interop and module utilities from boa_interop into boa_engine (#4218)

Migrated module and function interop traits and JS argument handling functionality into the `boa_engine` crate for better modularity.

Deprecated certain exports in `boa_interop` and updated references across the project to reflect the changes, to maintain backward compatibility, at least until we kill `boa_interop` for good.

Author: hansl

core/engine/src/interop/into_js_arguments.rs

@@ -0,0 +1,341 @@
+use boa_engine::object::Object;
+use boa_engine::value::TryFromJs;
+use boa_engine::{Context, JsNativeError, JsResult, JsValue, NativeObject};
+use boa_gc::{GcRef, GcRefMut};
+use std::ops::Deref;
+
+/// Create a Rust value from a JS argument. This trait is used to
+/// convert arguments from JS to Rust types. It allows support
+/// for optional arguments or rest arguments.
+pub trait TryFromJsArgument<'a>: Sized {
+    /// Try to convert a JS argument into a Rust value, returning the
+    /// value and the rest of the arguments to be parsed.
+    ///
+    /// # Errors
+    /// Any parsing errors that may occur during the conversion.
+    fn try_from_js_argument(
+        this: &'a JsValue,
+        rest: &'a [JsValue],
+        context: &mut Context,
+    ) -> JsResult<(Self, &'a [JsValue])>;
+}
+
+impl<'a, T: TryFromJs> TryFromJsArgument<'a> for T {
+    fn try_from_js_argument(
+        _: &'a JsValue,
+        rest: &'a [JsValue],
+        context: &mut Context,
+    ) -> JsResult<(Self, &'a [JsValue])> {
+        match rest.split_first() {
+            Some((first, rest)) => Ok((first.try_js_into(context)?, rest)),
+            None => T::try_from_js(&JsValue::undefined(), context).map(|v| (v, rest)),
+        }
+    }
+}
+
+/// An argument that would be ignored in a JS function. This is equivalent of typing
+/// `()` in Rust functions argument, but more explicit.
+#[derive(Debug, Clone, Copy)]
+pub struct Ignore;
+
+impl<'a> TryFromJsArgument<'a> for Ignore {
+    fn try_from_js_argument(
+        _this: &'a JsValue,
+        rest: &'a [JsValue],
+        _: &mut Context,
+    ) -> JsResult<(Self, &'a [JsValue])> {
+        Ok((Ignore, &rest[1..]))
+    }
+}
+
+/// An argument that when used in a JS function will empty the list
+/// of JS arguments as `JsValue`s. This can be used for having the
+/// rest of the arguments in a function. It should be the last
+/// argument of your function, before the `Context` argument if any.
+///
+/// For example,
+/// ```
+/// # use boa_engine::{Context, JsValue, IntoJsFunctionCopied};
+/// # use boa_engine::interop::JsRest;
+/// # let mut context = Context::default();
+/// let sums = (|args: JsRest, context: &mut Context| -> i32 {
+///     args.iter()
+///         .map(|i| i.try_js_into::<i32>(context).unwrap())
+///         .sum::<i32>()
+/// })
+/// .into_js_function_copied(&mut context);
+///
+/// let result = sums
+///     .call(
+///         &JsValue::undefined(),
+///         &[JsValue::from(1), JsValue::from(2), JsValue::from(3)],
+///         &mut context,
+///     )
+///     .unwrap();
+/// assert_eq!(result, JsValue::new(6));
+/// ```
+#[derive(Debug, Clone)]
+pub struct JsRest<'a>(pub &'a [JsValue]);
+
+#[allow(unused)]
+impl<'a> JsRest<'a> {
+    /// Consumes the `JsRest` and returns the inner list of `JsValue`.
+    #[must_use]
+    pub fn into_inner(self) -> &'a [JsValue] {
+        self.0
+    }
+
+    /// Transforms the `JsRest` into a `Vec<JsValue>`.
+    #[must_use]
+    pub fn to_vec(self) -> Vec<JsValue> {
+        self.0.to_vec()
+    }
+
+    /// Returns an iterator over the inner list of `JsValue`.
+    pub fn iter(&self) -> impl Iterator<Item = &JsValue> {
+        self.0.iter()
+    }
+
+    /// Returns the length of the inner list of `JsValue`.
+    #[must_use]
+    pub fn len(&self) -> usize {
+        self.0.len()
+    }
+
+    /// Returns `true` if the inner list of `JsValue` is empty.
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.0.is_empty()
+    }
+}
+
+impl<'a> From<&'a [JsValue]> for JsRest<'a> {
+    fn from(values: &'a [JsValue]) -> Self {
+        Self(values)
+    }
+}
+
+impl<'a> IntoIterator for JsRest<'a> {
+    type Item = &'a JsValue;
+    type IntoIter = std::slice::Iter<'a, JsValue>;
+
+    fn into_iter(self) -> Self::IntoIter {
+        self.into_inner().iter()
+    }
+}
+
+/// An argument that when used in a JS function will capture all
+/// the arguments that can be converted to `T`. The first argument
+/// that cannot be converted to `T` will stop the conversion.
+///
+/// For example,
+/// ```
+/// # use boa_engine::{Context, JsValue, IntoJsFunctionCopied};
+/// # use boa_engine::interop::JsAll;
+/// # let mut context = Context::default();
+/// let sums = (|args: JsAll<i32>, context: &mut Context| -> i32 { args.iter().sum() })
+///     .into_js_function_copied(&mut context);
+///
+/// let result = sums
+///     .call(
+///         &JsValue::undefined(),
+///         &[
+///             JsValue::from(1),
+///             JsValue::from(2),
+///             JsValue::from(3),
+///             JsValue::from(true),
+///             JsValue::from(4),
+///         ],
+///         &mut context,
+///     )
+///     .unwrap();
+/// assert_eq!(result, JsValue::new(6));
+/// ```
+#[derive(Debug, Clone)]
+pub struct JsAll<T: TryFromJs>(pub Vec<T>);
+
+impl<T: TryFromJs> JsAll<T> {
+    /// Consumes the `JsAll` and returns the inner list of `T`.
+    #[must_use]
+    pub fn into_inner(self) -> Vec<T> {
+        self.0
+    }
+
+    /// Returns an iterator over the inner list of `T`.
+    pub fn iter(&self) -> impl Iterator<Item = &T> {
+        self.0.iter()
+    }
+
+    /// Returns a mutable iterator over the inner list of `T`.
+    pub fn iter_mut(&mut self) -> impl Iterator<Item = &mut T> {
+        self.0.iter_mut()
+    }
+
+    /// Returns the length of the inner list of `T`.
+    #[must_use]
+    pub fn len(&self) -> usize {
+        self.0.len()
+    }
+
+    /// Returns `true` if the inner list of `T` is empty.
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.0.is_empty()
+    }
+}
+
+impl<'a, T: TryFromJs> TryFromJsArgument<'a> for JsAll<T> {
+    fn try_from_js_argument(
+        _this: &'a JsValue,
+        mut rest: &'a [JsValue],
+        context: &mut Context,
+    ) -> JsResult<(Self, &'a [JsValue])> {
+        let mut values = Vec::new();
+
+        while !rest.is_empty() {
+            match rest[0].try_js_into(context) {
+                Ok(value) => {
+                    values.push(value);
+                    rest = &rest[1..];
+                }
+                Err(_) => break,
+            }
+        }
+        Ok((JsAll(values), rest))
+    }
+}
+
+/// Captures the `this` value in a JS function. Although this can be
+/// specified multiple times as argument, it will always be filled
+/// with clone of the same value.
+#[derive(Debug, Clone)]
+pub struct JsThis<T: TryFromJs>(pub T);
+
+impl<'a, T: TryFromJs> TryFromJsArgument<'a> for JsThis<T> {
+    fn try_from_js_argument(
+        this: &'a JsValue,
+        rest: &'a [JsValue],
+        context: &mut Context,
+    ) -> JsResult<(Self, &'a [JsValue])> {
+        Ok((JsThis(this.try_js_into(context)?), rest))
+    }
+}
+
+impl<T: TryFromJs> Deref for JsThis<T> {
+    type Target = T;
+
+    fn deref(&self) -> &Self::Target {
+        &self.0
+    }
+}
+
+/// Captures a class instance from the `this` value in a JS function. The class
+/// will be a non-mutable reference of Rust type `T`, if it is an instance of `T`.
+///
+/// To have more flexibility on the parsing of the `this` value, you can use the
+/// [`JsThis`] capture instead.
+#[derive(Debug, Clone)]
+pub struct JsClass<T: NativeObject> {
+    inner: boa_engine::JsObject<T>,
+}
+
+impl<T: NativeObject> JsClass<T> {
+    /// Borrow a reference to the class instance of type `T`.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the object is currently borrowed.
+    ///
+    /// This does not panic if the type is wrong, as the type is checked
+    /// during the construction of the `JsClass` instance.
+    #[must_use]
+    pub fn borrow(&self) -> GcRef<'_, T> {
+        GcRef::map(self.inner.borrow(), |obj| obj.data())
+    }
+
+    /// Borrow a mutable reference to the class instance of type `T`.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the object is currently mutably borrowed.
+    #[must_use]
+    pub fn borrow_mut(&self) -> GcRefMut<'_, Object<T>, T> {
+        GcRefMut::map(self.inner.borrow_mut(), |obj| obj.data_mut())
+    }
+}
+
+impl<T: NativeObject + Clone> JsClass<T> {
+    /// Clones the inner class instance.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the inner object is currently borrowed mutably.
+    #[must_use]
+    pub fn clone_inner(&self) -> T {
+        self.inner.borrow().data().clone()
+    }
+}
+
+impl<'a, T: NativeObject + 'static> TryFromJsArgument<'a> for JsClass<T> {
+    fn try_from_js_argument(
+        this: &'a JsValue,
+        rest: &'a [JsValue],
+        _context: &mut Context,
+    ) -> JsResult<(Self, &'a [JsValue])> {
+        if let Some(object) = this.as_object() {
+            if let Ok(inner) = object.clone().downcast::<T>() {
+                return Ok((JsClass { inner }, rest));
+            }
+        }
+
+        Err(JsNativeError::typ()
+            .with_message("invalid this for class method")
+            .into())
+    }
+}
+
+/// Captures a [`ContextData`] data from the [`Context`] as a JS function argument,
+/// based on its type.
+///
+/// The host defined type must implement [`Clone`], otherwise the borrow
+/// checker would not be able to ensure the safety of the context while
+/// making the function call. Because of this, it is recommended to use
+/// types that are cheap to clone.
+///
+/// For example,
+/// ```
+/// # use boa_engine::{Context, Finalize, JsData, JsValue, Trace, IntoJsFunctionCopied};
+/// # use boa_engine::interop::ContextData;
+///
+/// #[derive(Clone, Debug, Finalize, JsData, Trace)]
+/// struct CustomHostDefinedStruct {
+///     #[unsafe_ignore_trace]
+///     pub counter: usize,
+/// }
+/// let mut context = Context::default();
+/// context.insert_data(CustomHostDefinedStruct { counter: 123 });
+/// let f = (|ContextData(host): ContextData<CustomHostDefinedStruct>| host.counter + 1)
+///     .into_js_function_copied(&mut context);
+///
+/// assert_eq!(
+///     f.call(&JsValue::undefined(), &[], &mut context),
+///     Ok(JsValue::new(124))
+/// );
+/// ```
+#[derive(Debug, Clone)]
+pub struct ContextData<T: Clone>(pub T);
+
+impl<'a, T: NativeObject + Clone> TryFromJsArgument<'a> for ContextData<T> {
+    fn try_from_js_argument(
+        _this: &'a JsValue,
+        rest: &'a [JsValue],
+        context: &mut Context,
+    ) -> JsResult<(Self, &'a [JsValue])> {
+        match context.get_data::<T>() {
+            Some(value) => Ok((ContextData(value.clone()), rest)),
+            None => Err(JsNativeError::typ()
+                .with_message("Context data not found")
+                .into()),
+        }
+    }
+}

…re/interop/src/into_js_function_impls.rs …ne/src/interop/into_js_function_impls.rscore/interop/src/into_js_function_impls.rs renamed to core/engine/src/interop/into_js_function_impls.rs core/interop/src/into_js_function_impls.rs renamed to core/engine/src/interop/into_js_function_impls.rs

@@ -1,12 +1,11 @@
 //! Implementations of the `IntoJsFunction` trait for various function signatures.
 
+use super::private::IntoJsFunctionSealed;
+use super::{IntoJsFunctionCopied, UnsafeIntoJsFunction};
+use crate::interop::{JsRest, TryFromJsArgument};
+use crate::{js_string, Context, JsError, NativeFunction, TryIntoJsResult};
 use std::cell::RefCell;
 
-use boa_engine::{js_string, Context, JsError, NativeFunction, TryIntoJsResult};
-
-use crate::private::IntoJsFunctionSealed;
-use crate::{IntoJsFunctionCopied, JsRest, TryFromJsArgument, UnsafeIntoJsFunction};
-
 /// A token to represent the context argument in the function signature.
 /// This should not be used directly and has no external meaning.
 #[derive(Debug, Copy, Clone)]