Skip to content

Na maioria dos casos, o Node-API fica encapsulado em várias abstrações e estruturas de alto nível do NAPI-RS. No entanto, em alguns cenários, você ainda precisa acessar o Node-API subjacente.

A struct Env fornece acesso ao ambiente do Node-API e permite criar valores JavaScript, lidar com erros, gerenciar memória e interagir com o runtime JavaScript.

Criação de strings e symbols

create_string

Cria uma string JavaScript a partir de um tipo Rust que pode ser convertido em &str.

rust
pub fn create_string<S: AsRef<str>>(&self, s: S) -> Result<JsString<'_>>

Exemplo:

rust
let js_string = env.create_string("Hello, World!")?;

create_string_from_std

Cria uma string JavaScript a partir de uma String do Rust.

rust
pub fn create_string_from_std<'env>(&self, s: String) -> Result<JsString<'env>>

create_string_from_c_char

Cria uma string JavaScript a partir de um ponteiro para string em estilo C. Isso é usado em cenários de C FFI.

INFO

Você pode passar NAPI_AUTO_LENGTH como parâmetro len se a string C for terminada em nulo.

rust
pub unsafe fn create_string_from_c_char<'env>(
  &self,
  data_ptr: *const c_char,
  len: isize,
) -> Result<JsString<'env>>

create_string_utf16

Cria uma string JavaScript a partir de dados codificados em UTF-16.

rust
pub fn create_string_utf16<C: AsRef<[u16]>>(&self, chars: C) -> Result<JsString<'_>>

create_string_latin1

Cria uma string JavaScript a partir de dados codificados em Latin-1.

rust
pub fn create_string_latin1<C: AsRef<[u8]>>(&self, chars: C) -> Result<JsString<'_>>

create_symbol

Cria um symbol JavaScript com uma descrição opcional.

rust
pub fn create_symbol(&self, description: Option<&str>) -> Result<JsSymbol<'_>>

symbol_for

INFO

Requer a feature napi9.

Cria ou recupera um symbol do registro global de symbols.

rust
pub fn symbol_for(&self, description: &str) -> Result<JsSymbol<'_>>

Tratamento de erros

get_last_error_info

Recupera informações estendidas sobre o último erro ocorrido.

rust
pub fn get_last_error_info(&self) -> Result<ExtendedErrorInfo>

throw

Lança qualquer valor JavaScript como exceção.

rust
pub fn throw<T: ToNapiValue>(&self, value: T) -> Result<()>

throw_error

Lança um Error JavaScript com a mensagem fornecida e um código de erro opcional.

rust
pub fn throw_error(&self, msg: &str, code: Option<&str>) -> Result<()>

throw_range_error

Lança um RangeError JavaScript com a mensagem fornecida e um código de erro opcional.

rust
pub fn throw_range_error(&self, msg: &str, code: Option<&str>) -> Result<()>

throw_type_error

Lança um TypeError JavaScript com a mensagem fornecida e um código de erro opcional.

rust
pub fn throw_type_error(&self, msg: &str, code: Option<&str>) -> Result<()>

throw_syntax_error requer napi9

Lança um SyntaxError JavaScript com a mensagem fornecida e um código de erro opcional.

rust
pub fn throw_syntax_error<S: AsRef<str>, C: AsRef<str>>(&self, msg: S, code: Option<C>)

fatal_error

Dispara um erro fatal que encerra o processo imediatamente.

rust
pub fn fatal_error(self, location: &str, message: &str)

fatal_exception

INFO

Requer a feature napi3.

Dispara um uncaughtException em JavaScript. Útil para callbacks assíncronos que lançam exceções irrecuperáveis.

rust
pub fn fatal_exception(&self, err: Error)

create_error

Cria um objeto de erro JavaScript a partir de um Error Rust.

rust
pub fn create_error(&self, e: Error) -> Result<Object<'_>>

Criação de funções e classes

create_function

Cria uma função JavaScript a partir de um callback nativo.

rust
pub fn create_function<Args: JsValuesTupleIntoVec, Return>(
  &self,
  name: &str,
  callback: Callback,
) -> Result<Function<'_, Args, Return>>

Exemplo:

INFO

Você pode acessar o Callback C adicionando o sufixo _c_callback ao nome da função. No exemplo abaixo, custom_function_c_callback é o callback C de custom_function.

lib.rs
rust
use napi::bindgen_prelude::*;
use napi_derive::napi;

#[napi]
pub fn create_function(env: &Env) -> Result<Function<u32, u32>> {
  env.create_function("customFunction", custom_function_c_callback) 
}

#[napi(no_export)]
fn custom_function(input: u32) -> u32 { 
  input * 2
}

INFO

O atributo no_export é usado para impedir que a função seja exportada para o lado JavaScript.

custom_function não é exportada, então ela não fica visível no lado JavaScript. Mas o callback C é usado para criar Function em fn create_function. Você pode usá-lo assim:

index.ts
ts
import { createFunction } from './index.js'

const customFunction = createFunction()
console.log(customFunction(2)) // 4

create_function_from_closure

INFO

Requer a feature napi5.

Cria uma função JavaScript a partir de um closure Rust.

rust
pub fn create_function_from_closure<Args: JsValuesTupleIntoVec, Return, F>(
  &self,
  name: &str,
  callback: F,
) -> Result<Function<'_, Args, Return>>
where
  Return: ToNapiValue,
  F: 'static + Fn(FunctionCallContext) -> Result<Return>,

Exemplo:

lib.rs
rust
use napi::bindgen_prelude::*;
use napi_derive::napi;

#[napi]
pub fn create_function(env: &Env) -> Result<Function<u32, u32>> {
  let var_moved_into_closure = 42; // esta variável é movida para dentro do closure
  env.create_function_from_closure("rustClosure", move |ctx| {
    // obtém o primeiro argumento vindo do lado JavaScript
    let result = var_moved_into_closure + ctx.get::<u32>(0)?; 
    Ok(result)
  })
}

⬇️ ⬇️ ⬇️ ⬇️ ⬇️ ⬇️ ⬇️ ⬇️ ⬇️

index.ts
ts
import { createFunction } from './index.js'

const rustClosure = createFunction()
console.log(rustClosure(2)) // 44

define_class

Cria uma classe JavaScript com o construtor e as propriedades fornecidos.

rust
pub fn define_class<Args: JsValuesTupleIntoVec>(
  &self,
  name: &str,
  constructor_cb: Callback,
  properties: &[Property],
) -> Result<Function<'_, Args, Unknown<'_>>>

Gerenciamento de memória

adjust_external_memory

Indica ao V8 a quantidade de memória alocada externamente mantida viva por objetos JavaScript.

rust
pub fn adjust_external_memory(&self, size: i64) -> Result<i64>

run_in_scope

Executa uma função dentro de um handle scope, o que ajuda a gerenciar a memória de objetos temporários.

rust
pub fn run_in_scope<T, F>(&self, executor: F) -> Result<T>
where
  F: FnOnce() -> Result<T>,

Limpeza do ambiente

add_env_cleanup_hook

INFO

Requer a feature napi3.

Registra um cleanup hook a ser chamado quando o ambiente estiver sendo desmontado.

rust
pub fn add_env_cleanup_hook<T, F>(
  &self,
  cleanup_data: T,
  cleanup_fn: F,
) -> Result<CleanupEnvHook<T>>
where
  T: 'static,
  F: 'static + FnOnce(T),

remove_env_cleanup_hook

INFO

Requer a feature napi3.

Remove um cleanup hook registrado anteriormente.

rust
pub fn remove_env_cleanup_hook<T>(&self, hook: CleanupEnvHook<T>) -> Result<()>
where
  T: 'static,

add_async_cleanup_hook

INFO

Requer a feature napi8.

Registra um cleanup hook assíncrono.

rust
pub fn add_async_cleanup_hook<Arg, F>(&self, arg: Arg, cleanup_fn: F) -> Result<()>
where
  F: FnOnce(Arg),
  Arg: 'static,

add_removable_async_cleanup_hook

INFO

Requer a feature napi8.

Registra um cleanup hook assíncrono removível.

rust
pub fn add_removable_async_cleanup_hook<Arg, F>(
  &self,
  arg: Arg,
  cleanup_fn: F,
) -> Result<AsyncCleanupHook>
where
  F: FnOnce(Arg),
  Arg: 'static,

Execução de scripts e informações do ambiente

run_script

Executa uma string JavaScript e retorna o resultado.

rust
pub fn run_script<S: AsRef<str>, V: FromNapiValue>(&self, script: S) -> Result<V>

Exemplo:

rust
let result: i32 = env.run_script("2 + 2")?;
assert_eq!(result, 4);

get_napi_version

Obtém a versão do N-API (process.versions.napi).

rust
pub fn get_napi_version(&self) -> Result<u32>

get_node_version

Obtém as informações de versão do Node.js.

rust
pub fn get_node_version(&self) -> Result<NodeVersion>

get_module_file_name

INFO

Requer a feature napi9.

Recupera o caminho do arquivo do módulo JS em execução no momento como URL.

rust
pub fn get_module_file_name(&self) -> Result<String>

get_uv_event_loop

INFO

Requer a feature napi2.

Obtém um ponteiro para o event loop libuv subjacente.

rust
pub fn get_uv_event_loop(&self) -> Result<*mut sys::uv_loop_s>

Gerenciamento de dados de instância

set_instance_data

INFO

Requer a feature napi6.

Associa dados ao Agent atualmente em execução.

rust
pub fn set_instance_data<T, Hint, F>(&self, native: T, hint: Hint, finalize_cb: F) -> Result<()>
where
  T: 'static,
  Hint: 'static,
  F: FnOnce(FinalizeContext<T, Hint>),

get_instance_data

INFO

Requer a feature napi6.

Recupera dados previamente associados ao Agent atualmente em execução.

rust
pub fn get_instance_data<T>(&self) -> Result<Option<&'static mut T>>
where
  T: 'static,

Suporte a async e futures

spawn

Executa uma tarefa no thread pool do libuv e retorna um AsyncWorkPromise.

rust
pub fn spawn<T: 'static + Task>(&self, task: T) -> Result<AsyncWorkPromise<T::JsValue>>

spawn_future

INFO

Requer as features tokio_rt e napi4.

Inicia uma future Rust e retorna uma Promise JavaScript.

rust
pub fn spawn_future<
  T: 'static + Send + ToNapiValue,
  F: 'static + Send + Future<Output = Result<T>>,
>(&self, fut: F) -> Result<PromiseRaw<'_, T>>

spawn_future_with_callback

INFO

Requer as features tokio_rt e napi4.

Inicia uma future com um callback para processar o resultado.

rust
pub fn spawn_future_with_callback<
  T: 'static + Send,
  V: ToNapiValue,
  F: 'static + Send + Future<Output = Result<T>>,
  R: 'static + FnOnce(Env, T) -> Result<V>,
>(&self, fut: F, callback: R) -> Result<PromiseRaw<'_, V>>

Criação de datas

create_date

INFO

Requer a feature napi5.

Cria um objeto JavaScript Date a partir de um timestamp.

rust
pub fn create_date(&self, time: f64) -> Result<JsDate<'_>>

Serialização JSON

to_js_value

INFO

Requer a feature serde-json.

Serializa uma struct Rust em um valor JavaScript usando serde.

rust
pub fn to_js_value<'env, T>(&self, node: &T) -> Result<Unknown<'env>>
where
  T: Serialize,

from_js_value

INFO

Requer a feature serde-json.

Desserializa um valor JavaScript em um tipo Rust usando serde.

rust
pub fn from_js_value<'v, T, V>(&self, value: V) -> Result<T>
where
  T: DeserializeOwned,
  V: JsValue<'v>,

Comparação de valores

strict_equals

Executa uma comparação de igualdade estrita entre dois valores JavaScript (equivalente a ===).

rust
pub fn strict_equals<'env, A: JsValue<'env>, B: JsValue<'env>>(
  &self,
  a: A,
  b: B,
) -> Result<bool>
Editar essa página no Github →