Merge pull request #332 from dherman/kjv-feedback

More API tweaks

src/context/internal.rs

@@ -4,8 +4,8 @@ use std::os::raw::c_void;
 use neon_runtime;
 use neon_runtime::raw;
 use neon_runtime::scope::Root;
-use value::JsObject;
-use value::mem::Handle;
+use types::JsObject;
+use handle::Handle;
 use object::class::ClassMap;
 use result::NeonResult;
 use super::ModuleContext;

src/context/mod.rs

@@ -1,4 +1,4 @@
-//! Types and traits that represent _execution contexts_, which manage access to the JavaScript engine.
+//! Node _execution contexts_, which manage access to the JavaScript engine at various points in the Node.js runtime lifecycle.
 
 pub(crate) mod internal;
 
@@ -11,13 +11,13 @@ use neon_runtime;
 use neon_runtime::raw;
 use borrow::{Ref, RefMut, Borrow, BorrowMut};
 use borrow::internal::Ledger;
-use value::{JsResult, JsValue, Value, JsObject, JsArray, JsFunction, JsBoolean, JsNumber, JsString, StringResult, JsNull, JsUndefined};
-use value::mem::{Managed, Handle};
-use value::binary::{JsArrayBuffer, JsBuffer};
-use value::error::JsError;
+use handle::{Managed, Handle};
+use types::{JsValue, Value, JsObject, JsArray, JsFunction, JsBoolean, JsNumber, JsString, StringResult, JsNull, JsUndefined};
+use types::binary::{JsArrayBuffer, JsBuffer};
+use types::error::JsError;
 use object::{Object, This};
 use object::class::Class;
-use result::{NeonResult, Throw, ResultExt};
+use result::{NeonResult, JsResult, Throw};
 use self::internal::{ContextInternal, Scope, ScopeMetadata};
 
 #[repr(C)]
@@ -468,7 +468,7 @@ impl<'a, T: This> CallContext<'a, T> {
     /// Produces the `i`th argument and casts it to the type `V`, or throws an exception if `i` is greater than or equal to `self.len()` or cannot be cast to `V`.
     pub fn argument<V: Value>(&mut self, i: i32) -> JsResult<'a, V> {
         let a = self.info.require(self, i)?;
-        a.downcast().unwrap_or_throw(self)
+        a.downcast_or_throw(self)
     }
 
     /// Produces a handle to the `this`-binding.

src/handle/internal.rs

@@ -0,0 +1,5 @@
+use types::Value;
+
+pub trait SuperType<T: Value> {
+    fn upcast_internal(T) -> Self;
+}

src/value/mem.rs → src/handle/mod.rs

@@ -1,15 +1,17 @@
-//! Types encapsulating _handles_ to managed JavaScript memory.
+//! Safe _handles_ to managed JavaScript memory.
+
+pub(crate) mod internal;
 
 use std::marker::PhantomData;
 use std::ops::{Deref, DerefMut};
 use std::error::Error;
 use std::fmt::{self, Debug, Display};
 use neon_runtime;
 use neon_runtime::raw;
-use value::{JsResult, Value};
-use value::internal::SuperType;
+use types::Value;
 use context::Context;
-use result::ResultExt;
+use result::{JsResult, JsResultExt};
+use self::internal::SuperType;
 
 /// The trait of data that is managed by the JS garbage collector and can only be accessed via handles.
 pub trait Managed: Copy {
@@ -82,8 +84,8 @@ impl<F: Value, T: Value> Error for DowncastError<F, T> {
 /// The result of a call to `Handle::downcast()`.
 pub type DowncastResult<'a, F, T> = Result<Handle<'a, T>, DowncastError<F, T>>;
 
-impl<'a, F: Value, T: Value> ResultExt<'a, T> for DowncastResult<'a, F, T> {
-    fn unwrap_or_throw<'b, C: Context<'b>>(self, cx: &mut C) -> JsResult<'a, T> {
+impl<'a, F: Value, T: Value> JsResultExt<'a, T> for DowncastResult<'a, F, T> {
+    fn or_throw<'b, C: Context<'b>>(self, cx: &mut C) -> JsResult<'a, T> {
         match self {
             Ok(v) => Ok(v),
             Err(e) => cx.throw_type_error(&e.description)
@@ -118,14 +120,24 @@ impl<'a, T: Value> Handle<'a, T> {
         U::is_typeof(self.value)
     }
 
-    /// Attempts to downcast a handle to another type, which may fail.
+    /// Attempts to downcast a handle to another type, which may fail. A failure
+    /// to downcast **does not** throw a JavaScript exception, so it's OK to
+    /// continue interacting with the JS engine if this method produces an `Err`
+    /// result.
     pub fn downcast<U: Value>(&self) -> DowncastResult<'a, T, U> {
         match U::downcast(self.value) {
             Some(v) => Ok(Handle::new_internal(v)),
             None => Err(DowncastError::new())
         }
     }
 
+    /// Attempts to downcast a handle to another type, raising a JavaScript `TypeError`
+    /// exception on failure. This method is a convenient shorthand, equivalent to
+    /// `self.downcast::<U>().or_throw::<C>(cx)`.
+    pub fn downcast_or_throw<'b, U: Value, C: Context<'b>>(&self, cx: &mut C) -> JsResult<'a, U> {
+        self.downcast().or_throw(cx)
+    }
+
 }
 
 impl<'a, T: Managed> Deref for Handle<'a, T> {

src/lib.rs

@@ -1,4 +1,4 @@
-//! The `neon` crate provides the entire [Neon](https://www.neon-bindings.com/) API.
+//! The [Neon](https://www.neon-bindings.com/) crate provides bindings for writing Node.js plugins with a safe and fast Rust API.
 
 extern crate neon_runtime;
 extern crate cslice;
@@ -12,7 +12,8 @@ extern crate rustc_version;
 extern crate lazy_static;
 
 pub mod context;
-pub mod value;
+pub mod handle;
+pub mod types;
 pub mod object;
 pub mod borrow;
 pub mod result;
@@ -60,9 +61,9 @@ macro_rules! register_module {
                     dso_handle: *mut u8,
                     filename: *const u8,
                     register_func: Option<extern "C" fn(
-                        $crate::value::Handle<$crate::value::JsObject>, *mut u8, *mut u8)>,
+                        $crate::handle::Handle<$crate::types::JsObject>, *mut u8, *mut u8)>,
                     context_register_func: Option<extern "C" fn(
-                        $crate::value::Handle<$crate::value::JsObject>, *mut u8, *mut u8, *mut u8)>,
+                        $crate::handle::Handle<$crate::types::JsObject>, *mut u8, *mut u8, *mut u8)>,
                     modname: *const u8,
                     priv_data: *mut u8,
                     link: *mut __NodeModule
@@ -81,7 +82,7 @@ macro_rules! register_module {
                 };
 
                 extern "C" fn __register_neon_module(
-                        m: $crate::value::Handle<$crate::value::JsObject>, _: *mut u8, _: *mut u8) {
+                        m: $crate::handle::Handle<$crate::types::JsObject>, _: *mut u8, _: *mut u8) {
                     $crate::macro_internal::initialize_module(m, __init_neon_module);
                 }
 
@@ -112,7 +113,7 @@ macro_rules! class_definition {
                           $cname ;
                           $typ ;
                           {
-                              fn _______allocator_rust_y_u_no_hygienic_items_______($cx: $crate::context::CallContext<$crate::value::JsUndefined>) -> $crate::result::NeonResult<$typ> {
+                              fn _______allocator_rust_y_u_no_hygienic_items_______($cx: $crate::context::CallContext<$crate::types::JsUndefined>) -> $crate::result::NeonResult<$typ> {
                                   $body
                               }
 
@@ -134,7 +135,7 @@ macro_rules! class_definition {
                           $new_ctor ;
                           ($($mname)* $name) ;
                           ($($mdef)* {
-                              fn _______method_rust_y_u_no_hygienic_items_______($cx: $crate::context::CallContext<$cls>) -> $crate::value::JsResult<$crate::value::JsValue> {
+                              fn _______method_rust_y_u_no_hygienic_items_______($cx: $crate::context::CallContext<$cls>) -> $crate::result::JsResult<$crate::types::JsValue> {
                                   $body
                               }
 
@@ -150,7 +151,7 @@ macro_rules! class_definition {
                           $allocator ;
                           $call_ctor ;
                           ({
-                              fn _______constructor_rust_y_u_no_hygienic_items_______($cx: $crate::context::CallContext<$cls>) -> $crate::result::NeonResult<Option<$crate::value::Handle<$crate::value::JsObject>>> {
+                              fn _______constructor_rust_y_u_no_hygienic_items_______($cx: $crate::context::CallContext<$cls>) -> $crate::result::NeonResult<Option<$crate::handle::Handle<$crate::types::JsObject>>> {
                                   $body
                               }
 
@@ -167,7 +168,7 @@ macro_rules! class_definition {
                           $typ ;
                           $allocator ;
                           ({
-                              fn _______call_rust_y_u_no_hygienic_items_______($cx: $crate::context::CallContext<$crate::value::JsValue>) -> $crate::value::JsResult<$crate::value::JsValue> {
+                              fn _______call_rust_y_u_no_hygienic_items_______($cx: $crate::context::CallContext<$crate::types::JsValue>) -> $crate::result::JsResult<$crate::types::JsValue> {
                                   $body
                               }
 
@@ -197,7 +198,7 @@ macro_rules! class_definition {
 #[macro_export]
 macro_rules! impl_managed {
     ($cls:ident) => {
-        impl $crate::value::Managed for $cls {
+        impl $crate::handle::Managed for $cls {
             fn to_raw(self) -> $crate::macro_internal::runtime::raw::Local {
                 let $cls(raw) = self;
                 raw

src/object/class/internal.rs

@@ -4,11 +4,12 @@ use std::ptr::null_mut;
 use neon_runtime;
 use neon_runtime::raw;
 use super::{Class, ClassInternal, Callback};
-use value::{JsResult, JsValue, JsObject, JsFunction, JsUndefined, Handle, Managed, build};
+use handle::{Handle, Managed};
 use context::{CallbackInfo, CallContext, Context};
 use context::internal::ContextInternal;
-use result::{NeonResult, Throw};
-use value::error::convert_panics;
+use result::{NeonResult, JsResult, Throw};
+use types::{JsValue, JsObject, JsFunction, JsUndefined, build};
+use types::error::convert_panics;
 
 #[repr(C)]
 pub struct MethodCallback<T: Class>(pub fn(CallContext<T>) -> JsResult<JsValue>);

src/object/class/mod.rs

@@ -12,10 +12,11 @@ use neon_runtime::raw;
 use neon_runtime::call::CCallback;
 use context::{Context, Lock, CallbackInfo};
 use context::internal::Isolate;
-use result::{NeonResult, Throw};
+use result::{NeonResult, JsResult, Throw};
 use borrow::{Borrow, BorrowMut, Ref, RefMut, LoanError};
-use value::{JsResult, Value, JsFunction, JsValue, Handle, Managed, build};
-use value::internal::ValueInternal;
+use handle::{Handle, Managed};
+use types::{Value, JsFunction, JsValue, build};
+use types::internal::ValueInternal;
 use object::{Object, This};
 use self::internal::{ClassMetadata, MethodCallback, ConstructorCallCallback, AllocateCallback, ConstructCallback};
 

src/object/mod.rs

@@ -4,10 +4,11 @@ pub(crate) mod class;
 
 use neon_runtime;
 use neon_runtime::raw;
-use value::{Handle, Managed, JsResult, Value, JsValue, JsArray, build};
-use value::utf8::Utf8;
+use handle::{Handle, Managed};
+use types::{Value, JsValue, JsArray, build};
+use types::utf8::Utf8;
 use context::Context;
-use result::{NeonResult, Throw};
+use result::{NeonResult, JsResult, Throw};
 
 pub use self::class::{Class, ClassDescriptor};
 

src/prelude.rs

@@ -1,8 +1,9 @@
-//! The Neon "prelude," a re-exported collection of the most commonly-used Neon APIs.
+//! A convenience module that re-exports the most commonly-used Neon APIs.
 
-pub use value::{Handle, JsResult, JsBuffer, JsArrayBuffer, BinaryData, JsError, Value, JsValue, JsUndefined, JsNull, JsBoolean, JsString, JsNumber, JsObject, JsArray, JsFunction};
+pub use handle::Handle;
+pub use types::{JsBuffer, JsArrayBuffer, BinaryData, JsError, Value, JsValue, JsUndefined, JsNull, JsBoolean, JsString, JsNumber, JsObject, JsArray, JsFunction};
 pub use object::{Object, Class};
 pub use borrow::{Borrow, BorrowMut};
 pub use context::{CallKind, Context, ModuleContext, ExecuteContext, ComputeContext, CallContext, FunctionContext, MethodContext, TaskContext};
-pub use result::{NeonResult, ResultExt};
+pub use result::{NeonResult, JsResult, JsResultExt};
 pub use thread::Task;

src/result/mod.rs

@@ -2,7 +2,8 @@
 
 use std::error::Error;
 use std::fmt::{Display, Formatter, Result as FmtResult};
-use value::{JsResult, Value};
+use handle::Handle;
+use types::Value;
 use context::Context;
 
 /// An error sentinel type used by `NeonResult` (and `JsResult`) to indicate that the JS engine has entered into a throwing state.
@@ -24,8 +25,11 @@ impl Error for Throw {
 /// The result of a computation that might send the JS engine into a throwing state.
 pub type NeonResult<T> = Result<T, Throw>;
 
+/// The result of a computation that produces a JavaScript value and might send the JS engine into a throwing state.
+pub type JsResult<'b, T> = NeonResult<Handle<'b, T>>;
+
 /// An extension trait for `Result` values that can be converted into `JsResult` values by throwing a JavaScript
 /// exception in the error case.
-pub trait ResultExt<'a, V: Value> {
-    fn unwrap_or_throw<'b, C: Context<'b>>(self, cx: &mut C) -> JsResult<'a, V>;
+pub trait JsResultExt<'a, V: Value> {
+    fn or_throw<'b, C: Context<'b>>(self, cx: &mut C) -> JsResult<'a, V>;
 }

src/thread/mod.rs

@@ -1,11 +1,12 @@
-//! Types and traits for implementing multithreaded computation in a Node plugin.
+//! Asynchronous access to multithreaded computation in a Node plugin.
 
 use std::marker::{Send, Sized};
 use std::mem;
 use std::os::raw::c_void;
 
-use value::{JsResult, Value, JsFunction};
-use value::mem::{Handle, Managed};
+use types::{Value, JsFunction};
+use result::JsResult;
+use handle::{Handle, Managed};
 use context::TaskContext;
 use neon_runtime;
 use neon_runtime::raw;

src/value/binary.rs → src/types/binary.rs

@@ -7,9 +7,10 @@ use std::slice;
 use context::{Context, Lock};
 use borrow::{Borrow, BorrowMut, Ref, RefMut, LoanError};
 use borrow::internal::Pointer;
-use value::{JsResult, Value, Object, build};
-use value::mem::Managed;
-use value::internal::ValueInternal;
+use handle::Managed;
+use types::{Value, Object, build};
+use types::internal::ValueInternal;
+use result::JsResult;
 use neon_runtime;
 use neon_runtime::raw;
 

src/value/error.rs → src/types/error.rs

@@ -7,9 +7,9 @@ use neon_runtime::raw;
 
 use context::Context;
 use result::{NeonResult, Throw};
-use value::{Value, Object, Handle, Managed, build};
-use value::internal::ValueInternal;
-use value::utf8::Utf8;
+use types::{Value, Object, Handle, Managed, build};
+use types::internal::ValueInternal;
+use types::utf8::Utf8;
 
 /// A JS `Error` object.
 #[repr(C)]

src/value/internal.rs → src/types/internal.rs

@@ -3,10 +3,11 @@ use std::os::raw::c_void;
 use neon_runtime;
 use neon_runtime::raw;
 use context::{CallbackInfo, FunctionContext};
-use value::error::convert_panics;
-use value::{JsObject, Handle, Managed};
+use types::error::convert_panics;
+use types::{JsObject, Handle, Managed};
+use result::JsResult;
 use object::class::Callback;
-use super::{JsResult, Value};
+use super::Value;
 
 pub trait ValueInternal: Managed + 'static {
     fn name() -> String;
@@ -26,10 +27,6 @@ pub trait ValueInternal: Managed + 'static {
     }
 }
 
-pub trait SuperType<T: Value> {
-    fn upcast_internal(T) -> Self;
-}
-
 #[repr(C)]
 pub struct FunctionCallback<T: Value>(pub fn(FunctionContext) -> JsResult<T>);
 

src/value/mod.rs → src/types/mod.rs

@@ -1,8 +1,7 @@
-//! Types and traits for working with JavaScript values.
+//! Representations of JavaScript's core builtin types.
 
 pub(crate) mod binary;
 pub(crate) mod error;
-pub(crate) mod mem;
 
 pub(crate) mod internal;
 pub(crate) mod utf8;
@@ -15,18 +14,16 @@ use neon_runtime;
 use neon_runtime::raw;
 use context::{Context, FunctionContext};
 use context::internal::Isolate;
-use result::{NeonResult, Throw, ResultExt};
+use result::{NeonResult, JsResult, Throw, JsResultExt};
 use object::{Object, This};
 use object::class::Callback;
-use self::internal::{ValueInternal, SuperType, FunctionCallback};
+use handle::{Handle, Managed};
+use handle::internal::SuperType;
+use self::internal::{ValueInternal, FunctionCallback};
 use self::utf8::Utf8;
 
 pub use self::binary::{JsBuffer, JsArrayBuffer, BinaryData, BinaryViewType};
 pub use self::error::JsError;
-pub use self::mem::{Handle, Managed, DowncastError, DowncastResult};
-
-/// The result of a computation that produces a JS value and might send the JS engine into a throwing state.
-pub type JsResult<'b, T> = NeonResult<Handle<'b, T>>;
 
 pub(crate) fn build<'a, T: Managed, F: FnOnce(&mut raw::Local) -> bool>(init: F) -> JsResult<'a, T> {
     unsafe {
@@ -234,8 +231,8 @@ impl fmt::Display for StringOverflow {
 /// The result of constructing a new `JsString`.
 pub type StringResult<'a> = Result<Handle<'a, JsString>, StringOverflow>;
 
-impl<'a> ResultExt<'a, JsString> for StringResult<'a> {
-    fn unwrap_or_throw<'b, C: Context<'b>>(self, cx: &mut C) -> JsResult<'a, JsString> {
+impl<'a> JsResultExt<'a, JsString> for StringResult<'a> {
+    fn or_throw<'b, C: Context<'b>>(self, cx: &mut C) -> JsResult<'a, JsString> {
         match self {
             Ok(v) => Ok(v),
             Err(e) => cx.throw_range_error(&e.to_string())