neon/types_docs.rs
1#[cfg_attr(feature = "aquamarine", aquamarine::aquamarine)]
2/// Representations of JavaScript's core builtin types.
3///
4/// ## Modeling JavaScript Types
5///
6/// All JavaScript values in Neon implement the abstract [`Value`](crate::types::Value)
7/// trait, which is the most generic way to work with JavaScript values. Neon provides a
8/// number of types that implement this trait, each representing a particular
9/// type of JavaScript value.
10///
11/// By convention, JavaScript types in Neon have the prefix `Js` in their name,
12/// such as [`JsNumber`](crate::types::JsNumber) (for the JavaScript `number`
13/// type) or [`JsFunction`](crate::types::JsFunction) (for the JavaScript
14/// `function` type).
15///
16/// ### Handles and Casts
17///
18/// Access to JavaScript values in Neon works through [handles](crate::handle),
19/// which ensure the safe interoperation between Rust and the JavaScript garbage
20/// collector. This means, for example, a Rust variable that stores a JavaScript string
21/// will have the type `Handle<JsString>` rather than [`JsString`](crate::types::JsString).
22///
23/// Neon types model the JavaScript type hierarchy through the use of *casts*.
24/// The [`Handle::upcast()`](crate::handle::Handle::upcast) method safely converts
25/// a handle to a JavaScript value of one type into a handle to a value of its
26/// supertype. For example, it's safe to treat a [`JsArray`](crate::types::JsArray)
27/// as a [`JsObject`](crate::types::JsObject), so you can do an "upcast" and it will
28/// never fail:
29///
30/// ```
31/// # use neon::prelude::*;
32/// fn as_object(array: Handle<JsArray>) -> Handle<JsObject> {
33/// let object: Handle<JsObject> = array.upcast();
34/// object
35/// }
36/// ```
37///
38/// Unlike upcasts, the [`Handle::downcast()`](crate::handle::Handle::downcast) method
39/// requires a runtime check to test a value's type at runtime, so it can fail with
40/// a [`DowncastError`](crate::handle::DowncastError):
41///
42/// ```
43/// # use neon::prelude::*;
44/// fn as_array<'a>(
45/// cx: &mut impl Context<'a>,
46/// object: Handle<'a, JsObject>
47/// ) -> JsResult<'a, JsArray> {
48/// object.downcast(cx).or_throw(cx)
49/// }
50/// ```
51///
52/// ### The JavaScript Type Hierarchy
53///
54/// The top of the JavaScript type hierarchy is modeled with the Neon type
55/// [`JsValue`](crate::types::JsValue). A [handle](crate::handle) to a `JsValue`
56/// can refer to any JavaScript value. (For TypeScript programmers, this can be
57/// thought of as similar to TypeScript's [`unknown`][unknown] type.)
58///
59/// From there, the type hierarchy divides into _object types_ and _primitive
60/// types_:
61///
62/// ```mermaid
63/// flowchart LR
64/// JsValue(JsValue)
65/// JsValue-->JsObject(JsObject)
66/// click JsValue "./struct.JsValue.html" "JsValue"
67/// click JsObject "./struct.JsObject.html" "JsObject"
68/// subgraph primitives [Primitive Types]
69/// JsBoolean(JsBoolean)
70/// JsNumber(JsNumber)
71/// JsString(JsString)
72/// JsNull(JsNull)
73/// JsUndefined(JsUndefined)
74/// click JsBoolean "./struct.JsBoolean.html" "JsBoolean"
75/// click JsNumber "./struct.JsNumber.html" "JsNumber"
76/// click JsString "./struct.JsString.html" "JsString"
77/// click JsNull "./struct.JsNull.html" "JsNull"
78/// click JsUndefined "./struct.JsUndefined.html" "JsUndefined"
79/// end
80/// JsValue-->primitives
81/// ```
82///
83/// The top of the object type hierarchy is [`JsObject`](crate::types::JsObject). A
84/// handle to a `JsObject` can refer to any JavaScript object.
85///
86/// The primitive types are the built-in JavaScript datatypes that are not object
87/// types: [`JsBoolean`](crate::types::JsBoolean), [`JsNumber`](crate::types::JsNumber),
88/// [`JsString`](crate::types::JsString), [`JsNull`](crate::types::JsNull), and
89/// [`JsUndefined`](crate::types::JsUndefined).
90///
91/// #### Object Types
92///
93/// The object type hierarchy further divides into a variety of different subtypes:
94///
95/// ```mermaid
96/// flowchart LR
97/// JsObject(JsObject)
98/// click JsObject "./struct.JsObject.html" "JsObject"
99/// subgraph objects [Standard Object Types]
100/// JsFunction(JsFunction)
101/// JsArray(JsArray)
102/// JsDate(JsDate)
103/// JsError(JsError)
104/// click JsFunction "./struct.JsFunction.html" "JsFunction"
105/// click JsArray "./struct.JsArray.html" "JsArray"
106/// click JsDate "./struct.JsDate.html" "JsDate"
107/// click JsError "./struct.JsError.html" "JsError"
108/// end
109/// subgraph typedarrays [Typed Arrays]
110/// JsBuffer(JsBuffer)
111/// JsArrayBuffer(JsArrayBuffer)
112/// JsTypedArray("JsTypedArray<T>")
113/// click JsBuffer "./struct.JsBuffer.html" "JsBuffer"
114/// click JsArrayBuffer "./struct.JsArrayBuffer.html" "JsArrayBuffer"
115/// click JsTypedArray "./struct.JsTypedArray.html" "JsTypedArray"
116/// end
117/// subgraph custom [Custom Types]
118/// JsBox(JsBox)
119/// click JsBox "./struct.JsBox.html" "JsBox"
120/// end
121/// JsObject-->objects
122/// JsObject-->typedarrays
123/// JsObject-->custom
124/// ```
125///
126/// These include several categories of object types:
127/// - **Standard object types:** [`JsFunction`](crate::types::JsFunction),
128/// [`JsArray`](crate::types::JsArray), [`JsDate`](crate::types::JsDate), and
129/// [`JsError`](crate::types::JsError).
130/// - **Typed arrays:** [`JsBuffer`](crate::types::JsBuffer),
131/// [`JsArrayBuffer`](crate::types::JsArrayBuffer), and
132/// [`JsTypedArray<T>`](crate::types::JsTypedArray).
133/// - **Custom types:** [`JsBox`](crate::types::JsBox), a special Neon type that allows
134/// the creation of custom objects that own Rust data structures.
135///
136/// All object types implement the [`Object`](crate::object::Object) trait, which
137/// allows getting and setting properties of an object.
138///
139/// [unknown]: https://mariusschulz.com/blog/the-unknown-type-in-typescript#the-unknown-type
140pub mod exports {
141 pub use crate::types_impl::*;
142}