Tutoriais

jsonW no Node.js: como ler com o addon N-API

O SDK de Node.js do jsonW é um addon N-API. Veja como instalar pelo npm, rodar o exemplo oficial e usar using para fechar o Leitor.

Por Equipe Wortic 6 min de leitura

No Node.js, o SDK do jsonW é um addon N-API que fica em sdk/node. Você pode instalar o pacote com npm install @wortictecnologia/jsonw, que traz binário pronto para macOS arm64 e Linux x64, ou compilar o addon com make node, como manda o README dos SDKs. Depois, new Leitor abre o arquivo e indexa um campo pelo nome.

O formato, em uma frase, é o seguinte. Segundo a página oficial do jsonW, ele tem três formas sem perda (linha, coluna e texto), 19 recursos e está na versão 1.4.1. Todo JSON vale como jsonW, então os objetos que sua aplicação Node já produz podem ser gravados sem conversão.

Instalar pelo npm ou compilar o addon?

O pacote npm traz o addon já compilado para macOS arm64 e Linux x64, com tipos TypeScript e o comando jsonw. O comando de instalação na página oficial aponta a versão 1.4.1. Se a sua plataforma não está nessa lista, compile o addon a partir de sdk/node com make node, como indica o README dos SDKs.

Os binários de Linux pedem glibc 2.34 ou mais novo, o que cobre Ubuntu 22.04 ou mais novo, Debian 12 ou mais novo e RHEL 9 ou mais novo. Verifique isso antes de subir a aplicação para um servidor antigo.

Como abrir e ler com Leitor?

O exemplo oficial, em sdk/node/exemplo.js, recebe o arquivo, o campo e o valor. No Node, indexar recebe o nome do campo; na ABI C, jsonw_indexar recebe o número da coluna. O cabeçalho do exemplo mostra o comando:

node exemplo.js dados.jsw id 2

O cabeçalho também diz que o exemplo pede Node 24 ou mais novo, porque usa a instrução using. O llms.txt do repositório fala em Node.js 22.12 ou mais novo para o pacote. As duas indicações não batem, então teste na sua versão antes de copiar o exemplo para produção.

O núcleo do exemplo começa assim, com o Leitor dentro de using:

using a = new Leitor(arquivo);

Antes de buscar, o exemplo confere se o campo existe na lista de campos. Depois, indexa o campo pelo nome, a menos que receba a opção --varrer, e percorre as linhas do valor com for ... of sobre a.chave(campo, JSON.parse(texto)).

Por que usar using?

A instrução using libera o Leitor ao sair do bloco, sem depender de chamar close à mão. É a mesma ideia do RAII do C++, aplicada ao JavaScript. Assim, o arquivo não fica aberto por esquecimento, mesmo quando a função termina antes do esperado.

Para o Escritor, a regra é outra e pede atenção. O README dos SDKs diz que só fechar publica o arquivo, e que quem sai por erro no meio da gravação deve chamar abandonar em vez de fechar. Se você usa um bloco parecido com using para gravar, trate o erro antes de fechar.

As operações de avaliar e escolher chegam ao Node?

O repositório traz um arquivo de operações para o Node, em sdk/node/jsonw_node_ops.c, ao lado do addon. O README dos SDKs descreve avaliar, que dá a nota de cada linha por pesos, cosseno, esparso ou grade, e escolher, que pega as k maiores notas. O pedido de avaliar é um JSON, o que facilita montar o pedido direto em JavaScript.

Antes de usar essas operações em produção, leia o arquivo de operações do Node e rode o exemplo com a sua massa de dados. O mesmo README diz que o avaliar lê só as colunas do pedido, em paralelo, e o ganho de tempo depende do seu arquivo e da sua máquina, então meça com os seus dados.

Por que indexar antes de buscar?

No Node, a.indexar com o nome do campo roda uma vez, e depois cada a.chave é uma busca binária. O README principal mede a diferença num arquivo de 1 milhão de linhas: a mediana de 200 buscas por id levou 142,8 ms varrendo e 0,196 ms com índice, com o índice montado em 193 ms. Os números são de macOS arm64 com a versão 1.3.13.

Qual nome de método vale: linha ou json?

O README principal usa a.linha(i) nos exemplos de Node e de Python. O exemplo do SDK em sdk/node usa a.json(i), e o README dos SDKs lista json(i) e texto(i) para ler uma linha. Antes de copiar um trecho, confira o nome do método na versão que você instalou com npm, porque os nomes podem mudar entre versões.

Quais limites considerar em Node.js?

  • Versão do Node: o cabeçalho do exemplo pede Node 24 ou mais novo, e o llms.txt cita Node.js 22.12 para o pacote. Teste a versão que você usa.
  • Plataforma: o pacote npm traz binário pronto para macOS arm64 e Linux x64. Outras plataformas exigem compilar o addon com make node.
  • Versão do jsonW: a página oficial informa a 1.4.1, e o llms.txt do repositório ainda cita a 1.3.14.

Para quem quer um painel de consulta de empresas ou CEPs sem montar um banco, a Wortic oferece APIs abertas com documentação na página para desenvolvedores. Para o conector que liga a conta Wortic ao Claude ou ao ChatGPT, veja a página de conexão. Os planos da Wortic estão em wortic.com.br/planos.

O código público do jsonW está em github.com/developer-wortic/jsonw. A Wortic, empresa brasileira, criou e mantém o formato, sob a licença Sustainable Use, do modelo fair-code.

Perguntas frequentes

O que é o SDK em Node.js (addon N-API)?

É um addon N-API que fica em sdk/node, com as classes Leitor e Escritor. Ele pode ser instalado pelo npm, com o pacote @wortictecnologia/jsonw, ou compilado com make node. O addon segue a mesma ABI C de todos os outros SDKs.

Como usar o SDK em Node.js na prática?

Crie o Leitor com o caminho do arquivo, confira campo com a.campos.includes e rode busca com a.chave(campo, valor). Para cada linha, use a.json(i). O exemplo oficial roda com node exemplo.js dados.jsw id 2.

Quais são os limites do SDK em Node.js?

O exemplo pede Node 24 ou mais novo por causa de using, e o llms.txt fala em Node.js 22.12 para o pacote, então teste a versão. Os binários prontos cobrem macOS arm64 e Linux x64, e Linux pede glibc 2.34 ou mais novo.

Fontes

Conheça: jsonW em Node.js pelo npm.

Quer isso funcionando na sua empresa?

Um consultor da Wortic olha o seu caso e mostra o caminho, sem compromisso.

Falar com um consultor

Equipe editorial

Equipe editorial da Wortic especializada em automacao, IA, ERP, CRM e crescimento operacional.

  • Automacao com IA
  • Gestao empresarial
  • CRM
  • ERP
  • Marketing digital

Isso funcionando no seu negócio.

Um consultor mostra o sistema do seu ramo, com a IA dentro.