BigInt em JSON: defina um contrato de campo sem perdas antes de adicionar um replacer

O que é

A MDN documenta que JSON.stringify não serializa valores BigInt por padrão e lança um TypeError. Um replacer ou uma conversão explícita pode codificá-los, mas o receptor precisa saber como reconstruir o tipo pretendido. Converter via Number pode causar perda de precisão, portanto a representação de transporte faz parte do contrato do esquema. MDN BigInt

Por que importa

Um agente pode corrigir a exceção aplicando Number a todo BigInt. Isso resolve a serialização, mas pode alterar identificadores ou contadores. Decida se o receptor precisa de aritmética, comparação de identidade ou exibição, e escolha uma representação explícita que preserve a informação necessária.

Como aplicar

• Faça o inventário dos campos afetados e das faixas de valores permitidas. Distinga identificadores de quantidades: um identificador não precisa virar um tipo numérico em tempo de execução só porque contém dígitos.
• Para uma representação em string decimal, especifique no esquema as regras de sinal, de zeros à esquerda e de string vazia. Converta diretamente do BigInt para a sua forma em string, evitando um intermediário Number.
• Se usar um objeto com tag, defina o formato exato e a política de colisão. Não deixe que objetos arbitrários de usuário se tornem valores numéricos privilegiados apenas porque contêm uma chave com nome conveniente.
• Proponha fixtures de ida e volta para zero, para valores negativos quando permitidos e para inteiros fora da faixa segura de Number do receptor. Verifique a igualdade exata do valor após a reconstrução.
• Teste codificações malformadas e garanta que a validação falhe com um erro claro no campo. Mantenha o mesmo esquema no produtor, no consumidor e nas fixtures armazenadas.

Armadilhas

Um reviver JSON genérico não consegue inferir o tipo original de toda string com aparência decimal. Uma modificação global de protótipo também afeta serializações não relacionadas, por isso avalie o seu alcance antes de adotá-la. Outras linguagens podem ter faixas nativas de inteiros diferentes; teste cada consumidor real. Este artigo propõe uma revisão de contrato sem perdas e não afirma a existência de um padrão universal de codificação nem apresenta resultados executados de interoperabilidade.