Trait NapiValueT

pub trait NapiValueT: NapiValueCheck + Sized {
    // Required methods
    fn from_raw(env: NapiEnv, value: napi_value) -> Self;
    fn value(&self) -> JsValue;

    // Provided methods
    unsafe fn cast<T: NapiValueT>(&self) -> T { ... }
    fn cast_checked<T: NapiValueT>(&self) -> NapiResult<T> { ... }
    fn kind(&self) -> NapiResult<NapiValuetype> { ... }
    fn coerce_to_bool(&self) -> NapiResult<JsBoolean> { ... }
    fn coerce_coerce_to_number(&self) -> NapiResult<JsNumber> { ... }
    fn coerce_to_object(&self) -> NapiResult<JsObject> { ... }
    fn coerce_to_string(&self) -> NapiResult<JsString> { ... }
    fn instance_of(&self, constructor: JsFunction) -> NapiResult<bool> { ... }
    fn equals(&self, rhs: impl NapiValueT) -> NapiResult<bool> { ... }
    fn env(&self) -> NapiEnv { ... }
    fn raw(&self) -> napi_value { ... }
    fn null(&self) -> NapiResult<JsNull> { ... }
    fn undefined(&self) -> NapiResult<JsUndefined> { ... }
    fn global(&self) -> NapiResult<JsGlobal> { ... }
    fn throw(&self) -> NapiResult<()> { ... }
    fn define_properties<P>(&self, properties: P) -> NapiResult<()>
       where P: AsRef<[NapiPropertyDescriptor]> { ... }
    fn gc<Finalizer>(&mut self, finalizer: Finalizer) -> NapiResult<NapiRef>
       where Finalizer: FnOnce(NapiEnv) -> NapiResult<()> { ... }
    fn finalizer<Finalizer>(&self, finalizer: Finalizer) -> NapiResult<NapiRef>
       where Finalizer: FnOnce(NapiEnv) -> NapiResult<()> { ... }
    fn wrap<T>(
        &mut self,
        data: T,
        finalizer: impl FnOnce(NapiEnv, T) -> NapiResult<()>,
    ) -> NapiResult<NapiRef> { ... }
    fn unwrap<T>(&self) -> NapiResult<Option<&mut T>> { ... }
    fn remove_wrap<T>(&mut self) -> NapiResult<T> { ... }
    fn type_tag_object(&self, tag: &NapiTypeTag) -> NapiResult<()> { ... }
    fn check_object_type_tag(&self, tag: &NapiTypeTag) -> NapiResult<bool> { ... }
}

The trait for js value, which just store napi_value raw pointer.

Required Methods

fn from_raw(env: NapiEnv, value: napi_value) -> Self

construct value from raw pointer

fn value(&self) -> JsValue

inner value

Provided Methods

unsafe fn cast<T: NapiValueT>(&self) -> T

napi_value type cast

Safety

It just put the handle in new type, does not check the real type.

fn cast_checked<T: NapiValueT>(&self) -> NapiResult<T>

Upcast to specified value

fn kind(&self) -> NapiResult<NapiValuetype>

Returns napi_ok if the API succeeded.

• napi_invalid_arg if the type of value is not a known ECMAScript type and value is not an External value. This API represents behavior similar to invoking the typeof Operator on the object as defined in Section 12.5.5 of the ECMAScript Language Specification. However, there are some differences: It has support for detecting an External value. It detects null as a separate type, while ECMAScript typeof would detect object. If value has a type that is invalid, an error is returned.

fn coerce_to_bool(&self) -> NapiResult<JsBoolean>

This API implements the abstract operation ToBoolean() as defined in Section 7.1.2 of the ECMAScript Language Specification.

fn coerce_coerce_to_number(&self) -> NapiResult<JsNumber>

This API implements the abstract operation ToNumber() as defined in Section 7.1.3 of the ECMAScript Language Specification. This function potentially runs JS code if the passed-in value is an object.

fn coerce_to_object(&self) -> NapiResult<JsObject>

This API implements the abstract operation ToObject() as defined in Section 7.1.13 of the ECMAScript Language Specification.

fn coerce_to_string(&self) -> NapiResult<JsString>

This API implements the abstract operation ToString() as defined in Section 7.1.13 of the ECMAScript Language Specification. This function potentially runs JS code if the passed-in value is an object.

fn instance_of(&self, constructor: JsFunction) -> NapiResult<bool>

This API represents invoking the instanceof Operator on the object as defined in Section 12.10.4 of the ECMAScript Language Specification.

fn equals(&self, rhs: impl NapiValueT) -> NapiResult<bool>

This API represents the invocation of the Strict Equality algorithm as defined in Section 7.2.14 of the ECMAScript Language Specification.

fn env(&self) -> NapiEnv

the NapiEnv of current value

fn raw(&self) -> napi_value

the raw-handle of current value

fn null(&self) -> NapiResult<JsNull>

get null singleton

fn undefined(&self) -> NapiResult<JsUndefined>

get undefined singleton

fn global(&self) -> NapiResult<JsGlobal>

get global singleton

fn throw(&self) -> NapiResult<()>

value is throwable

fn define_properties<P>(&self, properties: P) -> NapiResult<()>

where P: AsRef<[NapiPropertyDescriptor]>,

This method allows the efficient definition of multiple properties on a given object. The properties are defined using property descriptors (see napi_property_descriptor). Given an array of such property descriptors, this API will set the properties on the object one at a time, as defined by DefineOwnProperty() (described in Section 9.1.6 of the ECMA-262 specification).

fn gc<Finalizer>(&mut self, finalizer: Finalizer) -> NapiResult<NapiRef>

where Finalizer: FnOnce(NapiEnv) -> NapiResult<()>,

This is a hook which is fired when the value is gabage-collected. For napi >= 5, we use napi_add_finalizer, For napi < 5, we use napi_wrap.

fn finalizer<Finalizer>(&self, finalizer: Finalizer) -> NapiResult<NapiRef>

where Finalizer: FnOnce(NapiEnv) -> NapiResult<()>,

Adds a napi_finalize callback which will be called when the JavaScript object in js_object is ready for garbage collection. This API is similar to napi_wrap() except that:

• the native data cannot be retrieved later using napi_unwrap(),
• nor can it be removed later using napi_remove_wrap(), and
• the API can be called multiple times with different data items in order to attach each of them to the JavaScript object, and
• the object manipulated by the API can be used with napi_wrap().

Caution: The optional returned reference (if obtained) should be deleted via napi_delete_reference ONLY in response to the finalize callback invocation. If it is deleted before then, then the finalize callback may never be invoked. herefore, when obtaining a reference a finalize callback is also required in order to enable correct disposal of the reference.

fn wrap<T>( &mut self, data: T, finalizer: impl FnOnce(NapiEnv, T) -> NapiResult<()>, ) -> NapiResult<NapiRef>

Wraps a native instance in a JavaScript object. The native instance can be retrieved later using napi_unwrap().

When JavaScript code invokes a constructor for a class that was defined using napi_define_class(), the napi_callback for the constructor is invoked. After constructing an instance of the native class, the callback must then call napi_wrap() to wrap the newly constructed instance in the already-created JavaScript object that is the this argument to the constructor callback. (That this object was created from the constructor function’s prototype, so it already has definitions of all the instance properties and methods.)

Typically when wrapping a class instance, a finalize callback should be provided that simply deletes the native instance that is received as the data argument to the finalize callback.

The optional returned reference is initially a weak reference, meaning it has a reference count of 0. Typically this reference count would be incremented temporarily during async operations that require the instance to remain valid.

Caution: The optional returned reference (if obtained) should be deleted via napi_delete_reference ONLY in response to the finalize callback invocation. If it is deleted before then, then the finalize callback may never be invoked. Therefore, when obtaining a reference a finalize callback is also required in order to enable correct disposal of the reference.

Calling napi_wrap() a second time on an object will return an error. To associate another native instance with the object, use napi_remove_wrap() first.

fn unwrap<T>(&self) -> NapiResult<Option<&mut T>>

Retrieves a native instance that was previously wrapped in a JavaScript object using napi_wrap().

When JavaScript code invokes a method or property accessor on the class, the corresponding napi_callback is invoked. If the callback is for an instance method or accessor, then the this argument to the callback is the wrapper object; the wrapped C++ instance that is the target of the call can be obtained then by calling napi_unwrap() on the wrapper object.

NB: if a there is no wrap or the wrap is just removed by NapiValue::remove_wrap, return None.

fn remove_wrap<T>(&mut self) -> NapiResult<T>

Retrieves a native instance that was previously wrapped in the JavaScript object js_object using napi_wrap() and removes the wrapping. If a finalize callback was associated with the wrapping, it will no longer be called when the JavaScript object becomes garbage-collected.

fn type_tag_object(&self, tag: &NapiTypeTag) -> NapiResult<()>

Associates the value of the type_tag pointer with the JavaScript object. napi_check_object_type_tag() can then be used to compare the tag that was attached to the object with one owned by the addon to ensure that the object has the right type. If the object already has an associated type tag, this API will return napi_invalid_arg.

fn check_object_type_tag(&self, tag: &NapiTypeTag) -> NapiResult<bool>

Compares the pointer given as type_tag with any that can be found on js_object. If no tag is found on js_object or, if a tag is found but it does not match type_tag, then result is set to false. If a tag is found and it matches type_tag, then result is set to true.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl NapiValueT for JsArray

impl NapiValueT for JsArrayBuffer

impl NapiValueT for JsBoolean

impl NapiValueT for JsClass

impl NapiValueT for JsDataView

impl NapiValueT for JsDate

impl NapiValueT for JsError

impl NapiValueT for JsGlobal

impl NapiValueT for JsNull

impl NapiValueT for JsNumber

impl NapiValueT for JsObject

impl NapiValueT for JsString

impl NapiValueT for JsSymbol

impl NapiValueT for JsTypedArray

impl NapiValueT for JsUndefined

impl NapiValueT for JsValue

impl<F: NapiValueT> NapiValueT for Function<F>

impl<T> NapiValueT for JsExternal<T>

impl<T: Copy> NapiValueT for JsBigInt<T>

impl<const N: usize> NapiValueT for JsBuffer<N>