Module types

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:

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. 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:

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, JsArray, JsDate, and JsError.
Typed arrays: JsBuffer, JsArrayBuffer, and JsTypedArray<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§

bigintnapi-6: Types for working with JsBigInt.
buffer: Types and traits for working with binary buffers.
extract: Traits and utilities for extract Rust data from JavaScript values.
function: Types and traits for working with JavaScript functions.

Structs§

DateError: An error produced when constructing a date with an invalid value.
Deferred: A controller struct that can be used to resolve or reject a JsPromise.
JsArray: The type of JavaScript Array objects.
JsArrayBuffer: The type of JavaScript ArrayBuffer objects.
JsBigIntnapi-6: The type of JavaScript BigInt values.
JsBoolean: The type of JavaScript Boolean primitives.
JsBox: A JavaScript smart pointer object that owns Rust data.
JsBuffer: The type of Node Buffer objects.
JsDate: The type of JavaScript Date objects.
JsError: The type of JavaScript Error objects.
JsFunction: The type of JavaScript Function objects.
JsFuturenapi-5 and futures: A type of JavaScript Promise object that acts as a Future.
JsNull: The type of JavaScript null primitives.
JsNumber: The type of JavaScript number primitives.
JsObject: The type of JavaScript objects, i.e., the root of all object types.
JsPromise: The type of JavaScript Promise objects.
JsString: The type of JavaScript string primitives.
JsTypedArray: The family of JavaScript typed array types.
JsUndefined: The type of JavaScript undefined primitives.
JsValue: The type of any JavaScript value, i.e., the root of all types.
StringOverflow: An error produced when constructing a string that exceeds the limits of the runtime.

Enums§

DateErrorKind: The error kinds corresponding to DateError

Traits§

Finalize: A trait for finalizing values owned by the main JavaScript thread.
Value: The trait shared by all JavaScript values.

Type Aliases§

JsBigInt64Array: The type of JavaScript BigInt64Array objects.
JsBigUint64Array: The type of JavaScript BigUint64Array objects.
JsFloat32Array: The type of JavaScript Float32Array objects.
JsFloat64Array: The type of JavaScript Float64Array objects.
JsInt8Array: The type of JavaScript Int8Array objects.
JsInt16Array: The type of JavaScript Int16Array objects.
JsInt32Array: The type of JavaScript Int32Array objects.
JsUint8Array: The type of JavaScript Uint8Array objects.
JsUint16Array: The type of JavaScript Uint16Array objects.
JsUint32Array: The type of JavaScript Uint32Array objects.
StringResult: The result of constructing a new JsString.

Module typesCopy item path