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.

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 2O 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
- SDK de Node.js, sdk/node/exemplo.js
- README dos SDKs do jsonW
- llms.txt do repositório jsonW
- README principal do jsonW
- Página oficial do jsonW
- Página para desenvolvedores da Wortic
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 consultorEquipe editorial
Equipe editorial da Wortic especializada em automacao, IA, ERP, CRM e crescimento operacional.
- Automacao com IA
- Gestao empresarial
- CRM
- ERP
- Marketing digital
