BigInt в JSON: определите контракт полей без потерь, прежде чем добавлять replacer

Что это такое

MDN указывает, что JSON.stringify по умолчанию не сериализует значения BigInt и вызывает TypeError. Функция replacer или явное преобразование позволяют их закодировать, но получатель должен знать, как восстановить нужный тип. Преобразование через Number может привести к потере точности, поэтому представление при передаче является частью контракта схемы. MDN BigInt

Почему это важно

Агент может устранить исключение, применив Number ко всем BigInt. Это решает проблему сериализации, но потенциально меняет идентификаторы или счётчики. Определите, нужны ли получателю арифметические операции, сравнение идентичности или отображение, и выберите явное представление, сохраняющее необходимую информацию.

Как применять

• Составьте перечень затронутых полей и их допустимых диапазонов. Отличайте идентификаторы от количественных значений: идентификатор не обязан становиться числовым типом времени выполнения лишь потому, что состоит из цифр.
• Для представления десятичной строкой задайте в схеме правила для знака, ведущих нулей и пустой строки. Преобразуйте BigInt непосредственно в строковую форму, избегая промежуточного Number.
• Если используется объект с меткой типа, определите его точную форму и политику коллизий. Не позволяйте произвольным пользовательским объектам становиться привилегированными числовыми значениями только потому, что в них есть ключ с удобным именем.
• Предложите тестовые сценарии кодирования и восстановления для нуля, отрицательных значений, когда они разрешены, и целых чисел за пределами безопасного диапазона Number у получателя. Проверяйте точное равенство значений после восстановления.
• Проверьте некорректные кодировки и убедитесь, что валидация завершается понятной ошибкой поля. Используйте одну и ту же схему у производителя, потребителя и в сохранённых тестовых данных.

Подводные камни

Универсальный JSON reviver не может определить исходный тип каждой строки, похожей на десятичное число. Глобальное изменение прототипа также влияет на несвязанную сериализацию, поэтому перед его применением проверьте область воздействия. В других языках встроенные целочисленные типы могут иметь иные диапазоны; проверьте каждого реального потребителя. Статья предлагает проверку контракта без потерь и не заявляет ни универсального стандарта кодирования, ни результатов выполненных проверок совместимости.