Stage 1 Draft / April 14, 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. Let n be ? ToBigInt(x).
  2. Return the BigInt value that represents abs(ℝ(x)).

1.2 BigInt.asIntN ( bits, bigint )

This function performs the following steps when called:

  1. Set bits to ? ToIndex(bits).
  2. Set bigint to ? ToBigInt(bigint).
  3. Let mod be ℝ(bigint) modulo 2bits.
  4. If mod ≥ 2bits - 1, return ℤ(mod - 2bits); otherwise, return ℤ(mod).

1.3 BigInt.asUintN ( bits, bigint )

This function performs the following steps when called:

  1. Set bits to ? ToIndex(bits).
  2. Set bigint to ? ToBigInt(bigint).
  3. Return ℤ(ℝ(bigint) modulo 2bits).

1.4 BigInt.cbrt ( x )

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

It performs the following steps when called:

  1. Let n be ? ToBigInt(x).
  2. Let root be the cube root of ℝ(n).
  3. Return ℤ(truncate(root)).

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

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

It performs the following steps when called:

  1. Let firstCoerced be ? ToBigInt(firstArg).
  2. Let restCoerced be a new empty List.
  3. For each element arg of restArgs, do
    1. Let n be ? ToBigInt(arg).
    2. Append n to restCoerced.
  4. Let highest be firstCoerced.
  5. For each element number of restCoerced, do
    1. If number > highest, set highest to number.
  6. Return highest.

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

1.6 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. Let firstCoerced be ? ToBigInt(firstArg).
  2. Let restCoerced be a new empty List.
  3. For each element arg of restArgs, do
    1. Let n be ? ToBigInt(arg).
    2. Append n to restCoerced.
  4. Let lowest be firstCoerced.
  5. For each element number of restCoerced, do
    1. If number < lowest, set lowest to number.
  6. Return lowest.

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

1.7 BigInt.pow ( base, exponent )

This function performs the following steps when called:

  1. Set base to ? ToBigInt(base).
  2. Set exponent to ? ToBigInt(exponent).
  3. Return Number::exponentiate(base, exponent).

1.8 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.9 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. Let n be ? ToBigInt(x).
  2. If n is 0ℤ, return n.
  3. If n < 0ℤ, return -1ℤ.
  4. Return 1ℤ.

1.10 BigInt.sqrt ( x )

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

It performs the following steps when called:

  1. Let n be ? ToBigInt(x).
  2. If n < 0ℤ, throw a RangeError exception.
  3. Let root be the square root of ℝ(n).
  4. Return ℤ(truncate(root)).