## Why is this an issue?

Numbers in JavaScript are stored in double-precision 64-bit binary
format IEEE 754. Like any other number encoding occupying a finite number of bits, it is unable to represent all numbers.

The values are stored using 64 bits in the following form:

- 1 bit for the sign (positive or negative)
- 11 bits for the exponent (2
^{n}). -1022 ≤ n ≤ 1023
- 52 bits for the significand (or mantissa)

The actual value of the stored number will be `(-1)`^{sign} * (1 + significand) * 2 ^{exponent}

Given this structure, there are limits in both **magnitude** and **precision**.

Due to the 52 bits used for the significand, any arithmetic in need of more precision than 2^{-52} (provided by
`Number.EPSILON`

) is subject to rounding.

In terms of magnitude, the largest number the 64 bits of the format can store is 2^{1024} - 1 (`Number.MAX_VALUE`

).

However, because the 52 bits of the significand, only integers between -(2^{53} - 1) (`Number.MIN_SAFE_INTEGER`

) and
2^{53} - 1 (`Number.MAX_SAFE_INTEGER`

) can be represented exactly and be properly compared.

Number.MAX_SAFE_INTEGER + 1 === Number.MAX_SAFE_INTEGER + 2; // true

JavaScript provides the `bigint`

primitive to represent values which are too large to be represented by the number primitive. BigInts
are created by appending `n`

to the end of an integer literal, or by calling the `BigInt()`

function (without the new operator),
with an integer or a string.

const myBigInt = BigInt(Number.MAX_SAFE_INTEGER);
myBigInt + 1n === myBigInt + 2n; // false

## How to fix it

For large numbers, JavaScript provides the helper function `Number.isSafeInteger()`

to test if a number is between the safe limits.

When you need to store a large number, use `BigInt`

. `bigint`

and `number`

primitives can be compared between them
as usual (e.g. `>`

, `==`

), but pay attention that arithmetic operations (`+`

`*`

`-`

`%`

`**`

) between both types raise an error unless they are converted to the same type. Use the `BigInt`

and
`Number`

functions to convert between both types:

const myNumber = Number(myBigInt);
const myBigInt = BigInt(myNumber);

Be careful converting values back and forth, however, as the precision of a `bigint`

value may be lost when it is coerced to a
`number`

value.

### Code examples

#### Noncompliant code example

const foo = 2312123211345545367 // Noncompliant: will be stored as 2312123211345545000
const bar = BigInt(2312123211345545367); // Noncompliant: parameter is first parsed as an integer and thus rounded

#### Compliant solution

const foo = BigInt('2312123211345545367');
const bar = 2312123211345545367n;

When in need of more decimal precision, it is recommended to use a dedicated library to ensure that calculation errors are not introduced by
rounding.

#### Noncompliant code example

const baz = 0.123456789123456789 // Noncompliant: will be stored as 0.12345678912345678

#### Compliant solution

// use a library like decimal.js for storing numbers containing many decimal digits
import { Decimal } from 'decimal.js';
const bar = new Decimal('0.123456789123456789');

## Resources

### Documentation