bigint

bigint is a primitive data type in TypeScript used to represent arbitrarily large integers beyond the safe integer limit of the standard number type (Number.MAX_SAFE_INTEGER, or $2^{53} - 1$).

You can initialize a bigint by appending an n suffix to an integer literal or by calling the global BigInt() function.

const literalBigInt: bigint = 9007199254740992n;
const constructedBigInt: bigint = BigInt("9007199254740992");
const hexBigInt: bigint = 0x1fffffffffffffn;

Type Interoperability and Strictness

TypeScript enforces strict separation between bigint and number. There is no implicit type coercion between the two primitives. Attempting to mix them in arithmetic operations will result in a compile-time type error, requiring explicit casting to perform operations across the two types.

While bigint and number can be safely mixed in relational comparisons (<, >, <=, >=) and loose equality comparisons (==, !=), strict equality comparisons (===, !==) are forbidden. Because bigint and number are disjoint types with no overlap, TypeScript explicitly rejects strict equality checks between them and will throw a compile-time error (TS2367).

const bigVal: bigint = 100n;
const numVal: number = 50;

// TS2365: Operator '+' cannot be applied to types 'bigint' and 'number'.
// const invalidSum = bigVal + numVal; 

const validBigIntSum: bigint = bigVal + BigInt(numVal);
const validNumberSum: number = Number(bigVal) + numVal;

// Relational and loose equality comparisons are valid
const isGreater: boolean = bigVal > numVal; // true
const isLooselyEqual: boolean = bigVal == 100; // true

// TS2367: This condition will always return 'false' since the types 'bigint' and 'number' have no overlap.
// const isStrictlyEqual: boolean = bigVal === 100;

Mathematical and Bitwise Operations

bigint supports standard arithmetic operators (+, -, *, /, %, **) and bitwise operators (&, |, ^, ~, <<, >>). Notably, the unsigned right shift operator (>>>) is explicitly unsupported for bigint types, as bigint does not have a fixed bit-width to shift into.

Because bigint strictly represents whole numbers, division operations inherently truncate fractional components towards zero. Furthermore, bigint primitives are incompatible with the built-in Math object methods, which strictly expect number arguments.

// Division truncates towards zero
const division: bigint = 5n / 2n; // Evaluates to 2n

// Bitwise operations are supported, except >>>
const bitwiseAnd: bigint = 0b101n & 0b011n; // Evaluates to 1n

// TS2736: Operator '>>>' cannot be applied to type 'bigint'.
// const invalidShift = 10n >>> 1n; 

// TS2345: Argument of type 'bigint' is not assignable to parameter of type 'number'.
// const absolute = Math.abs(-10n); 

Compiler Configuration

Because bigint is a relatively recent ECMAScript feature, the TypeScript compiler requires a specific target to emit valid code. Your tsconfig.json must have the target set to ES2020 or later. If targeting an older ECMAScript version, TypeScript will throw a compilation error, as bigint cannot be polyfilled or down-compiled to standard JavaScript numbers without losing precision.

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020"]
  }
}

Master TypeScript with Deep Grasping Methodology!

Learn More