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