Tutoriais

jsonW: qual versão de Node, PHP e Python eu preciso?

No jsonW, o piso de Node é 22.12 e o de PHP é 8.4. Testei Node 26 e PHP 8.5 no Mac e mostro onde a documentação se contradiz sobre C++ e Swift.

Por Equipe Wortic 9 min de leitura

No jsonW, a versão mínima de Node.js para o SDK é a 22.12, segundo o campo engines do pacote npm e a página llms.txt do repositório. Para PHP, a mesma página pede PHP 8.4 ou mais novo, e para Python, 3.10. Mas os documentos não batem em todas as linguagens. Este texto mostra o que rodei de verdade neste Mac, com Node 26.13.1 e PHP 8.5.12, e o que ficou sem prova.

Quais versões a documentação pede?

A página llms.txt do repositório jsonW traz uma lista de linguagens com a versão de cada SDK. Nela aparecem “Node.js 22.12+ and TypeScript”, “PHP 8.4+ (Composer, Laravel, WordPress)” e “Python 3.10+”. A mesma página cita Ruby 4, Rust 2024, Java 22 ou mais novo, Swift 6 e C++23. O arquivo package.json do pacote npm declara o mesmo piso para o Node, com o campo engines pedindo node 22.12 ou mais novo.

  • Node.js: 22.12 ou mais novo.
  • PHP: 8.4 ou mais novo, com a extensão FFI, que depende da biblioteca libffi instalada.
  • Python: 3.10 ou mais novo, sem dependências extras.
  • Java e Kotlin: Java 22 ou mais novo, pela API FFM, sem JNI.
  • Ruby 4, Rust 2024, Swift 6 e C++23, segundo o llms.txt.

Por que os documentos não batem?

A tabela de SDKs do README do diretório sdk escreve “C++17” e “Swift 5+”, enquanto o llms.txt escreve “C++23” e “Swift 6”. O mesmo README escreve “PHP 8” e não “PHP 8.4”. Eu não sei qual dos dois está certo para cada SDK, e não rodei C++ nem Swift neste Mac. O que dá para afirmar é o que cada documento diz. Quem depende de uma versão específica de C++ ou de Swift deve confirmar no repositório antes de travar a versão no projeto.

Como eu testei o Node?

O teste usou o SDK que está no próprio repositório, em sdk/node/index.js, sem criar nenhum arquivo .js. Antes de carregar a biblioteca, confirmei a versão do Node instalada no Mac. A saída de node -v foi v26.13.1, bem acima do piso de 22.12.

  1. Carreguei o SDK pelo caminho do repositório, com a opção --input-type=module, que deixa o Node ler import direto da linha de comando.
  2. Abri o arquivo de vendas, com seis linhas, e pedi o número de linhas, os campos, um campo de uma linha, uma linha em texto e a conferência de custódia.
  3. Gravei um arquivo novo com o Escritor, a partir de um texto em jsonW, e li o arquivo de volta.
node --input-type=module -e "
import { Leitor, Escritor, versao } from 'CAMINHO/sdk/node/index.js';
console.log('node', process.version, 'versao addon', versao);
const a = new Leitor('vendas.jsw');
console.log('linhas', a.linhas, 'campos', a.campos.join(','));
console.log('campo(0,produto)', a.campo(0, 'produto'));
console.log('texto(1)', a.texto(1));
console.log('conferir', a.conferir());
a.fechar();
const w = new Escritor('node-teste.jsw', 'id:i64,nome:texto,preco:dinheiro');
w.gravarTexto('{id:7,nome:"Teste node",preco:3.10 BRL}');
w.fechar();
const b = new Leitor('node-teste.jsw');
console.log('gravado', b.linhas, b.texto(0), b.conferir());
b.fechar();
"
node v26.13.1 versao addon 1.3.14
linhas 6 campos id,produto,uf,preco,estoque
campo(0,produto) Cafe especial
texto(1) {id:2,produto:"Cha verde",uf:"RJ",preco:8.90 BRL,estoque:12}
conferir true
gravado 1 {id:7,nome:"Teste node",preco:3.10 BRL} true

Duas coisas chamam a atenção nessa saída. A primeira é a versão do addon, que o próprio SDK informa como 1.3.14, enquanto o binário wjsw do mesmo pacote diz 1.4.1. Eu registrei as duas e não tentei decidir qual vale para o seu caso. A segunda é que o comentário do próprio index.js diz que o recurso using é do Node 24 em diante, e que, no Node 22, é preciso chamar fechar() no fim. Por isso, no teste, eu chamei fechar() à mão em todos os recursos.

Como eu testei o PHP?

O PHP do Mac é a versão 8.5.12, com a extensão FFI carregada. O SDK de PHP usa FFI para chamar a biblioteca libjsonw, e a classe que faz isso procura o caminho da biblioteca primeiro na variável de ambiente JSONW_LIB. Por isso, apontei essa variável para a biblioteca do pacote macos-arm64.

  1. Confirmei a extensão com php -r. A saída foi 8.5.12 ffi=sim.
  2. Defini JSONW_LIB com o caminho do arquivo libjsonw.dylib do pacote macos-arm64.
  3. Carreguei o SDK com require e li as linhas do mesmo arquivo de vendas.
php -r 'require "CAMINHO/sdk/php/jsonw.php"; $a = new JsonW\Leitor("vendas.jsw"); echo "php ", PHP_VERSION, " linhas=", count($a), PHP_EOL; foreach ($a as $i => $l) { if ($i > 1) break; echo $a->texto($i), PHP_EOL; } echo "conferir=", var_export($a->conferir(), true), PHP_EOL;'
php 8.5.12 linhas=6
{id:1,produto:"Cafe especial",uf:"SP",preco:12.50 BRL,estoque:40}
{id:2,produto:"Cha verde",uf:"RJ",preco:8.90 BRL,estoque:12}
conferir=true

O teste de PHP cobre a versão 8.5, e não a 8.4 nem a 8.3. A documentação pede 8.4 ou mais novo, então esse número é o piso que o llms.txt declara, mas eu não rodei o SDK na versão exata do piso.

Que erro aparece se a biblioteca não estiver no lugar?

Esse erro eu não provoquei de propósito, então a mensagem abaixo vem do código-fonte e não de uma execução. No SDK de Node, quando o addon não é encontrado, a função lança uma mensagem que começa com “jsonw: sem addon para” e termina com a orientação para compilar com make node dentro do diretório sdk. No meu Mac, a plataforma seria darwin-arm64. No SDK de PHP, a mensagem começa com “libjsonw nao encontrada” e manda apontar JSONW_LIB para a biblioteca. Se você vir uma dessas mensagens, o problema não é a versão da linguagem, e sim o caminho do arquivo binário.

Quando usar essas versões, e quando não usar?

Use o SDK de Node se o seu servidor já roda Node 22.12 ou mais novo, porque é o piso que o pacote declara. Use o SDK de PHP se o servidor roda PHP 8.4 ou mais novo com a extensão FFI, e com a biblioteca libffi instalada. A página de requisitos da FFI no manual do PHP diz, em inglês, “This extension requires the libffi library to be installed.” Não use esta lista como garantia para Python: eu não rodei o SDK de Python neste texto, e o piso de 3.10 vem só da documentação do repositório. Também não use para C++ ou Swift sem antes confirmar qual versão o projeto espera, porque os documentos se contradizem. Para saber quais versões do Node seguem com suporte, consulte a página de versões anteriores do Node.js.

O que a documentação não cobre?

A documentação não traz uma tabela de versão mínima por sistema operacional. O README do repositório diz que Linux binaries need glibc 2.34+, e cita Ubuntu 22.04 ou mais novo, Debian 12 ou mais novo e RHEL 9 ou mais novo. Isso é um requisito de sistema, e vale mesmo que o Node ou o PHP estejam na versão certa. Outro ponto em aberto é o Python: o piso de 3.10 aparece no llms.txt, mas não há teste publicado dele neste texto, e eu não rodei nenhum código Python, porque a regra deste trabalho proíbe Python. Por fim, não encontrei, nos documentos que li, uma tabela que diga qual versão do addon de Node acompanha cada versão do pacote. Eu encontrei 1.3.14 dentro de sdk/node, e o binário wjsw diz 1.4.1.

Como verificar a versão no seu ambiente?

Para conferir o seu caso, rode node -v e php -r 'echo PHP_VERSION;' e compare com o piso. Depois, carregue o SDK do seu idioma e leia um arquivo pequeno, como o de seis linhas deste teste, com conferir. Se a leitura e a conferência passarem, a combinação de linguagem, biblioteca e sistema está funcionando. Se o texto de versão das linguagens que você usa bater com o piso, mas o SDK não carregar, o próximo passo é verificar o caminho da biblioteca e a arquitetura do processador.

Onde a Wortic entra nisso?

O jsonW é publicado pela Wortic, e o código público fica no repositório developer-wortic/jsonw. Quem usa Claude ou ChatGPT encontra a ligação com a Wortic na página sobre como usar a Wortic dentro do Claude e do ChatGPT. A página para desenvolvedores reúne as APIs abertas e a documentação de uso. Os planos da Wortic ficam na página de planos.

Perguntas frequentes

Qual é a versão mínima de Node para o jsonW?

O campo engines do pacote npm pede node 22.12 ou mais novo, e o llms.txt diz Node.js 22.12+. Neste Mac, o SDK carregou com Node 26.13.1. Não testei versões abaixo de 22.12.

Como confirmar se o SDK funciona no meu ambiente?

Carregue o SDK da sua linguagem, abra um arquivo pequeno de jsonW e rode a conferência. Se a leitura funcionar e a conferência passar, a versão da linguagem e o caminho da biblioteca estão certos.

Quais versões ficaram sem teste?

Não rodei Python, C++ nem Swift. O PHP foi testado só na versão 8.5.12. Os documentos se contradizem sobre C++ e Swift, então confirme no repositório antes de travar a versão.

Fontes

Conheça: jsonW (json Wondrous): o formato de dados da Wortic.

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.