# Conversões de tipos

Todo argumento exportado deve implementar FromNapiValue (ou um dos traits de conversão por referência), e todo valor retornado deve implementar ToNapiValue. O tipo TypeScript gerado é uma documentação útil, mas é a implementação do trait Rust que determina se uma conversão está realmente disponível.

Esta referência descreve o runtime bindgen do napi-rs v3. Para handles de baixo nível, como JsString e JsObject, consulte Env e valores de baixo nível.

# Legenda de direção

# Valores primitivos

i64 é mapeado deliberadamente para number, enquanto i64n é mapeado para bigint. Prefira o wrapper apenas quando a API JavaScript realmente precisar expor um BigInt.

#[napi]
pub fn inspect_bigint(value: BigInt) -> Result<u64> {
  let (negative, narrowed, lossless) = value.get_u64();
  if negative || !lossless {
    return Err(Error::from_reason("value does not fit in u64"));
  }
  Ok(narrowed)
}

O tipo de retorno acima é bigint porque u64 é um tipo BigInt de saída.

# Option, null e undefined

Option<T> tem um mapeamento intencionalmente assimétrico:

Use Null ou Undefined quando a própria distinção fizer parte da API. Use Either<T, Null> ou Either<T, Undefined> quando exatamente um valor nullish for aceito.

#[napi]
pub fn optional_name(value: Option<String>) -> Option<String> {
  value.filter(|name| !name.is_empty())
}

#[napi]
pub fn null_but_not_undefined(value: Either<String, Null>) -> bool {
  matches!(value, Either::B(Null))
}

# Uniões com Either

Either<A, B> até Either26<A, ..., Z> são mapeados para uniões TypeScript. Na entrada, o napi-rs testa as variantes da esquerda para a direita com a implementação de ValidateNapiValue de cada tipo e converte a primeira correspondência.

#[napi]
pub fn normalize_id(value: Either<u32, String>) -> String {
  match value {
    Either::A(number) => number.to_string(),
    Either::B(text) => text,
  }
}

export function normalizeId(value: number | string): string

Ordene alternativas sobrepostas da mais específica para a menos específica. A validação de um Object simples, por exemplo, não consegue provar um schema de objeto completo. Either é uma união em tempo de execução, não um enum sem tag no estilo serde com backtracking após código de usuário arbitrário.

# Arrays, tuplas, maps e sets

A conversão de Vec<T> e coleções é O(n). Use Array, Object, views de typed array com escopo ou um stream quando precisar de acesso incremental, em vez de uma cópia própria.

# Objetos, classes e formas personalizadas

Não trate uma classe como uma forma de objeto. Um campo público normal de leitura e escrita precisa de conversão de saída para o getter e de entrada para o setter; um campo readonly precisa apenas de saída, e um campo de classe ignorado não tem accessor. Para valores de classe aninhados, aceite &T, ClassInstance<T> ou use Array::get_ref; Vec<T> exige uma implementação própria de FromNapiValue e, portanto, não é a forma de aceitar uma lista de instâncias de classe.

Consulte Classes, Objetos, Enums e Atributos #[napi] para exemplos específicos de cada forma.

# Buffers, ArrayBuffers e typed arrays

Buffers e ArrayBuffers externos podem ser zero-copy quando o runtime aceita armazenamentos subjacentes externos. Um runtime pode rejeitar buffers externos; construtores como BufferSlice::from_data então recorrem a uma cópia. Não prometa comportamento zero-copy em todo runtime compatível com Node. Consulte Typed arrays e Entendendo o ciclo de vida.

# Datas e JSON com serde

serde_json::Value não é uma representação sem perdas de JavaScript arbitrário. Em particular, um BigInt de entrada grande pode se tornar um número JSON quando couber ou uma string decimal quando não couber. Use BigInt quando a identidade BigInt e as regras exatas de estreitamento importarem.

serde-json-ordered também habilita o comportamento preserve_order do serde_json.

# Funções, Promises e streams

ReadableStream::new verifica se o runtime fornece um ReadableStream global. Node-API 4 sozinho não garante o global de Web Streams; with_readable_stream_class aceita explicitamente um construtor compatível.

# Dados nativos externos

External<T> expõe ao JavaScript uma alocação nativa opaca e com tag de tipo. Ela não é serializada e seu tipo gerado é ExternalObject<T>.

• Retorne um External<T> próprio para transferi-lo para um valor external JavaScript.
• Aceite &External<T> ou &mut External<T> para tomar emprestado e verificar o tipo do valor encapsulado.
• Use ExternalRef<T> quando o Rust precisar manter uma referência JavaScript para o external.
• External::new_with_size_hint informa ao coletor de lixo JavaScript o tamanho da alocação nativa; o número é uma dica contábil para o GC, não um limite de memória.

Consulte External para detalhes do ciclo de vida.

# Validação não é coerção

A maioria das funções geradas converte de acordo com sua implementação de FromNapiValue. Adicionar #[napi(strict)] primeiro chama ValidateNapiValue e rejeita um tipo JavaScript incompatível no nível superior. Isso não converte strings em números nem valida recursivamente cada propriedade antes da conversão.

#[napi(return_if_invalid)] faz a mesma validação, mas retorna undefined para uma entrada inválida em vez de lançar uma exceção. Consulte Atributos #[napi] para conhecer suas restrições.

# Escolhendo um modelo de propriedade

Use esta ordem de preferência:

1. Use valores Rust próprios (String, Vec<T>, #[napi(object)]) quando uma cópia for aceitável e o valor precisar atravessar threads ou pontos de await.
2. Use handles e slices com escopo (Object<'env>, Array<'env>, BufferSlice<'env>, slices de typed array) para acesso síncrono com zero ou poucas cópias.
3. Use wrappers que retêm referências (Buffer, ObjectRef, FunctionRef, Reference<T>) quando dados pertencentes ao JavaScript precisarem sobreviver ao callback.
4. Use ThreadsafeFunction para invocar JavaScript de outra thread; nunca mova para lá um handle JavaScript com escopo.
5. Use um stream quando os dados precisarem ser produzidos de forma incremental, em vez de copiados para uma única coleção.

O compilador impõe muitos desses limites por meio de lifetimes e Send, mas um método unsafe ou handle bruto do Node-API pode ignorá-los. Leia Entendendo o ciclo de vida antes de fazer isso.