# Atributos #[napi]

O macro #[napi] exporta itens Rust e controla o comportamento deles em tempo de execução no JavaScript e as declarações TypeScript geradas. Esta página abrange todas as opções públicas aceitas pelo napi-derive v3, incluindo as duas opções específicas de contexto analisadas em parâmetros e variantes de enum.

use napi::bindgen_prelude::*;
use napi_derive::napi;

#[napi(js_name = "addOne", strict)]
pub fn add_one(value: u32) -> u32 {
  value + 1
}

# Alvos compatíveis

Nas tabelas abaixo:

• Função significa uma função livre exportada.
• Método inclui métodos de instância, métodos estáticos, fábricas, construtores, getters e setters quando a opção fizer sentido.
• Classe significa uma struct exportada com identidade de classe. Uma struct object, array ou transparent é uma forma de valor.
• Campo significa um campo de struct ou de uma variante de enum estruturado.

Com o recurso padrão napi-derive/strict, uma opção aceita pelo analisador, mas não utilizada naquele tipo de item, causa um erro de compilação. Prefira as combinações documentadas aqui em vez de depender do comportamento com strict desabilitado.

# Nomes e exportações

Um módulo Rust inline pode ser convertido em um namespace JavaScript. Somente os filhos que também têm #[napi] são exportados, e módulos napi aninhados não são compatíveis.

#[napi(js_name = "math")]
mod arithmetic {
  #[napi]
  pub fn add(a: u32, b: u32) -> u32 {
    a + b
  }
}

export namespace math {
  export function add(a: number, b: number): number
}

# module_exports

O callback deve ser uma função livre não genérica. Ele só pode aceitar Env, Object ou referências a eles e só pode retornar () ou Result<()>. Não pode ser combinado com constructor, factory, getter, setter, js_name, strict, return_if_invalid nem no_export.

#[napi(module_exports)]
pub fn initialize(mut exports: Object) -> Result<()> {
  exports.set("build", "release")?;
  Ok(())
}

Para uma inicialização que não precise do objeto exports, consulte Inicialização de módulo.

# Funções e métodos

strict e return_if_invalid são mutuamente exclusivos. Eles validam a implementação de ValidateNapiValue do tipo Rust; não fazem validação arbitrária de schema. Os elementos de um Vec<T> aninhado são convertidos um a um, e a conversão ainda pode falhar depois da verificação inicial do array.

A validação executa no callback JavaScript gerado antes que uma future Rust assíncrona seja criada. Em um export assíncrono, strict pode portanto lançar uma exceção sincronamente, enquanto return_if_invalid retorna undefined síncrono para uma entrada inválida, em vez de uma Promise. Esses atributos não alteram o tipo de retorno assíncrono gerado; documente esse caminho excepcional.

# Classes e formas de valor

Os controles de direção são controles de compilação: desabilitar uma direção remove a implementação do trait de conversão correspondente. Isso é útil para formas somente de entrada que contêm callbacks ou formas somente de saída que contêm dados que não podem ser lidos do JavaScript.

#[napi(object, object_to_js = false)]
pub struct Request {
  pub path: String,
  pub on_chunk: ThreadsafeFunction<Buffer>,
}

#[napi(transparent)]
pub struct UserId(pub String);

#[napi(array)]
pub struct Point(pub f64, pub f64);

Para um campo de object ou enum estruturado, o modo padrão aceita uma propriedade ausente como None e omite None na saída. Um valor presente é convertido como o T interno, portanto null e undefined não são aceitos universalmente. Com use_nullable = true, a propriedade é obrigatória, a conversão de Option<T> aceita null como None, e a saída usa null; uma propriedade ausente ou undefined ainda é rejeitada. Arrays aplicam a mesma distinção a um índice de tupla ausente ou obrigatório contendo null. Em uma classe, acessores e argumentos do construtor abreviado já usam a conversão normal de Option<T>, e getters retornam null para None; use_nullable muda apenas a forma TypeScript gerada.

# Campos

Em uma classe normal, skip remove o acessor JavaScript gerado, enquanto skip_typescript mantém o acessor em tempo de execução e oculta apenas sua declaração. Em um object, array ou enum estruturado, skip e readonly afetam a declaração gerada, mas a conversão em tempo de execução ainda processa o campo. Evite skip com a forma abreviada de struct #[napi(constructor)]: o construtor gerado ainda consome todos os campos, embora o campo omitido não apareça na assinatura TypeScript.

# Enums

Os nomes de case aceitos são lowercase, UPPERCASE, PascalCase, camelCase, snake_case, UPPER_SNAKE, kebab-case e UPPER-KEBAB-CASE.

#[napi(string_enum = "kebab-case")]
pub enum Mode {
  ReadOnly,
  #[napi(value = "read-write")]
  Writable,
}

#[napi(discriminant = "kind", discriminant_case = "camelCase")]
pub enum Event {
  Ready,
  FileChanged { path: String },
  Progress(u32, u32),
}

string_enum aceita somente variantes sem campos e não pode ser combinado com discriminantes Rust explícitos. Um enum que contém qualquer variante com dados é um enum estruturado; cada variante se torna um objeto com o discriminador e seus campos. Um campo cujo nome JavaScript seja igual ao discriminador é rejeitado.

# Substituições de TypeScript

#[napi(
  ts_generic_types = "T",
  ts_args_type = "value: T",
  ts_return_type = "T"
)]
pub fn identity<'env>(value: Unknown<'env>) -> Unknown<'env> {
  value
}

#[napi(ts_type = "(operation: 'add' | 'subtract', a: number, b: number): number")]
pub fn calculate(operation: String, a: i32, b: i32) -> i32 {
  match operation.as_str() {
    "add" => a + b,
    "subtract" => a - b,
    _ => 0,
  }
}

Essas strings são inseridas na declaração gerada; o napi-rs não as analisa como TypeScript nem verifica se descrevem o comportamento em tempo de execução. Mantenha as conversões em tempo de execução como fonte autoritativa e teste o arquivo .d.ts gerado.

# Iteradores

iterator e async_iterator são mutuamente exclusivos. Uma classe geradora não pode expor campos públicos chamados next, return ou throw, pois o napi-rs instala esses métodos de protocolo. Consulte Iteradores e iteradores assíncronos para ver os traits obrigatórios e as restrições de ciclo de vida.

# Índice de opções

O analisador geral aceita estas opções:

catch_unwind, async_runtime, module_exports, js_name, constructor, factory, getter, setter, readonly, enumerable, writable, configurable, skip, strict, return_if_invalid, object, object_from_js, object_to_js, custom_finalize, namespace, iterator, async_iterator, ts_args_type, ts_return_type, ts_type, ts_generic_types, string_enum, use_nullable, discriminant, discriminant_case, transparent, array, no_export e skip_typescript.

Os analisadores específicos de contexto também aceitam ts_arg_type em um parâmetro de função e value em uma variante de string enum.