Typed Array discoverability

.cargo/config.toml

@@ -3,5 +3,5 @@
 # The following aliases simplify linting the entire workspace
 neon-check = " check  --all --all-targets --features napi-experimental,futures"
 neon-clippy = "clippy --all --all-targets --features napi-experimental,futures -- -A clippy::missing_safety_doc"
-neon-test = "  test   --all               --features=napi-experimental,futures"
-neon-doc = "   rustdoc -p neon            --features=napi-experimental,futures -- --cfg docsrs"
+neon-test = "  test   --all               --features=doc-comment,napi-experimental,futures"
+neon-doc = "   rustdoc -p neon            --features=doc-dependencies,napi-experimental,futures -- --cfg docsrs"

crates/neon/Cargo.toml

@@ -25,6 +25,8 @@ semver = "1"
 smallvec = "1.4.2"
 once_cell = "1.10.0"
 neon-macros = { version = "=1.0.0-alpha.1", path = "../neon-macros" }
+aquamarine = { version = "0.1.11", optional = true }
+doc-comment = { version = "0.3.3", optional = true }
 
 [dependencies.tokio]
 version = "1.18.2"
@@ -70,9 +72,13 @@ task-api = []
 # DEPRECATED: This is always enabled and should be removed.
 proc-macros = []
 
+# Enables the optional dependencies that are only used for generating the API docs.
+doc-dependencies = ["doc-comment", "aquamarine"]
+
 [package.metadata.docs.rs]
 rustdoc-args = ["--cfg", "docsrs"]
 features = [
     "futures",
     "napi-experimental",
+    "doc-dependencies",
 ]

crates/neon/src/context/mod.rs

@@ -322,12 +322,12 @@ pub trait Context<'a>: ContextInternal<'a> {
 
     /// Convenience method for creating a `JsNull` value.
     fn null(&mut self) -> Handle<'a, JsNull> {
-        return JsNull::new(self);
+        JsNull::new(self)
     }
 
     /// Convenience method for creating a `JsUndefined` value.
     fn undefined(&mut self) -> Handle<'a, JsUndefined> {
-        return JsUndefined::new(self);
+        JsUndefined::new(self)
     }
 
     /// Convenience method for creating an empty `JsObject` value.

crates/neon/src/handle/mod.rs

@@ -88,7 +88,7 @@ pub struct Handle<'a, T: Managed + 'a> {
 impl<'a, T: Managed> Clone for Handle<'a, T> {
     fn clone(&self) -> Self {
         Self {
-            value: self.value.clone(),
+            value: self.value,
             phantom: PhantomData,
         }
     }

crates/neon/src/lib.rs

@@ -89,7 +89,13 @@ pub mod result;
 mod sys;
 #[cfg(feature = "napi-6")]
 pub mod thread;
-pub mod types;
+// To use the #[aquamarine] attribute on the top-level neon::types module docs, we have to
+// use this hack so we can keep the module docs in a separate file.
+// See: https://github.com/mersinvald/aquamarine/issues/5#issuecomment-1168816499
+mod types_docs;
+mod types_impl;
+
+pub use types_docs::exports as types;
 
 #[doc(hidden)]
 pub mod macro_internal;

crates/neon/src/lifecycle.rs

@@ -131,7 +131,7 @@ impl LocalCell {
         // Kick off a new transaction and drop it before getting the result.
         {
             let mut tx = TryInitTransaction::new(cx, id);
-            tx.run(|cx| Ok(f(cx)?))?;
+            tx.run(|cx| f(cx))?;
         }
 
         // If we're here, the transaction has succeeded, so get the result.
@@ -195,11 +195,9 @@ impl<'cx, 'a, C: Context<'cx>> TryInitTransaction<'cx, 'a, C> {
         InstanceData::locals(self.cx).get(self.id)
     }
 
+    #[allow(clippy::wrong_self_convention)]
     fn is_trying(&mut self) -> bool {
-        match self.cell() {
-            LocalCell::Trying => true,
-            _ => false,
-        }
+        matches!(self.cell(), LocalCell::Trying)
     }
 }
 

crates/neon/src/prelude.rs

@@ -11,8 +11,10 @@ pub use crate::{
     result::{JsResult, NeonResult, ResultExt as NeonResultExt},
     types::{
         boxed::{Finalize, JsBox},
-        JsArray, JsArrayBuffer, JsBoolean, JsBuffer, JsError, JsFunction, JsNull, JsNumber,
-        JsObject, JsPromise, JsString, JsTypedArray, JsUndefined, JsValue, Value,
+        JsArray, JsArrayBuffer, JsBigInt64Array, JsBigUint64Array, JsBoolean, JsBuffer, JsError,
+        JsFloat32Array, JsFloat64Array, JsFunction, JsInt16Array, JsInt32Array, JsInt8Array,
+        JsNull, JsNumber, JsObject, JsPromise, JsString, JsTypedArray, JsUint16Array,
+        JsUint32Array, JsUint8Array, JsUndefined, JsValue, Value,
     },
 };
 

crates/neon/src/sys/arraybuffer.rs

@@ -65,3 +65,17 @@ pub unsafe fn as_mut_slice<'a>(env: Env, buf: Local) -> &'a mut [u8] {
 
     slice::from_raw_parts_mut(data.assume_init().cast(), size)
 }
+
+/// # Safety
+/// * Caller must ensure `env` and `buf` are valid
+pub unsafe fn size(env: Env, buf: Local) -> usize {
+    let mut data = MaybeUninit::uninit();
+    let mut size = 0usize;
+
+    assert_eq!(
+        napi::get_arraybuffer_info(env, buf, data.as_mut_ptr(), &mut size as *mut _),
+        napi::Status::Ok,
+    );
+
+    size
+}

crates/neon/src/sys/bindings/functions.rs

@@ -90,6 +90,15 @@ mod napi1 {
                 byte_length: *mut usize,
             ) -> Status;
 
+            fn create_typedarray(
+                env: Env,
+                type_: TypedArrayType,
+                length: usize,
+                arraybuffer: Value,
+                byte_offset: usize,
+                result: *mut Value,
+            ) -> Status;
+
             fn get_typedarray_info(
                 env: Env,
                 typedarray: Value,

crates/neon/src/sys/bindings/mod.rs

@@ -3,7 +3,7 @@
 //! These types are manually copied from bindings generated from `bindgen`. To
 //! update, use the following approach:
 //!
-//! * Run `cargo build` with `--cfg neon=dev` at least once to install `nodejs-sys`
+//! * Run a debug build of Neon at least once to install `nodejs-sys`
 //! * Open the generated bindings at `target/debug/build/nodejs-sys-*/out/bindings.rs`
 //! * Copy the types needed into `types.rs` and `functions.rs`
 //! * Modify to match Rust naming conventions:

crates/neon/src/sys/buffer.rs

@@ -74,3 +74,17 @@ pub unsafe fn as_mut_slice<'a>(env: Env, buf: Local) -> &'a mut [u8] {
 
     slice::from_raw_parts_mut(data.assume_init().cast(), size)
 }
+
+/// # Safety
+/// * Caller must ensure `env` and `buf` are valid
+pub unsafe fn size(env: Env, buf: Local) -> usize {
+    let mut data = MaybeUninit::uninit();
+    let mut size = 0usize;
+
+    assert_eq!(
+        napi::get_buffer_info(env, buf, data.as_mut_ptr(), &mut size as *mut _),
+        napi::Status::Ok,
+    );
+
+    size
+}

crates/neon/src/sys/no_panic.rs

@@ -210,13 +210,11 @@ unsafe fn error_from_message(env: Env, msg: &str) -> Local {
 
     let status = napi::create_error(env, ptr::null_mut(), msg, err.as_mut_ptr());
 
-    let err = if status == napi::Status::Ok {
+    if status == napi::Status::Ok {
         err.assume_init()
     } else {
         fatal_error("Failed to create an Error");
-    };
-
-    err
+    }
 }
 
 #[track_caller]
@@ -246,7 +244,7 @@ unsafe fn panic_msg(panic: &Panic) -> Option<&str> {
     if let Some(msg) = panic.downcast_ref::<&str>() {
         Some(msg)
     } else if let Some(msg) = panic.downcast_ref::<String>() {
-        Some(&msg)
+        Some(msg)
     } else {
         None
     }

crates/neon/src/sys/tsfn.rs

@@ -78,7 +78,7 @@ impl<T: Send + 'static> ThreadsafeFunction<T> {
 
         Self {
             tsfn: Tsfn(result.assume_init()),
-            is_finalized: is_finalized,
+            is_finalized,
             callback,
         }
     }

crates/neon/src/sys/typedarray.rs

@@ -39,3 +39,22 @@ pub unsafe fn info(env: Env, value: Local) -> TypedArrayInfo {
 
     info.assume_init()
 }
+
+pub unsafe fn new(
+    env: Env,
+    typ: TypedArrayType,
+    buffer: Local,
+    offset: usize,
+    len: usize,
+) -> Result<Local, napi::Status> {
+    let mut array = MaybeUninit::uninit();
+    let status = napi::create_typedarray(env, typ, len, buffer, offset, array.as_mut_ptr());
+
+    if status == napi::Status::PendingException {
+        return Err(status);
+    }
+
+    assert_eq!(status, napi::Status::Ok);
+
+    Ok(array.assume_init())
+}