> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt
> Use this file to discover all available pages before exploring further.
# JavaScript BigInt
`BigInt` is a built-in numeric primitive in JavaScript that provides a way to represent and manipulate whole numbers larger than 253 - 1. This value represents the `Number.MAX_SAFE_INTEGER` limit dictated by the IEEE 754 double-precision floating-point format, which the standard `Number` type uses. `BigInt` enables arbitrary-precision integer arithmetic, preventing the silent precision loss that occurs when standard numbers exceed the safe integer threshold.
## Instantiation and Syntax
A `BigInt` is created either by appending the suffix `n` to an integer literal or by invoking the `BigInt()` function. Unlike `Number`, `String`, or `Boolean`, invoking `BigInt` with the `new` keyword throws a `TypeError`. The ECMAScript specification explicitly forbids constructor usage for `BigInt` (similar to `Symbol`) to avoid the historical pitfalls and confusion associated with primitive object wrappers.
```javascript theme={"dark"}
// Literal syntax
const maxSafe = 9007199254740991n;
const beyondSafe = 9007199254740992n;
// Function syntax
const fromNumber = BigInt(15);
const fromString = BigInt("90071992547409923456789");
const fromHex = BigInt("0x1fffffffffffff");
// TypeError: BigInt is not a constructor
const invalidObject = new BigInt(10);
```
## Type Identification
The `typeof` operator returns a distinct string for `BigInt` values, separating them from standard floating-point numbers.
```javascript theme={"dark"}
typeof 10; // "number"
typeof 10n; // "bigint"
```
## Arithmetic Operations
`BigInt` supports standard arithmetic operators (`+`, `-`, `*`, `/`, `%`, `**`). However, because `BigInt` strictly represents integers, division operations do not return fractional values. Instead, the result is truncated towards zero.
A critical exception in `BigInt` arithmetic is the **unary plus** operator (`+`). While commonly used to coerce values to numbers, unary plus is explicitly *not* supported for `BigInt` and will throw a `TypeError`.
```javascript theme={"dark"}
const a = 10n;
const b = 3n;
const sum = a + b; // 13n
const product = a * b; // 30n
const quotient = a / b; // 3n (fractional part is discarded)
const remainder = a % b; // 1n
const power = a ** b; // 1000n
// TypeError: Cannot convert a BigInt value to a number
const invalidUnary = +a;
```
## Type Mixing and Coercion
JavaScript prohibits implicit coercion between `BigInt` and `Number` during arithmetic operations to prevent accidental precision loss. Attempting to mix the two types throws a `TypeError`. Explicit casting is required.
```javascript theme={"dark"}
const bigValue = 100n;
const numValue = 25;
// TypeError: Cannot mix BigInt and other types, use explicit conversions
const invalidMath = bigValue + numValue;
// Valid: Explicitly cast Number to BigInt
const safeBigIntMath = bigValue + BigInt(numValue); // 125n
// Valid: Explicitly cast BigInt to Number (Risk of precision loss if > 2^53 - 1)
const safeNumberMath = Number(bigValue) + numValue; // 125
```
## Comparisons
Relational operators (`<`, `>`, `>=`, `<=`) allow mixed-type comparisons without explicit coercion. Equality operators behave according to standard JavaScript strictness rules: strict equality (`===`) checks both value and type, while loose equality (`==`) coerces the values before comparing.
```javascript theme={"dark"}
10n === 10; // false (different types: bigint vs number)
10n == 10; // true (loose equality allows implicit coercion)
10n > 5; // true
10n < 15.5; // true
```
## Technical Limitations
1. **Math Object Incompatibility:** `BigInt` values cannot be passed to methods of the built-in `Math` object (e.g., `Math.max()`, `Math.pow()`). Doing so throws a `TypeError`.
2. **Serialization:** The standard `JSON.stringify()` method does not know how to serialize `BigInt` values by default and will throw a `TypeError`. To serialize a `BigInt`, you must implement a custom `replacer` function or patch the `BigInt.prototype.toJSON` method to return a string representation.
3. **Bitwise Operations:** Bitwise operators (`|`, `&`, `<<`, `>>`, `^`, `~`) are fully supported, but zero-fill right shift (`>>>`) is not, as `BigInt` does not have a fixed width and always maintains its sign bit.
Tired of Poor JavaScript Skills? Fix That With Deep Grasping!
Learn More
