---
title: 'Env'
description: Acesse o Node-API de baixo nível.
---

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` <sub>_requer napi9_</sub>

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 {6,10}
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 {6,9}
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>
```