Serialização de objetos em JavaScript (Node.js)

Serialização de objetos em JavaScript (Node.js): do JSON aos formatos binários

Serialização é o processo de converter uma estrutura de dados complexa (objeto, array, Map, Set) em um formato que pode ser salvo em arquivo, transmitido pela rede ou enviado para outro processo. No Node.js, a serialização é usada em toda parte: desde APIs REST até comunicação entre processos e cache. Neste artigo, vamos explorar as principais ferramentas e bibliotecas para serialização no ambiente Node.js, seus pontos fortes e fracos.

1. JSON nativo: o padrão de facto

A maneira mais simples e popular é usar o objeto global JSON com os métodos JSON.stringify() e JSON.parse(). Ele é suportado nativamente no Node.js sem a necessidade de instalar pacotes adicionais.

Exemplo de serialização básica:

const user = {  name: 'Alexey',  age: 30,  roles: ['admin', 'editor'],  metadata: null};

// Serialização para stringconst jsonString = JSON.stringify(user);console.log(jsonString);// {"name":"Alexey","age":30,"roles":["admin","editor"],"metadata":null}

// Desserialização de volta para objetoconst parsedUser = JSON.parse(jsonString);console.log(parsedUser.name); // Alexey

Limitações do JSON:

Não suporta funções — métodos do objeto serão removidos.
Não suporta referências circulares — causará o erro Converting circular structure to JSON.
Ignora undefined, Symbol, BigInt (este último causará erro).
Converte Date para string — na desserialização, o objeto Date não é restaurado.

Serialização personalizada com replacer:

const data = {  name: 'Teste',  date: new Date(),  secret: 'não salvar',  nested: { value: 42 }};

const json = JSON.stringify(data, (key, value) => {  if (key === 'secret') return undefined; // exclui o campo  if (value instanceof Date) return value.toISOString(); // formata a data explicitamente  return value;}, 2); // formatação com indentação

console.log(json);

2. Serialização via Buffer: para dados binários

Quando é necessário transmitir dados binários (imagens, arquivos, protobuf), usa-se a classe Buffer. No Node.js, Buffer permite converter strings e objetos para formato binário e vice-versa.

Exemplo com Buffer e JSON:

const obj = { message: 'Olá, mundo!' };

// Serializa para JSON, depois para Bufferconst buffer = Buffer.from(JSON.stringify(obj), 'utf-8');console.log(buffer); // <Buffer 7b 22 6d 65 73 73 61 67 65 22 3a 22 d0 9f ...

// De voltaconst restored = JSON.parse(buffer.toString('utf-8'));console.log(restored.message); // Olá, mundo!

Serialização direta de números em Buffer:

const buf = Buffer.alloc(8);buf.writeInt32LE(255, 0); // escreve um inteiro de 32 bitsbuf.writeFloatLE(3.14, 4); // escreve um float

console.log(buf); // representação binária// Leituraconsole.log(buf.readInt32LE(0)); // 255console.log(buf.readFloatLE(4)); // 3.140000104904175

3. Biblioteca flatted: solução para referências circulares

Se o seu objeto contém referências circulares (por exemplo, uma árvore DOM ou um grafo), o JSON padrão não consegue lidar. A biblioteca flatted (autor — Andrea Giammarchi) resolve esse problema.

Instalação e exemplo:

npm install flatted

const { stringify, parse } = require('flatted');

const circularObj = { name: 'Ciclo' };circularObj.self = circularObj; // referência circular

const json = stringify(circularObj);console.log(json);// {"name":"Ciclo","self":"$1"}

const restored = parse(json);console.log(restored.name); // Cicloconsole.log(restored.self === restored); // true