Struct NapiEnv

#[repr(C)]
pub struct NapiEnv(/* private fields */);

Implementations

impl NapiEnv

pub fn from_raw(env: napi_env) -> NapiEnv

create NapiEnv from raw napi_env

pub fn raw(&self) -> napi_env

access raw napi_env from NapiEnv

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

This API returns the global object.

pub fn node_version(&self) -> NapiResult<napi_node_version>

get node version the returned buffer is statically allocated and does not need to be freed.

pub fn napi_version(&self) -> NapiResult<u32>

get napi version

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

Return null object

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

Return undefined object

pub fn int32(&self, value: i32) -> NapiResult<JsNumber>

This API is used to convert from the C int32_t type to the JavaScript number type. The JavaScript number type is described in Section 6.1.6 of the ECMAScript Language Specification.

pub fn uint32(&self, value: u32) -> NapiResult<JsNumber>

This API is used to convert from the C uint32_t type to the JavaScript number type. The JavaScript number type is described in Section 6.1.6 of the ECMAScript Language Specification.

pub fn int64(&self, value: i64) -> NapiResult<JsNumber>

This API is used to convert from the C int64_t type to the JavaScript number type. The JavaScript number type is described in Section 6.1.6 of the ECMAScript Language Specification. Note the complete range of int64_t cannot be represented with full precision in JavaScript. Integer values outside the range of Number.MIN_SAFE_INTEGER -(253 - 1) - Number.MAX_SAFE_INTEGER (253 - 1) will lose precision.

pub fn double(&self, value: f64) -> NapiResult<JsNumber>

This API is used to convert from the C double type to the JavaScript number type. The JavaScript number type is described in Section 6.1.6 of the ECMAScript Language Specification.

pub fn string(&self, s: impl AsRef<str>) -> NapiResult<JsString>

This API creates a JavaScript string value from a UTF8-encoded C string. The native string is copied. The JavaScript string type is described in Section 6.1.4 of the ECMAScript Language Specification.

pub fn array(&self) -> NapiResult<JsArray>

Create an empty js array.

pub fn bigint_i64(&self, value: i64) -> NapiResult<JsBigInt<i64>>

Create a bigint_int64.

pub fn bigint_u64(&self, value: u64) -> NapiResult<JsBigInt<u64>>

Create a bigint_unt64.

pub fn boolean(&self, boolean: bool) -> NapiResult<JsBoolean>

Create a boolean.

pub fn buffer<const N: usize>(&self) -> NapiResult<JsBuffer<N>>

Create a Buffer

pub fn buffer_copy<const N: usize>( &self, data: [u8; N], ) -> NapiResult<JsBuffer<N>>

Create a Buffer from u8

pub fn arraybuffer(&self, buffer: impl AsRef<[u8]>) -> NapiResult<JsArrayBuffer>

Create an ArrayBuffer

pub fn date(&self, time: f64) -> NapiResult<JsDate>

Create a Date.

pub fn symbol(&self) -> NapiResult<JsSymbol>

This API creates a JavaScript symbol value from a UTF8-encoded C string. The JavaScript symbol type is described in Section 19.4 of the ECMAScript Language Specification.

pub fn symbol_description(&self, desc: JsString) -> NapiResult<JsSymbol>

Symbol with description.

pub fn object(&self) -> NapiResult<JsObject>

This API allocates a default JavaScript Object. It is the equivalent of doing new Object() in JavaScript. The JavaScript Object type is described in Section 6.1.7 of the ECMAScript Language Specification.

pub fn context(&self, name: impl AsRef<str>) -> NapiResult<NapiAsyncContext>

The async context

pub fn external<T>( &self, value: T, finalizer: impl FnOnce(NapiEnv, T) -> NapiResult<()> + 'static, ) -> NapiResult<JsExternal<T>>

Create an external data.

pub fn func<T, R>( &self, func: impl FnMut(JsObject, T) -> NapiResult<R> + 'static, ) -> NapiResult<Function<R>>

where T: FromJsArgs, R: NapiValueT,

Create a js function with a rust closure.

pub fn func_named<T, R>( &self, name: impl AsRef<str>, func: impl FnMut(JsObject, T) -> NapiResult<R> + 'static, ) -> NapiResult<Function<R>>

where T: FromJsArgs, R: NapiValueT,

Create a named js function with a rust closure.

pub fn function_named( &self, name: impl AsRef<str>, func: extern "C" fn(env: NapiEnv, info: napi_callback_info) -> napi_value, ) -> NapiResult<Function<JsValue>>

Create a named js function with a rust function

pub fn function( &self, func: extern "C" fn(env: NapiEnv, info: napi_callback_info) -> napi_value, ) -> NapiResult<Function<JsValue>>

Create a js function with a rust function

pub fn class<T, R>( &self, name: impl AsRef<str>, func: impl FnMut(JsObject, T) -> NapiResult<R> + 'static, properties: impl AsRef<[NapiPropertyDescriptor]>, ) -> NapiResult<JsClass>

where T: FromJsArgs, R: NapiValueT,

Create a js class with a rust closure

pub fn async_work<T>( &self, name: impl AsRef<str>, state: T, execute: impl FnMut(&mut T) + Send + 'static, complete: impl FnMut(NapiEnv, NapiStatus, T) -> NapiResult<()> + 'static, ) -> NapiResult<NapiAsyncWork<T>>

Create an async work with shared state

pub fn promise<T, L: NapiValueT + Copy + 'static, R: NapiValueT + Copy + 'static>( &self, work: impl FnMut(&mut T) + Send + 'static, complete: impl FnMut(JsPromise<L, R>, NapiStatus, T) -> NapiResult<()> + 'static, ) -> NapiResult<JsPromise<L, R>>

where T: Default,

Create a promise with a work & complete closure.

pub fn tsfn<Data, R, const N: usize>( &self, name: impl AsRef<str>, func: Function<R>, finalizer: impl FnOnce(NapiEnv) -> NapiResult<()> + 'static, callback: impl FnMut(Function<R>, Data) -> NapiResult<()> + 'static, ) -> NapiResult<NapiThreadsafeFunction<Data, N>>

where R: NapiValueT,

Create a NapiThreadsafeFunction.

pub fn define_properties( &self, object: impl NapiValueT, properties: impl AsRef<[NapiPropertyDescriptor]>, ) -> NapiResult<()>

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

pub fn throw<T: NapiValueT>(&self, to_throw: T) -> NapiResult<()>

This API throws the JavaScript value provided.

pub fn throw_error(&self, msg: impl AsRef<str>) -> NapiResult<()>

This API throws a JavaScript Error with the text provided.

pub fn throw_error_code( &self, msg: impl AsRef<str>, code: impl AsRef<str>, ) -> NapiResult<()>

This API throws a JavaScript Error with the text provided.

pub fn throw_type_error(&self, msg: impl AsRef<str>) -> NapiResult<()>

This API throws a JavaScript TypeError with the text provided.

pub fn throw_type_error_code( &self, msg: impl AsRef<str>, code: impl AsRef<str>, ) -> NapiResult<()>

This API throws a JavaScript TypeError with the text provided.

pub fn throw_range_error( &self, msg: impl AsRef<str>, code: Option<impl AsRef<str>>, ) -> NapiResult<()>

This API throws a JavaScript TypeError with the text provided.

pub fn throw_range_error_code( &self, msg: impl AsRef<str>, code: impl AsRef<str>, ) -> NapiResult<()>

This API throws a JavaScript TypeError with the text provided.

pub fn fatal_error(&self, msg: impl AsRef<str>)

pub fn get_and_clear_last_exception(&self) -> NapiResult<Option<JsError>>

Get and clear last exception This API can be called even if there is a pending JavaScript exception.

pub fn get_last_error_info(&self) -> NapiResult<NapiExtendedErrorInfo>

This API retrieves a napi_extended_error_info structure with information about the last error that occurred.

The content of the napi_extended_error_info returned is only valid up until a Node-API function is called on the same env. This includes a call to napi_is_exception_pending so it may often be necessary to make a copy of the information so that it can be used later. The pointer returned in error_message points to a statically-defined string so it is safe to use that pointer if you have copied it out of the error_message field (which will be overwritten) before another Node-API function was called.

Do not rely on the content or format of any of the extended information as it is not subject to SemVer and may change at any time. It is intended only for logging purposes.

This API can be called even if there is a pending JavaScript exception.

pub fn is_exception_pending(&self) -> NapiResult<bool>

Return true if an exception is pending. This API can be called even if there is a pending JavaScript exception.

pub fn error(&self, msg: impl AsRef<str>) -> NapiResult<JsError>

Create a js Error.

pub fn fatal_exception(&self, err: JsError) -> NapiResult<()>

Trigger an ‘uncaughtException’ in JavaScript. Useful if an async callback throws an exception with no way to recover.

pub fn handle_scope(&self) -> NapiResult<NapiHandleScope>

Create a handle scope

pub fn scope<T>(&self, task: impl Fn(NapiHandleScope) -> T) -> NapiResult<T>

Run in a scope.

pub fn escapable_handle_scope(&self) -> NapiResult<NapiEscapableHandleScope>

Create a escapable handle scope

pub fn escapable_scope<T>( &self, task: impl Fn(NapiEscapableHandleScope) -> T, ) -> NapiResult<T>

Run in an escapable scope.

pub fn add_cleanup_hook<Hook>( &self, hook: Hook, ) -> NapiResult<CleanupHookHandler>

where Hook: FnOnce() -> NapiResult<()>,

Registers fun as a function to be run with the arg parameter once the current Node.js environment exits.

A function can safely be specified multiple times with different arg values.

In that case, it will be called multiple times as well. Providing the same fun and arg values multiple times is not allowed and will lead the process to abort.

The hooks will be called in reverse order, i.e. the most recently added one will be called first.

Removing this hook can be done by using napi_remove_env_cleanup_hook. Typically, that happens when the resource for which this hook was added is being torn down anyway. For asynchronous cleanup, napi_add_async_cleanup_hook is available.

pub fn add_async_cleanup_hook<Hook>( &self, hook: Hook, ) -> NapiResult<Option<AsyncCleanupHookHandler>>

where Hook: FnOnce(AsyncCleanupHookHandler) -> NapiResult<()>,

Registers hook, which is a function of type napi_async_cleanup_hook, as a function to be run with the remove_handle and arg parameters once the current Node.js environment exits.

Unlike napi_add_env_cleanup_hook, the hook is allowed to be asynchronous.

Otherwise, behavior generally matches that of napi_add_env_cleanup_hook.

If remove_handle is not NULL, an opaque value will be stored in it that must later be passed to napi_remove_async_cleanup_hook, regardless of whether the hook has already been invoked. Typically, that happens when the resource for which this hook was added is being torn down anyway.

pub fn adjust_external_memory(&self, changes: i64) -> NapiResult<i64>

This function gives V8 an indication of the amount of externally allocated memory that is kept alive by JavaScript objects (i.e. a JavaScript object that points to its own memory allocated by a native module). Registering externally allocated memory will trigger global garbage collections more often than it would otherwise.

pub fn run_script<R: NapiValueT>( &self, script: impl AsRef<str>, ) -> NapiResult<R>

This function executes a string of JavaScript code and returns its result with the following caveats:

• Unlike eval, this function does not allow the script to access the current lexical scope, and therefore also does not allow to access the module scope, meaning that pseudo-globals such as require will not be available.
• The script can access the global scope. Function and var declarations in the script will be added to the global object. Variable declarations made using let and const will be visible globally, but will not be added to the global object.
• The value of this is global within the script.

pub fn get_uv_event_loop(&self) -> NapiResult<uv_loop_s>

pub fn set_instance_data<T, F>(&self, data: T, finalizer: F) -> NapiResult<()>

where F: FnOnce(NapiEnv, T) -> NapiResult<()>,

This API associates data with the currently running Agent. data can later be retrieved using napi_get_instance_data(). Any existing data associated with the currently running Agent which was set by means of a previous call to napi_set_instance_data() will be overwritten. If a finalize_cb was provided by the previous call, it will not be called.

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

This API retrieves data that was previously associated with the currently running Agent via napi_set_instance_data(). If no data is set, the call will succeed and data will be set to NULL.

Trait Implementations

impl AsRef<*mut napi_env__> for NapiEnv

fn as_ref(&self) -> &napi_env

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for NapiEnv

fn clone(&self) -> NapiEnv

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for NapiEnv

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Copy for NapiEnv