├── .gitignore ├── .editorconfig ├── .github ├── workflows │ ├── lock.yml │ └── publish.yml └── pull_request_template.md ├── package.json ├── CODE_OF_CONDUCT.md ├── LICENSE.md ├── HISTORY.md ├── CONTRIBUTING.md ├── README.md └── spec.html /.gitignore: -------------------------------------------------------------------------------- 1 | .DS_Store 2 | node_modules 3 | dist 4 | npm-debug.log 5 | deploy_key 6 | -------------------------------------------------------------------------------- /.editorconfig: -------------------------------------------------------------------------------- 1 | root = true 2 | 3 | [*] 4 | end_of_line = lf 5 | insert_final_newline = true 6 | trim_trailing_whitespace = true 7 | charset = utf-8 8 | indent_style = space 9 | indent_size = 2 10 | -------------------------------------------------------------------------------- /.github/workflows/lock.yml: -------------------------------------------------------------------------------- 1 | name: 'Lock Threads' 2 | 3 | on: 4 | schedule: 5 | - cron: '0 0 * * *' 6 | 7 | workflow_dispatch: 8 | 9 | permissions: 10 | issues: write 11 | pull-requests: write 12 | 13 | concurrency: 14 | group: lock 15 | 16 | jobs: 17 | action: 18 | runs-on: ubuntu-latest 19 | steps: 20 | - uses: dessant/lock-threads@v2 21 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "private": true, 3 | "name": "proposal-bigint-math", 4 | "description": "Draft specification for BigInt Math in JavaScript.", 5 | "homepage": "https://tc39.github.io/proposal-bigint-math/", 6 | "author": "J. S. Choi (https://jschoi.org/)", 7 | "license": "MIT", 8 | "repository": "github:tc39/proposal-bigint-math", 9 | "scripts": { 10 | "prebuild": "mkdir -p dist", 11 | "build": "ecmarkup --load-biblio @tc39/ecma262-biblio --verbose spec.html dist/index.html --assets-dir dist/", 12 | "watch": "npm run build -- --watch" 13 | }, 14 | "devDependencies": { 15 | "@tc39/ecma262-biblio": "2.1.2462", 16 | "ecmarkup": "^18.1.0" 17 | } 18 | } 19 | -------------------------------------------------------------------------------- /.github/workflows/publish.yml: -------------------------------------------------------------------------------- 1 | name: Build and Deploy to GitHub Pages 2 | on: 3 | push: 4 | branches: 5 | - main 6 | workflow_dispatch: 7 | jobs: 8 | build-and-deploy: 9 | runs-on: ubuntu-latest 10 | steps: 11 | - name: Checkout 🛎️ 12 | uses: actions/checkout@v2 13 | with: 14 | persist-credentials: false 15 | 16 | - name: Setup Node 17 | uses: actions/setup-node@v1 18 | with: 19 | node-version: '14.x' 20 | 21 | - name: Install and Build 🔧 22 | run: | 23 | npm install 24 | npm run build 25 | 26 | - name: Deploy 🚀 27 | uses: peaceiris/actions-gh-pages@v3 28 | with: 29 | github_token: ${{ secrets.GITHUB_TOKEN }} 30 | publish_dir: ./dist 31 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Code of conduct 2 | This repository is a TC39 project, and it therefore subscribes to its [code of 3 | conduct][CoC]. It is available at . 4 | 5 | We all should strive here to be respectful, friendly and patient, inclusive, 6 | considerate, and careful in the words we choose. When we disagree, we should try 7 | to understand why. 8 | 9 | To ask a question or report an issue, please follow the [CoC]’s directions, 10 | e.g., emailing [tc39-conduct-reports@googlegroups.com][]. 11 | 12 | More information about contributing is also available in [CONTRIBUTING.md][]. 13 | 14 | [CoC]: https://tc39.es/code-of-conduct/ 15 | [tc39-conduct-reports@googlegroups.com]: mailto:tc39-conduct-reports@googlegroups.com 16 | [CONTRIBUTING.md]: https://github.com/tc39/proposal-pipeline-operator/blob/main/CONTRIBUTING.md 17 | -------------------------------------------------------------------------------- /.github/pull_request_template.md: -------------------------------------------------------------------------------- 1 | Thank you for taking the time to contribute to this proposal! 2 | We’re so happy you’re helping out. 3 | 4 | 1. Please take a look at the [contributing guidelines][] 5 | and the resources to which it links. 6 | 2. Please include the purpose of the pull request. For example: 7 | * “This adds…” 8 | * “This simplifies…” 9 | * “This fixes…” 10 | 3. Please be explicit about what feedback, if any, you want: 11 | a quick pair of eyes, discussion or critique of its approach, 12 | a review of its copywriting, and so on. 13 | 4. Please mark the pull request as a Draft if it is still unfinished. 14 | 15 | All text in this repository is under the 16 | [same BSD license as Ecma-262][LICENSE.md]. 17 | As is the norm in open source, by contributing to this GitHub repository, 18 | you are licensing your contribution under the same license, 19 | as per the 20 | [GitHub terms of service][ToS]. 21 | 22 | [contributing guidelines]: https://github.com/tc39/proposal-pipeline-operator/blob/main/CONTRIBUTING.md 23 | [LICENSE.md]: https://github.com/tc39/proposal-pipeline-operator/blob/main/LICENSE.md 24 | [ToS]: https://help.github.com/en/github/site-policy/github-terms-of-service 25 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | Copyright 2021 J. S. Choi 2 | 3 | Redistribution and use in source and binary forms, with or without 4 | modification, are permitted provided that the following conditions 5 | are met: 6 | 7 | 1. Redistributions of source code must retain the above copyright 8 | notice, this list of conditions and the following disclaimer. 9 | 10 | 2. Redistributions in binary form must reproduce the above copyright 11 | notice, this list of conditions and the following disclaimer in the 12 | documentation and/or other materials provided with the distribution. 13 | 14 | 3. Neither the name of the copyright holder nor the names of its 15 | contributors may be used to endorse or promote products derived from 16 | this software without specific prior written permission. 17 | 18 | **This software is provided by the copyright holders and contributors 19 | “as is” and any express or implied warranties, including, but not 20 | limited to, the implied warranties of merchantability and fitness for a 21 | particular purpose are disclaimed. In no event shall the copyright 22 | holder or contributors be liable for any direct, indirect, incidental, 23 | special, exemplary, or consequential damages (including, but not limited 24 | to, procurement of substitute goods or services; loss of use, data, or 25 | profits; or business interruption) however caused and on any theory of 26 | liability, whether in contract, strict liability, or tort (including 27 | negligence or otherwise) arising in any way out of the use of this 28 | software, even if advised of the possibility of such damage.** 29 | -------------------------------------------------------------------------------- /HISTORY.md: -------------------------------------------------------------------------------- 1 | # History of BigInt Math 2 | 3 | ## 2021-09 4 | Presented to [plenary meeting for Stage 1 on 2021-09-01][2021-09-01]. Was accepted. 5 | 6 | 7 | [2021-09-01]: https://github.com/tc39/notes/blob/HEAD/meetings/2021-08/sept-01.md#bigint-math-for-stage-1 8 | 9 | ## 2021-10 10 | Presented to [plenary meeting as an update on 2021-10-26][2021-10-26]. 11 | 12 | [2021-10-26]: https://github.com/tc39/notes/blob/HEAD/meetings/2021-10/oct-26.md#bigint-math-update 13 | 14 | ## 2022-05 15 | Presented to [incubator meeting on 2022-05-06][2022-05-06] with [follow-up 16 | discussion on Matrix][2022-05-06 Matrix]. 17 | 18 | [2022-05-06]: https://github.com/tc39/incubator-agendas/blob/main/notes/2022/05-06.md 19 | [2022-05-06 Matrix]: https://matrixlogs.bakkot.com/TC39_Delegates/2022-05-06 20 | 21 | ## 2023-11 22 | The [operator-overloading proposal was withdrawn 23 | at the 2023-11 plenary][2023-11]. 24 | 25 | [2023-11]: //github.com/tc39/notes/blob/main/meetings/2023-11/november-28.md#withdrawing-operator-overloading 26 | 27 | * Discussion at the plenary makes clear 28 | that the polymorphism of the BigInt operators 29 | is now seen as an unforeseen burden and potential “mistake” 30 | imposing much complexity on the JavaScript engines with relatively little gain. 31 | * Even the original BigInt champion, Daniel Ehrenberg, 32 | added that he too thinks that BigInt math functions 33 | should be separate functions in `BigInt` and not functions in `Math`. 34 | 35 | ## 2025-04 36 | 37 | * Jesse Alama, champion of the Decimal proposal, 38 | [announces that they have decided to eschew type overloading 39 | for math functions on `Decimal`s][decimal #25]. 40 | * Following these precedents, the BigInt Math champion 41 | [changes BigInt Math to use separate functions in `BigInt` 42 | and not functions in `Math`][2025-04 #13]. 43 | 44 | [decimal #25]: https://github.com/tc39/proposal-decimal/issues/25 45 | [2025-04 #13]: https://github.com/tc39/proposal-bigint-math/issues/13#issuecomment-2774304480 46 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing to this proposal 2 | First off, thank you for taking the time to contribute! 🎉 3 | 4 | Here are some suggestions to contributing to this proposal. 5 | 6 | 1. The general [TC39 Process][], which summarizes 7 | how TC39’s “consensus” and “Stages” work. 8 | 2. The guide on [contributing to TC39 proposals][contributing guide]. 9 | 3. The [TC39 Code of Conduct][CoC]: 10 | It has important information about how we’re all expected to act 11 | and what to do when we feel like someone’s conduct does not meet the Code. 12 | We all want to maintain a friendly, productive working environment! 13 | 4. The [TC39 How to Give Feedback][feedback] article. 14 | 5. The [proposal explainer][] to make sure that it is 15 | not already addressed there. 16 | 6. The [TC39 Matrix guide][] (if you want to chat with TC39 members on Matrix, 17 | which is a real-time chat platform). 18 | 7. If the explainer does not already explain your topic adequately, 19 | then please [search the GitHub repository’s issues][issues] 20 | to see if any issues match the topic you had in mind. 21 | This proposal is more than four years old, 22 | and it is likely that the topic has already been raised and thoroughly discussed. 23 | 24 | You can leave a comment on an [existing GitHub issue][issues], 25 | create a new issue (but do try to [find an existing GitHub issue][issues] first), 26 | or [participate on Matrix][TC39 Matrix guide]. 27 | 28 | Please try to keep any existing GitHub issues on their original topic. 29 | 30 | If you feel that someone’s conduct is not meeting the [TC39 Code of Conduct][CoC], 31 | whether in this GitHub repository or in a [TC39 Matrix room][TC39 Matrix guide], 32 | then please follow the [Code of Conduct][CoC]’s directions for reporting the violation, 33 | including emailing [tc39-conduct-reports@googlegroups.com][]. 34 | 35 | Thank you again for taking the time to contribute! 36 | 37 | [CoC]: https://tc39.es/code-of-conduct/ 38 | [TC39 process]: https://tc39.es/process-document/ 39 | [contributing guide]: https://github.com/tc39/ecma262/blob/master/CONTRIBUTING.md#new-feature-proposals 40 | [feedback]: https://github.com/tc39/how-we-work/blob/master/feedback.md 41 | [proposal explainer]: https://github.com/tc39/proposal-array-from-async/blob/main/README.md 42 | [TC39 Matrix guide]: https://github.com/tc39/how-we-work/blob/master/matrix-guide.md 43 | [issues]: https://github.com/tc39/proposal-array-from-async/issues?q=is%3Aissue+ 44 | [tc39-conduct-reports@googlegroups.com]: mailto:tc39-conduct-reports@googlegroups.com 45 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # BigInt `Math` for JavaScript 2 | ECMAScript Stage 1 Proposal\ 3 | J. S. Choi, 2021–2025 4 | 5 | * **[Specification][]** 6 | * **Babel plugin**: Not yet 7 | 8 | [specification]: https://tc39.es/proposal-bigint-math/ 9 | 10 | ## Description 11 | (A [formal draft specification][specification] is available.) 12 | 13 | BigInts are important for a myriad of 14 | mathematical, financial, scientific, and timing applications 15 | (such as in the [Node.js `process.hrtime.bigint` API][hrtime]), 16 | and they have been therefore a valuable addition to JavaScript 17 | since their standardization in ES 2021. 18 | 19 | [hrtime]: https://nodejs.org/api/process.html#process_process_hrtime_bigint 20 | 21 | Several built-in `Math` functions 22 | would make sense with BigInts, 23 | yet JavaScript still does not have not support them. 24 | They only support regular floating-point JavaScript Numbers. 25 | 26 | * This proposal adds the following functions 27 | to the BigInt object acting as a namespace: 28 | * `BigInt.abs` 29 | * `BigInt.sign` 30 | * `BigInt.sqrt`* 31 | * `BigInt.cbrt`* 32 | * `BigInt.pow` 33 | * `BigInt.min`† 34 | * `BigInt.max`† 35 | * All of these functions return BigInts. 36 | * None of these functions accept any arguments other than BigInts. 37 | * * `sqrt` and `cbrt` truncate the result toward 0 into a BigInt. 38 | * † `min` and `max` require at least one argument. 39 | 40 | ## Philosophy 41 | This proposal balances performance with precedent. 42 | 43 | 1. Monomorphic functions are much easier for engines to optimize 44 | than polymorphic functions. 45 | 2. BigInts and Numbers are not semantically interchangeable. 46 | Developers should be aware when using BigInt versus Numbers to avoid errors. 47 | 3. It is ergonomically desirable for BigInt math functions’ API 48 | to be as consistent with existing number functions in Math as possible. 49 | 4. Numbers and BigInts are primitives, 50 | so math functions should be static functions like `BigInt.abs(v)`, 51 | rather than prototype methods like `v.abs()`. 52 | * This matches the precedent of `BigInt.asIntN` and `BigInt.asUintN`. 53 | * This is unlike the proposed [Decimal128s][]. 54 | Decimal128s will be objects and thus should use prototype methods.) 55 | 56 | [Decimal128s]: https://github.com/tc39/proposal-decimal 57 | 58 | ## Vision 59 | This initial proposal adds only a few first `BigInt` methods. 60 | The vision is that this proposal would open up the way 61 | to new proposals for new BigInt math functions, like: 62 | 63 | * `BigInt.gcd(v)`: Greatest common divisor (GCD) 64 | * `BigInt.popCount(v)`: Population count 65 | * `BigInt.bitLength(v)`: Bit length, i.e., truncating log2 66 | * `BigInt.modPow(v, exponent, modulus)`: Modular exponentiation 67 | * `BigInt.modInverse(v, modulus)`: Modular multiplicative inverse 68 | * `BigInt.fromString(value, radix)`: Base-n string parsing 69 | * `BigInt.toByteArray(v, endian)`: Conversion to byte array 70 | * `BigInt.fromByteArray(bytes, endian)`: Conversion from byte array 71 | 72 | Some of these may also be appropriate for ordinary integer Numbers. 73 | 74 | ## Excluded `Math` 75 | `Math` functions that would not make sense with BigInts 76 | are excluded from this proposal. These include: 77 | 78 | |`Math` method | Exclusion reason 79 | | ------------- | ---------------- 80 | |`acos` | Transcendental: very difficult to calculate when large 81 | |`acosh` | Transcendental 82 | |`asin` | Transcendental 83 | |`asinh` | Transcendental 84 | |`atan` | Transcendental 85 | |`atan2` | Transcendental 86 | |`atanh` | Transcendental 87 | |`ceil` | No known use case; `Math.ceil(3n / 2n) == 1` may be surprising 88 | |`clz32` | No known use case 89 | |`cos` | Transcendental 90 | |`cosh` | Transcendental 91 | |`exp` | Transcendental 92 | |`expm1` | Transcendental 93 | |`floor` | No known use case 94 | |`fround` | Returns floating-point numbers by definition 95 | |`hypot` | No known use case 96 | |`imul` | No known use case 97 | |`log` | Transcendental 98 | |`log10` | Truncation may be surprising; no known use case 99 | |`log2` | Truncation may be surprising; deferred to future `bitLength` proposal 100 | |`log1p` | Transcendental 101 | |`random` | No conceptual integer-only analogue 102 | |`round` | No known use case; `Math.round(3n / 2n) == 1` may be surprising 103 | |`sin` | Transcendental 104 | |`sinh` | No known use case 105 | |`tan` | Transcendental 106 | |`tanh` | Transcendental 107 | |`trunc` | No known use case 108 | 109 | [issue #3]: https://github.com/js-choi/proposal-bigint-math/issues/3#issuecomment-912133467 110 | [issue #6]: https://github.com/js-choi/proposal-bigint-math/issues/6 111 | [issue #8]: https://github.com/js-choi/proposal-bigint-math/issues/8 112 | [issue #9]: https://github.com/js-choi/proposal-bigint-math/issues/9 113 | -------------------------------------------------------------------------------- /spec.html: -------------------------------------------------------------------------------- 1 | 
  2 | title: ES BigInt Math (2025)
  3 | status: proposal
  4 | stage: 1
  5 | location: https://github.com/tc39/proposal-bigint-math
  6 | copyright: false
  7 | contributors: J. S. Choi
  8 |
9 | 10 | 11 |

Introduction

12 |

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

19 | 20 | 21 | 22 |

Properties of the BigInt Constructor

23 |

The BigInt constructor:

24 |
    25 |
  • has a [[Prototype]] internal slot whose value is %Function.prototype%.
    • 26 |
  • has the following properties:
    • 27 |
28 | 29 | 30 |

BigInt.abs ( _x_ )

31 |

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

32 |

It performs the following steps when called:

33 | 34 | 1. If _x_ is not a BigInt, throw a *TypeError* exception. 35 | 1. Return the BigInt value that represents abs(ℝ(_x_)). 36 | 37 | 38 | 39 | 40 |

BigInt.cbrt ( _x_ )

41 |

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

42 |

It performs the following steps when called:

43 | 44 | 1. If _x_ is not a BigInt, throw a *TypeError* exception. 45 | 1. Let _root_ be the cube root of ℝ(_x_). 46 | 1. Return ℤ(truncate(_root_)). 47 | 48 | 49 | 50 | 51 |

BigInt.max ( _firstArg_, ..._restArgs_ )

52 |

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

53 |

It performs the following steps when called:

54 | 55 | 1. If _x_ is not a BigInt, throw a *TypeError* exception. 56 | 1. Let _highest_ be _firstCoerced_. 57 | 1. For each element _number_ of _restCoerced_, do 58 | 1. If _number_ is not a BigInt, throw a *TypeError* exception. 59 | 1. If _number_ > _highest_, set _highest_ to _number_. 60 | 1. Return _highest_. 61 | 62 |

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

63 | 64 | 65 | 66 |

BigInt.min ( _firstArg_, ..._restArgs_ )

67 |

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

68 |

It performs the following steps when called:

69 | 70 | 1. If _x_ is not a BigInt, throw a *TypeError* exception. 71 | 1. Let _lowest_ be _firstCoerced_. 72 | 1. For each element _number_ of _restCoerced_, do 73 | 1. If _number_ is not a BigInt, throw a *TypeError* exception. 74 | 1. If _number_ < _lowest_, set _lowest_ to _number_. 75 | 1. Return _lowest_. 76 | 77 |

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

78 | 79 | 80 | 81 |

BigInt.pow ( _base_, _exponent_ )

82 |

This function performs the following steps when called:

83 | 84 | 1. If _base_ is not a BigInt, throw a *TypeError* exception. 85 | 1. If _exponent_ is not a BigInt, throw a *TypeError* exception. 86 | 1. Return BigInt::exponentiate(_base_, _exponent_). 87 | 88 | 89 | 90 | 91 |

BigInt.prototype

92 |

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

93 |

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

94 | 95 | 96 | 97 |

BigInt.sign ( _x_ )

98 |

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

99 |

It performs the following steps when called:

100 | 101 | 1. If _x_ is not a BigInt, throw a *TypeError* exception. 102 | 1. If _x_ is *0*ℤ, return _x_. 103 | 1. If _x_ < *0*ℤ, return *-1*ℤ. 104 | 1. Return *1*ℤ. 105 | 106 | 107 | 108 |

BigInt.sqrt ( _x_ )

109 |

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

110 |

It performs the following steps when called:

111 | 112 | 1. If _x_ is not a BigInt, throw a *TypeError* exception. 113 | 1. If _x_ < *0*ℤ, throw a *RangeError* exception. 114 | 1. Let _root_ be the square root of ℝ(_x_). 115 | 1. Return ℤ(truncate(_root_)). 116 | 117 | 118 | 119 | --------------------------------------------------------------------------------