BigInt: Basics

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

Links

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