jskatas.org Continuously Learn JavaScript. Your Way.

BigInt: Basics

A BigInt can represent numbers larger than number

Donate to NGO Julenka. Support Ukranians in need. Julenka is an NGO which my brother founded in 2011 to support Ukranian families and kids in need.

A BigInt is a large number

  • a number: Number.MAX_VALUE * Number.MAX_VALUE, is useless, it results in Infinity
  • a bigint: BigInt(Number.MAX_VALUE) * BigInt(Number.MAX_VALUE) results in an amazingly large AND usable number
  • the result of BigInt(Number.MAX_VALUE) * BigInt(Number.MAX_VALUE) has 617 digits

creating one can be done in multiple ways

  • adding an n at the end of a number
  • calling the function BigInt(x), where x is a number
  • calling the function BigInt(x) with a string
  • calling the function BigInt(x) with a binary number

difference to a number

  • a BigInt is of type "bigint"
  • comparing via == can coerce a bigint to a number
  • but type safe comparisons fail
  • a bigint can NOT be used with Math.* functions
  • can not be calculated with a number

BigInt supports various operators

  • the + and - work just like for numbers
  • also * and / work
  • the modulo operator % works as known
  • the exponentiation operator ** works like on numbers
  • but ++ even throws a SyntaxError

the comparison operators work, even with numbers

  • comparing 2n >= 2 works as if they were of the same type
  • the number can also be the left operand 1 < 2n, works as if they were the same type

explicit type conversion

  • via String(0n) renders the number without a trailing n
  • for Boolean(0b01n) everything but a 0 zero is true

the API

  • BigInt is NOT a constructor, it throws
  • BigInt.asIntN() returns a bigint that can fit in the given number of bits
  • BigInt.asUintN() uses the given bits to interpret an unsigned value, returning a bigint
  • 1n.toString() just cuts off the n and returns the number
  • valueOf() returns the value as is
  • overriding toJSON() on the prototype allows to "encode" a bigint for a JSON string


The proposal repo.
The "ECMAScript Language Specification", the JavaScript specification text describing this function.
The Mozilla Developer Network docs, contains good examples.
Announcement of this kata on twitter.