Stage 1 Draft / May 29, 2025

ES BigInt Math (2025)

Introduction

This is the formal specification for a proposed extension of the BigInt JavaScript global object with further operations. It modifies the original ECMAScript specification with several new or revised clauses. See the proposal's explainer for the proposal's background, motivation, and usage examples.

1 Properties of the BigInt Constructor

The BigInt constructor:

1.1 BigInt.abs ( x )

This function returns the absolute value of x as a BigInt; the result has the same magnitude as x but has positive sign.

It performs the following steps when called:

  1. If x is not a BigInt, throw a TypeError exception.
  2. Return the BigInt value that represents abs(ℝ(x)).

1.2 BigInt.cbrt ( x )

This function returns the cube root of x as a BigInt.

It performs the following steps when called:

  1. If x is not a BigInt, throw a TypeError exception.
  2. Let root be the cube root of ℝ(x).
  3. Return ℤ(truncate(root)).

1.3 BigInt.max ( firstArg, ...restArgs )

Given one or more BigInt arguments, this function returns the largest of the resulting values.

It performs the following steps when called:

  1. If x is not a BigInt, throw a TypeError exception.
  2. Let highest be firstCoerced.
  3. For each element number of restCoerced, do
    1. If number is not a BigInt, throw a TypeError exception.
    2. If number > highest, set highest to number.
  4. Return highest.

The "length" property of this function is 2𝔽.

1.4 BigInt.min ( firstArg, ...restArgs )

Given one or more arguments, this function calls ToBigInt on each of the arguments and returns the smallest of the resulting values.

It performs the following steps when called:

  1. If x is not a BigInt, throw a TypeError exception.
  2. Let lowest be firstCoerced.
  3. For each element number of restCoerced, do
    1. If number is not a BigInt, throw a TypeError exception.
    2. If number < lowest, set lowest to number.
  4. Return lowest.

The "length" property of this function is 2𝔽.

1.5 BigInt.pow ( base, exponent )

This function performs the following steps when called:

  1. If base is not a BigInt, throw a TypeError exception.
  2. If exponent is not a BigInt, throw a TypeError exception.
  3. Return BigInt::exponentiate(base, exponent).

1.6 BigInt.prototype

The initial value of BigInt.prototype is the BigInt prototype object.

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.

1.7 BigInt.sign ( x )

This function returns the sign of x as a BigInt, indicating whether x is positive, negative, or zero.

It performs the following steps when called:

  1. If x is not a BigInt, throw a TypeError exception.
  2. If x is 0ℤ, return x.
  3. If x < 0ℤ, return -1ℤ.
  4. Return 1ℤ.

1.8 BigInt.sqrt ( x )

This function returns the square root of x as a BigInt.

It performs the following steps when called:

  1. If x is not a BigInt, throw a TypeError exception.
  2. If x < 0ℤ, throw a RangeError exception.
  3. Let root be the square root of ℝ(x).
  4. Return ℤ(truncate(root)).