BigInt в JavaScript – руководство с примерами
BigInt хранит целые числа за пределами безопасного диапазона Number без потери точности. Используйте его для больших ID и точных вычислений, но передавайте такие идентификаторы через JSON строками. Так значение пройдет путь от API до базы данных и обратно без округления и TypeError.
- Почему Number теряет точность на больших целых
- Как создавать BigInt и выполнять вычисления
- Смешивание Number и BigInt
- Конструктор BigInt
- Как передавать большие идентификаторы через JSON
- Запись и чтение ID в MySQL через mysql2
- Библиотечные функции BigInt
- Чем Number отличается от BigInt
- Поддержка браузерами и транспилинг
- Когда выбирать Number, BigInt или строковый ID
Почему 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'); // → trueBigInt поддерживает сложение, вычитание, умножение, степень, остаток, инкремент и декремент.
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.
- Откройте терминал в пустой папке и выполните
npm install mysql2. После установки появится каталогnode_modules. - Создайте файл
bigint-id.cjsи заполните параметры подключения к запущенному MySQL. - Запустите
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
Выбирайте тип по требуемой точности и характеру вычислений. Таблица показывает ограничения, которые чаще всего влияют на выбор.
| Операция | Number | BigInt |
|---|---|---|
| Арифметика | Поддерживает целые и дробные числа | Поддерживает только целые; оба операнда должны быть 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, драйвере базы или клиентском коде.
Популярное за неделю
- Как создать сайт самому в 2026: 4 способа + пошаговая инструкция 34 мин чтения
- Лучшие конструкторы для создания сайтов — плюсы, минусы и сравнения 22 мин чтения
- Как создать скрипт сокращения ссылок на PHP 3 мин чтения
- js переход на другую страницу: методы, примеры и сравнение 5 мин чтения
- Фотогалерея для сайта: способы реализации и рабочий код 11 мин чтения
- 15 плагинов календарей и событий для сайта 9 мин чтения
Комментарии