Expand description
Representations of JavaScript’s core builtin types.
Modeling JavaScript Types
All JavaScript values in Neon implement the abstract 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
(for the JavaScript number
type) or JsFunction
(for the JavaScript
function
type).
Handles and Casts
Access to JavaScript values in Neon works through handles,
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
.
Neon types model the JavaScript type hierarchy through the use of casts.
The 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
as a JsObject
, so you can do an “upcast” and it will
never fail:
fn as_object(array: Handle<JsArray>) -> Handle<JsObject> {
let object: Handle<JsObject> = array.upcast();
object
}
Unlike upcasts, the Handle::downcast()
method
requires a runtime check to test a value’s type at runtime, so it can fail with
a DowncastError
:
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
. A handle to a JsValue
can refer to any JavaScript value. (For TypeScript programmers, this can be
thought of as similar to TypeScript’s unknown
type.)
From there, the type hierarchy divides into object types and primitive types:
The top of the object type hierarchy is 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
, JsNumber
,
JsString
, JsNull
, and
JsUndefined
.
Object Types
The object type hierarchy further divides into a variety of different subtypes:
These include several categories of object types:
- Standard object types:
JsFunction
,JsArray
,JsDate
, andJsError
. - Typed arrays:
JsBuffer
,JsArrayBuffer
, andJsTypedArray<T>
. - Custom types:
JsBox
, a special Neon type that allows the creation of custom objects that own Rust data structures.
All object types implement the Object
trait, which
allows getting and setting properties of an object.
Modules
Structs
napi-5
Array.isArray
would return true
.ArrayBuffer
type.napi-5
Error
object.null
value.undefined
value.Enums
napi-5
DateError
Traits
JsBox
must implement Finalize
.Type Definitions
BigInt64Array
type.BigUint64Array
type.Float32Array
type.Float64Array
type.Int8Array
type.Int16Array
type.Int32Array
type.Uint8Array
type.Uint16Array
type.Uint32Array
type.JsString
.