← Back to glossary

BigInt — Arbitrary Precision Integers

javascript ES2020 Intermediate

Also Known As

BigInt big integer JS arbitrary precision JavaScript

TL;DR

JavaScript's Number type cannot safely represent integers larger than 2⁵³−1 (Number.MAX_SAFE_INTEGER). BigInt is a separate numeric type that handles integers of arbitrary size, essential for working with 64-bit IDs from databases, cryptographic values, and precise financial calculations.

Explanation

JavaScript uses IEEE 754 double-precision floating point for all numbers — integers above 2⁵³ lose precision. The number 9007199254740993 and 9007199254740994 are represented identically. BigInt literals use an 'n' suffix: 9007199254740993n. BigInt supports all arithmetic operators (+, -, *, **, /, %) and comparison operators but cannot be mixed with regular Number in arithmetic — you must explicitly convert. BigInt cannot be serialized to JSON natively (JSON.stringify throws a TypeError). It is not available in very old browsers but has broad support since 2020. PHP's int type is 64-bit on 64-bit systems, so PHP can natively handle numbers that JavaScript's Number cannot.

Common Misconception

✗ Using BigInt everywhere instead of Number is safer. BigInt has no fractional part — it is integers only. It cannot represent 1.5. For most numeric work, Number is correct; BigInt is only needed for integers that exceed 2⁵³.

Why It Matters

PHP APIs often return 64-bit integer IDs (database auto-increments, snowflake IDs, Unix timestamps in microseconds). When these arrive in JavaScript via JSON, Number silently corrupts them if they exceed MAX_SAFE_INTEGER. A user ID of 9007199254740994 becomes 9007199254740992 — two different users now appear identical. BigInt prevents this.

Common Mistakes

JSON.parse() silently corrupting large integers — JSON has no BigInt type; numbers parse as IEEE 754 doubles. Use string IDs or a custom JSON parser.
JSON.stringify() throwing on BigInt — add a replacer: JSON.stringify(data, (k, v) => typeof v === 'bigint' ? v.toString() : v).
Mixing BigInt with Math functions — Math.max(), Math.sqrt() etc. do not accept BigInt; convert to Number first (with possible precision loss).
Not checking browser support — BigInt requires Chrome 67+, Firefox 68+, Safari 14+; polyfilling is complex and usually not worth it.

Code Examples

✗ Vulnerable

// ❌ Large integer loses precision in JSON
// PHP sends: {"id": 9007199254740993}
// JS receives:
const data = JSON.parse('{"id": 9007199254740993}');
console.log(data.id);           // 9007199254740992 — wrong!
console.log(data.id === 9007199254740993); // false

// ❌ Mixing BigInt and Number
const a = 100n;
const b = 50;
const c = a + b; // TypeError: Cannot mix BigInt and other types

✓ Fixed

// ✅ Server sends ID as string, client parses as BigInt
// PHP: json_encode(['id' => (string) $largeId])
const data = JSON.parse('{"id": "9007199254740993"}');
const id = BigInt(data.id);     // 9007199254740993n — correct

// BigInt arithmetic
const a = 9007199254740993n;
const b = 100n;
console.log(a + b);             // 9007199254741093n

// Convert back to string for API calls
fetch(`/api/users/${id.toString()}`);

// Comparison works across types with ==
console.log(10n == 10);  // true
console.log(10n === 10); // false (different types)

References

↗ https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt