BigInt в JavaScript – руководство с примерами

BigInt хранит целые числа за пределами безопасного диапазона Number без потери точности. Используйте его для больших ID и точных вычислений, но передавайте такие идентификаторы через JSON строками. Так значение пройдет путь от API до базы данных и обратно без округления и TypeError.

Почему Number теряет точность на больших целых

Тип Number хранит числа в формате двойной точности IEEE 754. Он поддерживает дроби, но не гарантирует точность произвольных целых.

Безопасный диапазон целых Number находится между −(2^53 − 1) и 2^53 − 1. За его пределами соседние значения могут превратиться в одно число.

console.log(9999999999999999);    // → 10000000000000000

9007199254740992 === 9007199254740993;    // → true

Числовой литерал теряет точность еще до выполнения сравнения. Если приложение получит такой ID, оно может обратиться к другой записи.

JavaScript предоставляет константы для границ безопасного диапазона:

Number.MAX_SAFE_INTEGER;    // → 9007199254740991
Number.MIN_SAFE_INTEGER;    // → -9007199254740991

Number.isSafeInteger(9007199254740991);    // → true
Number.isSafeInteger(9007199254740992);    // → false

Проверяйте Number.isSafeInteger перед преобразованием внешних числовых значений. Функция проверяет целочисленность и безопасный диапазон.

Как создавать BigInt и выполнять вычисления

BigInt представляет целые числа за пределами безопасного диапазона Number. Дробные значения этот тип не поддерживает.

Чтобы создать BigInt, добавьте n в конец целого литерала:

console.log(9007199254740995n);    // → 9007199254740995n
console.log(9007199254740995);     // → 9007199254740996

Большой ID из API передавайте в BigInt строкой. Промежуточное преобразование в Number может испортить последние цифры.

BigInt('9007199254740995');    // → 9007199254740995n
BigInt('0xff');                // → 255n

0b1010n;    // → 10n
0o12n;      // → 10n
0xan;       // → 10n

Оператор typeof возвращает для BigInt строку bigint. Такая проверка помогает функциям различать Number и BigInt.

console.log(typeof 10n);    // → bigint
console.log(typeof 10);     // → number

const value = 10n;
console.log(typeof value === 'bigint');    // → true

BigInt поддерживает сложение, вычитание, умножение, степень, остаток, инкремент и декремент.

10n + 20n;    // → 30n
10n - 20n;    // → -10n
-10n;         // → -10n
10n * 20n;    // → 200n
20n / 10n;    // → 2n
23n % 10n;    // → 3n
10n ** 3n;    // → 1000n

let x = 10n;
console.log(++x);    // → 11n, теперь x равно 11n
console.log(--x);    // → 10n, теперь x равно 10n

Инкремент и декремент меняют переменную, поэтому используйте let. Константа с const вызовет TypeError при попытке присваивания.

Деление BigInt отбрасывает дробную часть в сторону нуля. Оно не округляет результат до ближайшего целого.

25 / 10;       // → 2.5
25n / 10n;     // → 2n
-25n / 10n;    // → -2n

Не переводите обычные счетчики в BigInt без причины. На малых целых Number обычно работает быстрее, а BigInt полезен при требовании точности.

Смешивание Number и BigInt

JavaScript запрещает смешивать Number и BigInt в числовой арифметике. Унарный плюс тоже не работает с BigInt.

10 + 10n;    // → TypeError
+10n;        // → TypeError

Для целочисленного расчета преобразуйте безопасный Number в BigInt. Если исходное значение уже потеряло точность, преобразование сохранит ошибку.

const count = 10;
if (!Number.isSafeInteger(count)) {
    throw new RangeError('Ожидается безопасное целое число');
}

console.log(BigInt(count) + 10n);    // → 20n

Обратное преобразование через Number может потерять точность без ошибки. За пределами 2^53 Number не сообщает о проблеме.

const big = 9007199254740993n;
console.log(Number(big));    // → 9007199254740992
console.log(BigInt(Number(big)) === big);    // → false

Ограничьте BigInt безопасным диапазоном перед передачей в функцию, которая принимает Number.

function toSafeNumber(value) {
    if (typeof value !== 'bigint') {
        throw new TypeError('Ожидается BigInt');
    }
    if (value < BigInt(Number.MIN_SAFE_INTEGER) ||
        value > BigInt(Number.MAX_SAFE_INTEGER)) {
        throw new RangeError('Число выходит за безопасный диапазон');
    }
    return Number(value);
}

console.log(toSafeNumber(10n));    // → 10

Сравнения и логические условия

Строгое равенство учитывает типы. Нестрогое равенство сопоставляет значения во время выполнения, поэтому 10n == 10 возвращает true.

10n === 10;    // → false
10n == 10;     // → true
10n > 5;       // → true
10n < 10.5;    // → true

Для предсказуемого сравнения ID сначала приведите значения к одному типу. BigInt равен false только при значении 0n.

Boolean(5n);    // → true
Boolean(0n);    // → false

Сортировка смешанных массивов

Метод sort() без компаратора сортирует элементы по строковому представлению. Поэтому числовой порядок может нарушиться.

[2n, 10n, 3].sort();    // → [10n, 2n, 3]

Для смешанного массива используйте сравнения вместо вычитания. Вычитание Number и BigInt вызовет TypeError.

const arr = [3n, 10, 2, 1n, 0, -1n];
arr.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
console.log(arr);    // → [-1n, 0, 1n, 2, 3n, 10]

Math и битовые операторы

Методы Math не принимают BigInt. Существующий метод Math.max вызовет TypeError при таких аргументах.

Math.max(2n, 4n, 6n);    // → TypeError

Операторы |, &, ^, ~, << и >> поддерживают BigInt. Смешанные операнды запрещены, а беззнаковый сдвиг >>> не работает.

90 | 115;       // → 123
90n | 115n;     // → 123n
90n | 115;      // → TypeError
8n >> 1n;      // → 4n
8n >>> 1n;     // → TypeError

Конструктор BigInt

Функция BigInt преобразует совместимые значения в примитивный тип bigint. Вызывать ее через new нельзя.

BigInt('10');    // → 10n
BigInt(10);      // → 10n
BigInt(true);    // → 1n
new BigInt(10);  // → TypeError

Дробные числа, null и строки с недопустимым форматом вызывают исключение.

BigInt(10.2);     // → RangeError
BigInt(null);     // → TypeError
BigInt('abc');    // → SyntaxError
BigInt('10.2');   // → SyntaxError

Строка сохраняет все цифры исходного целого. Числовой литерал может получить округленный Number еще до вызова BigInt.

BigInt('9007199254740993');    // → 9007199254740993n
BigInt(9007199254740993);      // → 9007199254740992n

Как передавать большие идентификаторы через JSON

JSON не содержит отдельного типа для BigInt. Обычный JSON.stringify бросает TypeError, если встречает такое значение.

JSON.stringify({ id: 9007199254740993n });    // → TypeError

Передавайте большие ID строками на границах приложения. Поле id_str служит понятным примером такого контракта. Строковые ID встречаются в ответах API Twitter, который сейчас называется X API.

Сериализация и восстановление ID

Преобразуйте BigInt в строку перед сериализацией. После разбора JSON вызовите BigInt для восстановления числа.

const originalId = 9007199254740993n;
const outgoing = JSON.stringify({ id_str: originalId.toString() });
console.log(outgoing);    // → {"id_str":"9007199254740993"}

const incoming = JSON.parse(outgoing);
const restoredId = BigInt(incoming.id_str);
console.log(restoredId === originalId);    // → true

Если ID нужен только для хранения или поиска, оставьте его строкой. Преобразуйте строку в BigInt, когда потребуется арифметика.

Replacer превращает все BigInt в строки, а reviver восстанавливает известные поля при разборе.

const json = JSON.stringify(
    { id_str: 9007199254740993n, count: 2n },
    (key, value) => typeof value === 'bigint' ? value.toString() : value
);

const parsed = JSON.parse(json, (key, value) => {
    if (key === 'id_str' &&
        typeof value === 'string' &&
        /^[0-9]+$/.test(value)) {
        return BigInt(value);
    }
    return value;
});

console.log(parsed.id_str === 9007199254740993n);    // → true
console.log(typeof parsed.count);                    // → string

Другой вариант – задать собственный метод toJSON. Он превратит каждый BigInt в строку при вызове JSON.stringify.

BigInt.prototype.toJSON = function () {
    return this.toString();
};

const json = JSON.stringify({ id: 9007199254740993n });
console.log(json);    // → {"id":"9007199254740993"}

Не преобразовывайте автоматически каждую строку из цифр. Почтовый индекс и номер с ведущими нулями должны оставаться строками.

Если отправитель записал ID обычным JSON-числом, двухаргументный reviver получит уже округленное значение value и не вернет потерянные цифры. В средах с поддержкой третьего аргумента context.source обработчик может прочитать исходный фрагмент JSON, но строковое поле остается более совместимым контрактом.

const damaged = JSON.parse('{"id":9007199254740993}');
console.log(damaged.id);    // → 9007199254740992

Запись и чтение ID в MySQL через mysql2

Для примера используйте MySQL и драйвер mysql2. Перед запуском установите MySQL и Node.js с npm, запустите сервер и подготовьте рабочие имя пользователя, пароль и базу данных.

node --version
npm --version

Обе команды должны вывести номера установленных программ. Если команда не найдена, установите Node.js, откройте новый терминал и повторите проверку.

Если MySQL уже установлен на вашем компьютере, возьмите эти значения из созданного подключения. На сервере компании их выдает администратор. Подставьте их в код вместо значений YOUR_USER, YOUR_PASSWORD и YOUR_DATABASE.

  1. Откройте терминал в пустой папке и выполните npm install mysql2. После установки появится каталог node_modules.
  2. Создайте файл bigint-id.cjs и заполните параметры подключения к запущенному MySQL.
  3. Запустите node bigint-id.cjs. Программа выведет строковый ID и значение true.
const mysql = require('mysql2/promise');

async function main() {
    const original = JSON.parse('{"id_str":"9007199254740993"}');
    const id = original.id_str;

    if (typeof id !== 'string' || !/^[0-9]{1,19}$/.test(id)) {
        throw new TypeError('Ожидается строковый ID из 1–19 цифр');
    }
    if (BigInt(id) > 9223372036854775807n) {
        throw new RangeError('ID выходит за диапазон BIGINT со знаком');
    }

    const connection = await mysql.createConnection({
        host: 'localhost',
        user: 'YOUR_USER',
        password: 'YOUR_PASSWORD',
        database: 'YOUR_DATABASE'
    });

    try {
        await connection.query(
            'CREATE TEMPORARY TABLE bigint_id_demo (id BIGINT PRIMARY KEY)'
        );

        await connection.execute(
            'INSERT INTO bigint_id_demo (id) VALUES (?)',
            [id]
        );

        const [rows] = await connection.execute(
            'SELECT CAST(id AS CHAR) AS id_str FROM bigint_id_demo WHERE id = ?',
            [id]
        );

        if (rows.length !== 1 || rows[0].id_str !== id) {
            throw new Error('Прочитанный ID не совпал с исходным');
        }

        const response = JSON.stringify({ id_str: rows[0].id_str });
        const received = JSON.parse(response);

        console.log(response);
        console.log(received.id_str === original.id_str);
    } finally {
        await connection.end();
    }
}

main().catch((error) => {
    console.error(error.message);
    process.exitCode = 1;
});

Параметр запроса передает ID без конкатенации с SQL. На маршруте JSON → база → JSON значение не проходит через Number.

Если сервер MySQL не запущен или параметры подключения неверны, программа не подключится к базе. Запустите сервер и исправьте значения подключения, затем повторите команду node bigint-id.cjs. При успешном запуске консоль покажет JSON со строковым ID и true.

Для ID со значимыми ведущими нулями используйте текстовый столбец. Значение BIGINT подходит для целых ID без ведущих нулей.

Библиотечные функции BigInt

Функции BigInt.asUintN и BigInt.asIntN приводят значение к фиксированной разрядности. Они сохраняют младшие биты.

  • BigInt.asUintN(width, value) возвращает значение от 0 до 2^width − 1.
  • BigInt.asIntN(width, value) возвращает значение от −2^(width − 1) до 2^(width − 1) − 1.
BigInt.asUintN(8, 257n);    // → 1n, потому что 257 mod 2^8 = 1
BigInt.asUintN(8, -1n);     // → 255n
BigInt.asIntN(8, 255n);     // → -1n

BigInt.asUintN(4, 19n);     // → 3n, потому что 19 mod 2^4 = 3
BigInt.asIntN(4, 9n);       // → -7n

Функции полезны для фиксированной разрядности. Они выполняют приведение по модулю и не заменяют проверку диапазона.

Строковое представление числа

Метод toString(radix) задает основание системы счисления от 2 до 36. Без аргумента он возвращает десятичную строку без суффикса n.

const value = 255n;
value.toString();      // → '255'
value.toString(16);    // → 'ff'
value.toString(2);     // → '11111111'

Метод toLocaleString форматирует число с учетом локали. Используйте такой результат для интерфейса, но не для JSON и параметров запросов.

(12345678901234567890n).toLocaleString('ru-RU');
// → '12 345 678 901 234 567 890'

Массивы BigInt64Array и BigUint64Array

BigInt64Array хранит 64-битные целые со знаком. BigUint64Array хранит 64-битные целые без знака.

const signed = new BigInt64Array([1n, -2n]);
console.log(signed[1]);    // → -2n

const unsigned = new BigUint64Array([-1n]);
console.log(unsigned[0]);  // → 18446744073709551615n

Такие массивы подходят для двоичных данных и фиксированных форматов. Для произвольно больших ID они не подходят без проверки диапазона.

Чем Number отличается от BigInt

Выбирайте тип по требуемой точности и характеру вычислений. Таблица показывает ограничения, которые чаще всего влияют на выбор.

ОперацияNumberBigInt
АрифметикаПоддерживает целые и дробные числаПоддерживает только целые; оба операнда должны быть BigInt
Унарный плюсПоддерживаетсяВызывает TypeError
ДелениеМожет возвращать дробьОтбрасывает дробную часть в сторону нуля
СравнениеОператоры порядка работают с BigIntОператоры порядка работают с Number; === учитывает тип
Битовые операцииПреобразуют операнды в 32-битные целыеРаботают без 32-битного ограничения; >>> не поддерживается
Методы MathПоддерживаютсяНе принимают BigInt
JSON.stringifyСохраняет уже имеющуюся точность NumberБез специального преобразования вызывает TypeError

Поддержка браузерами и транспилинг

BigInt входит в стандарт ES2020. Тип поддерживают Chrome 67+, Edge 79+, Firefox 68+, Safari 14+ и Node.js 10.4+.

Актуальные сведения о BigInt доступны в документации MDN и таблице совместимости Can I use.

Для обычного приложения в современном окружении используйте нативный BigInt. В устаревшей среде синтаксиса недостаточно, потому что операторам нужна поддержка самого типа.

Библиотека JSBI остается вариантом для устаревших окружений. Она заменяет операции BigInt вызовами функций, а Babel-плагин помогает преобразовать код под такой сценарий.

Проверка typeof BigInt === 'function' обнаруживает функцию BigInt. Литерал 10n в неподдерживаемой среде вызовет синтаксическую ошибку еще при разборе файла.

Когда выбирать Number, BigInt или строковый ID

Берите Number для дробей и целых в безопасном диапазоне. Такой тип быстрее подходит для малых чисел, поэтому переносить в BigInt обычные счетчики не нужно.

Берите BigInt для точных вычислений с большими целыми. Строка подходит для ID, который приложение только хранит, сравнивает или передает дальше.

Передавайте большие ID через JSON строковыми полями. На сервере сохраняйте строковый формат до границы с базой. Преобразуйте строку в BigInt только там, где нужны вычисления.

Добавьте сквозной тест с ID 9007199254740993. Такой тест обнаружит округление в API, драйвере базы или клиентском коде.

Комментарии

Оставьте свой комментарий
Пока никто не оставил комментариев