{"id":18137817,"url":"https://github.com/tc39/proposal-bigint-math","last_synced_at":"2025-07-10T09:37:05.830Z","repository":{"id":44440904,"uuid":"395672394","full_name":"tc39/proposal-bigint-math","owner":"tc39","description":"Draft specification for supporting BigInts in JavaScript’s Math methods.","archived":false,"fork":false,"pushed_at":"2025-04-09T00:43:50.000Z","size":1536,"stargazers_count":37,"open_issues_count":8,"forks_count":2,"subscribers_count":18,"default_branch":"main","last_synced_at":"2025-04-09T01:31:22.698Z","etag":null,"topics":["bigint","math","proposal","tc39"],"latest_commit_sha":null,"homepage":"https://tc39.es/proposal-bigint-math/","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tc39.png","metadata":{"files":{"readme":"README.md","changelog":"HISTORY.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-08-13T13:51:59.000Z","updated_at":"2024-11-12T20:05:16.000Z","dependencies_parsed_at":"2022-07-19T04:17:10.438Z","dependency_job_id":null,"html_url":"https://github.com/tc39/proposal-bigint-math","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tc39%2Fproposal-bigint-math","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tc39%2Fproposal-bigint-math/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tc39%2Fproposal-bigint-math/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tc39%2Fproposal-bigint-math/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tc39","download_url":"https://codeload.github.com/tc39/proposal-bigint-math/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249751722,"owners_count":21320358,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bigint","math","proposal","tc39"],"created_at":"2024-11-01T15:07:04.543Z","updated_at":"2025-04-19T17:43:39.766Z","avatar_url":"https://github.com/tc39.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BigInt `Math` for JavaScript\nECMAScript Stage 1 Proposal\\\nJ. S. Choi, 2021–2025\n\n* **[Specification][]**\n* **Babel plugin**: Not yet\n\n[specification]: https://tc39.es/proposal-bigint-math/\n\n## Description\n(A [formal draft specification][specification] is available.)\n\nBigInts are important for a myriad of\nmathematical, financial, scientific, and timing applications\n(such as in the [Node.js `process.hrtime.bigint` API][hrtime]),\nand they have been therefore a valuable addition to JavaScript\nsince their standardization in ES 2021.\n\n[hrtime]: https://nodejs.org/api/process.html#process_process_hrtime_bigint\n\nSeveral built-in `Math` functions\nwould make sense with BigInts,\nyet JavaScript still does not have not support them.\nThey only support regular floating-point JavaScript Numbers.\n\n* This proposal adds the following functions\n  to the BigInt object acting as a namespace:\n  * `BigInt.abs`\n  * `BigInt.sign`\n  * `BigInt.sqrt`*\n  * `BigInt.cbrt`*\n  * `BigInt.pow`\n  * `BigInt.min`†\n  * `BigInt.max`†\n* All of these functions return BigInts.\n* None of these functions accept any arguments other than BigInts.\n* * `sqrt` and `cbrt` truncate the result toward 0 into a BigInt.\n* † `min` and `max` require at least one argument.\n\n## Philosophy\nThis proposal balances performance with precedent.\n\n1. Monomorphic functions are much easier for engines to optimize\n   than polymorphic functions.\n2. BigInts and Numbers are not semantically interchangeable.\n   Developers should be aware when using BigInt versus Numbers to avoid errors.\n3. It is ergonomically desirable for BigInt math functions’ API\n   to be as consistent with existing number functions in Math as possible.\n4. Numbers and BigInts are primitives,\n   so math functions should be static functions like `BigInt.abs(v)`,\n   rather than prototype methods like `v.abs()`.\n   * This matches the precedent of `BigInt.asIntN` and `BigInt.asUintN`.\n   * This is unlike the proposed [Decimal128s][].\n     Decimal128s will be objects and thus should use prototype methods.)\n\n[Decimal128s]: https://github.com/tc39/proposal-decimal\n\n## Vision\nThis initial proposal adds only a few first `BigInt` methods.\nThe vision is that this proposal would open up the way\nto new proposals for new BigInt math functions, like:\n\n* `BigInt.gcd(v)`: Greatest common divisor (GCD)\n* `BigInt.popCount(v)`: Population count\n* `BigInt.bitLength(v)`: Bit length, i.e., truncating log\u003csub\u003e2\u003c/sub\u003e\n* `BigInt.modPow(v, exponent, modulus)`: Modular exponentiation\n* `BigInt.modInverse(v, modulus)`: Modular multiplicative inverse\n* `BigInt.fromString(value, radix)`: Base-n string parsing\n* `BigInt.toByteArray(v, endian)`: Conversion to byte array\n* `BigInt.fromByteArray(bytes, endian)`: Conversion from byte array\n\nSome of these may also be appropriate for ordinary integer Numbers.\n\n## Excluded `Math`\n`Math` functions that would not make sense with BigInts\nare excluded from this proposal. These include:\n\n|`Math` method  | Exclusion reason\n| ------------- | ----------------\n|`acos`         | Transcendental: very difficult to calculate when large\n|`acosh`        | Transcendental\n|`asin`         | Transcendental\n|`asinh`        | Transcendental\n|`atan`         | Transcendental\n|`atan2`        | Transcendental\n|`atanh`        | Transcendental\n|`ceil`         | No known use case; `Math.ceil(3n / 2n) == 1` may be surprising\n|`clz32`        | No known use case\n|`cos`          | Transcendental\n|`cosh`         | Transcendental\n|`exp`          | Transcendental\n|`expm1`        | Transcendental\n|`floor`        | No known use case\n|`fround`       | Returns floating-point numbers by definition\n|`hypot`        | No known use case\n|`imul`         | No known use case\n|`log`          | Transcendental\n|`log10`        | Truncation may be surprising; no known use case\n|`log2`         | Truncation may be surprising; deferred to future `bitLength` proposal\n|`log1p`        | Transcendental\n|`random`       | No conceptual integer-only analogue\n|`round`        | No known use case; `Math.round(3n / 2n) == 1` may be surprising\n|`sin`          | Transcendental\n|`sinh`         | No known use case\n|`tan`          | Transcendental\n|`tanh`         | Transcendental\n|`trunc`        | No known use case\n\n[issue #3]: https://github.com/js-choi/proposal-bigint-math/issues/3#issuecomment-912133467\n[issue #6]: https://github.com/js-choi/proposal-bigint-math/issues/6\n[issue #8]: https://github.com/js-choi/proposal-bigint-math/issues/8\n[issue #9]: https://github.com/js-choi/proposal-bigint-math/issues/9\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftc39%2Fproposal-bigint-math","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftc39%2Fproposal-bigint-math","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftc39%2Fproposal-bigint-math/lists"}