https://github.com/tc39/proposal-bigint-math

Draft specification for supporting BigInts in JavaScript’s Math methods.
https://github.com/tc39/proposal-bigint-math

bigint math proposal tc39

Last synced: 11 months ago
JSON representation

Draft specification for supporting BigInts in JavaScript’s Math methods.

• Host: GitHub
• URL: https://github.com/tc39/proposal-bigint-math
• Owner: tc39
• License: bsd-3-clause
• Created: 2021-08-13T13:51:59.000Z (almost 5 years ago)
• Default Branch: main
• Last Pushed: 2025-04-09T00:43:50.000Z (about 1 year ago)
• Last Synced: 2025-04-09T01:31:22.698Z (about 1 year ago)
• Topics: bigint, math, proposal, tc39
• Language: HTML
• Homepage: https://tc39.es/proposal-bigint-math/
• Size: 1.46 MB
• Stars: 37
• Watchers: 18
• Forks: 2
• Open Issues: 8
• Metadata Files:
  • Readme: README.md
  • Changelog: HISTORY.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE.md
  • Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

README

          
# BigInt `Math` for JavaScript

ECMAScript Stage 1 Proposal\

J. S. Choi, 2021–2025

* **[Specification][]**

* **Babel plugin**: Not yet

[specification]: https://tc39.es/proposal-bigint-math/

## Description

(A [formal draft specification][specification] is available.)

BigInts are important for a myriad of

mathematical, financial, scientific, and timing applications

(such as in the [Node.js `process.hrtime.bigint` API][hrtime]),

and they have been therefore a valuable addition to JavaScript

since their standardization in ES 2021.

[hrtime]: https://nodejs.org/api/process.html#process_process_hrtime_bigint

Several built-in `Math` functions

would make sense with BigInts,

yet JavaScript still does not have not support them.

They only support regular floating-point JavaScript Numbers.

* This proposal adds the following functions

  to the BigInt object acting as a namespace:

  * `BigInt.abs`

  * `BigInt.sign`

  * `BigInt.sqrt`*

  * `BigInt.cbrt`*

  * `BigInt.pow`

  * `BigInt.min`†

  * `BigInt.max`†

* All of these functions return BigInts.

* None of these functions accept any arguments other than BigInts.

* * `sqrt` and `cbrt` truncate the result toward 0 into a BigInt.

* † `min` and `max` require at least one argument.

## Philosophy

This proposal balances performance with precedent.

1. Monomorphic functions are much easier for engines to optimize

   than polymorphic functions.

2. BigInts and Numbers are not semantically interchangeable.

   Developers should be aware when using BigInt versus Numbers to avoid errors.

3. It is ergonomically desirable for BigInt math functions’ API

   to be as consistent with existing number functions in Math as possible.

4. Numbers and BigInts are primitives,

   so math functions should be static functions like `BigInt.abs(v)`,

   rather than prototype methods like `v.abs()`.

   * This matches the precedent of `BigInt.asIntN` and `BigInt.asUintN`.

   * This is unlike the proposed [Decimal128s][].

     Decimal128s will be objects and thus should use prototype methods.)

[Decimal128s]: https://github.com/tc39/proposal-decimal

## Vision

This initial proposal adds only a few first `BigInt` methods.

The vision is that this proposal would open up the way

to new proposals for new BigInt math functions, like:

* `BigInt.gcd(v)`: Greatest common divisor (GCD)

* `BigInt.popCount(v)`: Population count

* `BigInt.bitLength(v)`: Bit length, i.e., truncating log2

* `BigInt.modPow(v, exponent, modulus)`: Modular exponentiation

* `BigInt.modInverse(v, modulus)`: Modular multiplicative inverse

* `BigInt.fromString(value, radix)`: Base-n string parsing

* `BigInt.toByteArray(v, endian)`: Conversion to byte array

* `BigInt.fromByteArray(bytes, endian)`: Conversion from byte array

Some of these may also be appropriate for ordinary integer Numbers.

## Excluded `Math`

`Math` functions that would not make sense with BigInts

are excluded from this proposal. These include:

|`Math` method  | Exclusion reason

| ------------- | ----------------

|`acos`         | Transcendental: very difficult to calculate when large

|`acosh`        | Transcendental

|`asin`         | Transcendental

|`asinh`        | Transcendental

|`atan`         | Transcendental

|`atan2`        | Transcendental

|`atanh`        | Transcendental

|`ceil`         | No known use case; `Math.ceil(3n / 2n) == 1` may be surprising

|`clz32`        | No known use case

|`cos`          | Transcendental

|`cosh`         | Transcendental

|`exp`          | Transcendental

|`expm1`        | Transcendental

|`floor`        | No known use case

|`fround`       | Returns floating-point numbers by definition

|`hypot`        | No known use case

|`imul`         | No known use case

|`log`          | Transcendental

|`log10`        | Truncation may be surprising; no known use case

|`log2`         | Truncation may be surprising; deferred to future `bitLength` proposal

|`log1p`        | Transcendental

|`random`       | No conceptual integer-only analogue

|`round`        | No known use case; `Math.round(3n / 2n) == 1` may be surprising

|`sin`          | Transcendental

|`sinh`         | No known use case

|`tan`          | Transcendental

|`tanh`         | Transcendental

|`trunc`        | No known use case

[issue #3]: https://github.com/js-choi/proposal-bigint-math/issues/3#issuecomment-912133467

[issue #6]: https://github.com/js-choi/proposal-bigint-math/issues/6

[issue #8]: https://github.com/js-choi/proposal-bigint-math/issues/8

[issue #9]: https://github.com/js-choi/proposal-bigint-math/issues/9