diff --git a/crates/neon/src/context/mod.rs b/crates/neon/src/context/mod.rs index 98b9b8bf5..2491d8726 100644 --- a/crates/neon/src/context/mod.rs +++ b/crates/neon/src/context/mod.rs @@ -107,7 +107,7 @@ //! # fn iterate(mut cx: FunctionContext) -> JsResult { //! let iterator = cx.argument::(0)?; // iterator object //! let next: Handle = // iterator's `next` method -//! iterator.get(&mut cx, "next")?; +//! iterator.prop(&mut cx, "next").get()?; //! let mut numbers = vec![]; // results vector //! let mut done = false; // loop controller //! @@ -117,12 +117,8 @@ //! .call_with(&cx) //! .this(iterator) //! .apply(&mut cx)?; -//! let number: Handle = // temporary number -//! obj.get(&mut cx, "value")?; -//! numbers.push(number.value(&mut cx)); -//! let done: Handle = // temporary boolean -//! obj.get(&mut cx, "done")?; -//! Ok(done.value(&mut cx)) +//! numbers.push(obj.prop(&mut cx, "value").get()?); // temporary number +//! obj.prop(&mut cx, "done").get() // temporary boolean //! })?; //! } //! # Ok(cx.undefined()) @@ -505,7 +501,7 @@ pub trait Context<'a>: ContextInternal<'a> { /// # let v: Handle = /// { /// let global = cx.global_object(); - /// global.get(cx, name) + /// global.prop(cx, name).get() /// } /// # ?; /// # Ok(v) diff --git a/crates/neon/src/event/mod.rs b/crates/neon/src/event/mod.rs index c5a594f0f..e6dff4f6d 100644 --- a/crates/neon/src/event/mod.rs +++ b/crates/neon/src/event/mod.rs @@ -82,13 +82,9 @@ //! let args = match result { //! Ok(psd) => { //! // Extract data from the parsed file. -//! let width = cx.number(psd.width()); -//! let height = cx.number(psd.height()); -//! -//! // Save the data in a result object. //! let obj = cx.empty_object(); -//! obj.set(&mut cx, "width", width)?; -//! obj.set(&mut cx, "height", height)?; +//! obj.prop(&mut cx, "width").set(psd.width())?; +//! obj.prop(&mut cx, "height").set(psd.height())?; //! vec![ //! cx.null().upcast::(), //! obj.upcast(), diff --git a/crates/neon/src/handle/mod.rs b/crates/neon/src/handle/mod.rs index ee6a91a9c..efb911c2e 100644 --- a/crates/neon/src/handle/mod.rs +++ b/crates/neon/src/handle/mod.rs @@ -27,22 +27,18 @@ //! //! ## Example //! -//! This Neon function takes an object as its argument, extracts two properties, -//! `width` and `height`, and multiplies them together as numbers. Each JavaScript -//! value in the calculation is stored locally in a `Handle`. +//! This Neon function takes an object as its argument, extracts an object property, +//! `homeAddress`, and then extracts a string property, `zipCode` from that second +//! object. Each JavaScript value in the calculation is stored locally in a `Handle`. //! //! ``` //! # use neon::prelude::*; -//! fn area(mut cx: FunctionContext) -> JsResult { -//! let rect: Handle = cx.argument(0)?; -//! -//! let width: Handle = rect.get(&mut cx, "width")?; -//! let w: f64 = width.value(&mut cx); -//! -//! let height: Handle = rect.get(&mut cx, "height")?; -//! let h: f64 = height.value(&mut cx); -//! -//! Ok(cx.number(w * h)) +//! # use neon::export; +//! #[export] +//! fn customer_zip_code<'cx>(cx: &mut FunctionContext<'cx>, customer: Handle<'cx, JsObject>) -> JsResult<'cx, JsString> { +//! let home_address: Handle = customer.prop(cx, "homeAddress").get()?; +//! let zip_code: Handle = home_address.prop(cx, "zipCode").get()?; +//! Ok(zip_code) //! } //! ``` diff --git a/crates/neon/src/object/mod.rs b/crates/neon/src/object/mod.rs index 1ef11476d..43d33f3fd 100644 --- a/crates/neon/src/object/mod.rs +++ b/crates/neon/src/object/mod.rs @@ -16,16 +16,15 @@ //! //! ``` //! # use neon::prelude::*; -//! fn set_and_check<'a>( -//! cx: &mut impl Context<'a>, -//! obj: Handle<'a, JsObject> -//! ) -> JsResult<'a, JsValue> { -//! let value = cx.string("hello!"); +//! fn set_and_check<'cx>( +//! cx: &mut Cx<'cx>, +//! obj: Handle<'cx, JsObject> +//! ) -> JsResult<'cx, JsValue> { //! // set property "17" with integer shorthand -//! obj.set(cx, 17, value)?; +//! obj.prop(cx, 17).set("hello")?; //! // get property "17" with string shorthand //! // returns the same value ("hello!") -//! obj.get(cx, "17") +//! obj.prop(cx, "17").get() //! } //! ``` //! @@ -210,7 +209,6 @@ where } /// Gets the property from the object and attempts to convert it to a Rust value. - /// Equivalent to calling `R::from_js(cx, obj.get(cx)?)`. /// /// May throw an exception either during accessing the property or converting the /// result type. @@ -220,7 +218,6 @@ where } /// Sets the property on the object to a value converted from Rust. - /// Equivalent to calling `obj.set(cx, v.try_into_js(cx)?)`. /// /// May throw an exception either during converting the value or setting the property. pub fn set>(&mut self, v: V) -> NeonResult<&mut Self> { @@ -230,7 +227,6 @@ where } /// Sets the property on the object to a value computed from a closure. - /// Equivalent to calling `obj.set(cx, f(cx).try_into_js(cx)?)`. /// /// May throw an exception either during converting the value or setting the property. pub fn set_with(&mut self, f: F) -> NeonResult<&mut Self> @@ -280,8 +276,7 @@ pub trait Object: Value { PropOptions { cx, this, key } } - /// Gets a property from a JavaScript object that may be `undefined` and - /// attempts to downcast the value if it existed. + #[doc(hidden)] fn get_opt<'a, V: Value, C: Context<'a>, K: PropertyKey>( &self, cx: &mut C, @@ -296,10 +291,7 @@ pub trait Object: Value { v.downcast_or_throw(cx).map(Some) } - /// Gets a property from a JavaScript object as a [`JsValue`]. - /// - /// If a [`getter`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get) - /// is defined on the object, it will be called. + #[doc(hidden)] fn get_value<'a, C: Context<'a>, K: PropertyKey>( &self, cx: &mut C, @@ -310,10 +302,7 @@ pub trait Object: Value { }) } - /// Gets a property from a JavaScript object and attempts to downcast as a specific type. - /// Equivalent to calling `obj.get_value(&mut cx)?.downcast_or_throw(&mut cx)`. - /// - /// Throws an exception if the value is a different type. + #[doc(hidden)] fn get<'a, V: Value, C: Context<'a>, K: PropertyKey>( &self, cx: &mut C, @@ -358,6 +347,7 @@ pub trait Object: Value { } } + #[doc(hidden)] fn set<'a, C: Context<'a>, K: PropertyKey, W: Value>( &self, cx: &mut C, @@ -378,6 +368,7 @@ pub trait Object: Value { Root::new(cx, self) } + #[doc(hidden)] fn call_method_with<'a, C, K>(&self, cx: &mut C, method: K) -> NeonResult> where C: Context<'a>, diff --git a/crates/neon/src/result/mod.rs b/crates/neon/src/result/mod.rs index 581995192..c65da4709 100644 --- a/crates/neon/src/result/mod.rs +++ b/crates/neon/src/result/mod.rs @@ -26,8 +26,7 @@ //! # use neon::prelude::*; //! fn get_message(mut cx: FunctionContext) -> JsResult { //! let obj: Handle = cx.argument(0)?; -//! let prop: Handle = obj.get(&mut cx, "message")?; -//! Ok(prop) +//! obj.prop(&mut cx, "message").get() //! } //! ``` //! diff --git a/crates/neon/src/thread/mod.rs b/crates/neon/src/thread/mod.rs index f4d7ad1e3..e5ae6d816 100644 --- a/crates/neon/src/thread/mod.rs +++ b/crates/neon/src/thread/mod.rs @@ -19,8 +19,8 @@ //! let worker: Handle = require.call_with(cx) //! .arg(cx.string("node:worker_threads")) //! .apply(cx)?; -//! let thread_id: Handle = worker.get(cx, "threadId")?; -//! Ok(thread_id.value(cx) as u32) +//! let thread_id: f64 = worker.prop(cx, "threadId").get()?; +//! Ok(thread_id as u32) //! }).cloned() //! } //! ``` diff --git a/crates/neon/src/types_impl/boxed.rs b/crates/neon/src/types_impl/boxed.rs index 1caf8ae87..8ec910427 100644 --- a/crates/neon/src/types_impl/boxed.rs +++ b/crates/neon/src/types_impl/boxed.rs @@ -295,7 +295,8 @@ impl Deref for JsBox { /// fn finalize<'a, C: Context<'a>>(self, cx: &mut C) { /// let global = cx.global_object(); /// let emit: Handle = global -/// .get(cx, "emit") +/// .prop(cx.cx_mut(), "emit") +/// .get() /// .unwrap(); /// /// let args = vec![ diff --git a/crates/neon/src/types_impl/error.rs b/crates/neon/src/types_impl/error.rs index 98fc404b8..7e723085a 100644 --- a/crates/neon/src/types_impl/error.rs +++ b/crates/neon/src/types_impl/error.rs @@ -24,11 +24,8 @@ use crate::{ /// let err = cx.type_error("expected a number, found a string")?; /// /// // Add some custom diagnostic properties to the error: -/// let expected = cx.string("number"); -/// err.set(&mut cx, "expected", expected)?; -/// -/// let found = cx.string("string"); -/// err.set(&mut cx, "found", found)?; +/// err.prop(&mut cx, "expected").set("number")?; +/// err.prop(&mut cx, "found").set("string")?; /// /// // Throw the error: /// cx.throw(err)?; diff --git a/crates/neon/src/types_impl/mod.rs b/crates/neon/src/types_impl/mod.rs index e1fc73d12..2aad93c3d 100644 --- a/crates/neon/src/types_impl/mod.rs +++ b/crates/neon/src/types_impl/mod.rs @@ -343,7 +343,7 @@ impl ValueInternal for JsNull { /// # fn test(mut cx: FunctionContext) -> JsResult { /// // Extract the console.log function: /// let console: Handle = cx.global("console")?; -/// let log: Handle = console.get(&mut cx, "log")?; +/// let log: Handle = console.prop(&mut cx, "log").get()?; /// /// // The two Boolean values: /// let t = cx.boolean(true); @@ -420,7 +420,7 @@ impl ValueInternal for JsBoolean { /// # fn test(mut cx: FunctionContext) -> JsResult { /// // Extract the console.log function: /// let console: Handle = cx.global("console")?; -/// let log: Handle = console.get(&mut cx, "log")?; +/// let log: Handle = console.prop(&mut cx, "log").get()?; /// /// // Create a string: /// let s = cx.string("hello 🥹"); @@ -697,7 +697,7 @@ impl JsString { /// # fn test(mut cx: FunctionContext) -> JsResult { /// // Extract the console.log function: /// let console: Handle = cx.global("console")?; -/// let log: Handle = console.get(&mut cx, "log")?; +/// let log: Handle = console.prop(&mut cx, "log").get()?; /// /// // Create a number: /// let n = cx.number(17.0); @@ -773,16 +773,15 @@ impl ValueInternal for JsNumber { /// # fn test(mut cx: FunctionContext) -> JsResult { /// // Extract the console.log function: /// let console: Handle = cx.global("console")?; -/// let log: Handle = console.get(&mut cx, "log")?; +/// let log: Handle = console.prop(&mut cx, "log").get()?; /// /// // Create an object: -/// let obj = cx.empty_object(); -/// -/// let name = cx.string("Neon"); -/// obj.set(&mut cx, "name", name)?; -/// -/// let url = cx.string("https://neon-bindings.com"); -/// obj.set(&mut cx, "url", url)?; +/// let obj = cx.empty_object() +/// .prop(&mut cx, "name") +/// .set("Neon")? +/// .prop("url") +/// .set("https://neon-bindings.com")? +/// .this(); /// /// // Call console.log(obj): /// log.call_with(&cx).arg(obj).exec(&mut cx)?; @@ -860,13 +859,9 @@ impl JsObject { /// // Create a new empty array: /// let a: Handle = cx.empty_array(); /// -/// // Create some new values to push onto the array: -/// let n = cx.number(17); -/// let s = cx.string("hello"); -/// -/// // Push the elements onto the array: -/// a.set(&mut cx, 0, n)?; -/// a.set(&mut cx, 1, s)?; +/// // Push some values onto the array: +/// a.prop(&mut cx, 0).set(17)?; +/// a.prop(&mut cx, 1).set("hello")?; /// # Ok(a) /// # } /// ``` diff --git a/crates/neon/src/types_impl/promise.rs b/crates/neon/src/types_impl/promise.rs index 1d79735e5..af5de8e62 100644 --- a/crates/neon/src/types_impl/promise.rs +++ b/crates/neon/src/types_impl/promise.rs @@ -123,10 +123,12 @@ const BOUNDARY: FailureBoundary = FailureBoundary { /// .promise(|mut cx, (indices, kinds)| { /// let indices = JsUint32Array::from_slice(&mut cx, &indices)?; /// let kinds = JsUint8Array::from_slice(&mut cx, &kinds)?; -/// let result = cx.empty_object(); -/// result.set(&mut cx, "indices", indices)?; -/// result.set(&mut cx, "kinds", kinds)?; -/// Ok(result) +/// Ok(cx.empty_object() +/// .prop(&mut cx, "indices") +/// .set(indices)? +/// .prop("kinds") +/// .set(kinds)? +/// .this()) /// }); /// /// Ok(promise)