The TC39 Decimal proposal aims to add functionality to JavaScript to represent base-10 decimal numbers.
The champions welcome your participation in discussing the design space in the issues linked above. We are seeking input for your needs around JavaScript decimal in this survey.
Champions:
Authors: Jesse Alama, Waldemar Horwat
Stage: Stage 1 of the TC39 process. A draft specification is available.
Accurate storage and processing of base-10 decimal numbers is a frequent need in JavaScript. Currently, developers sometimes represent these using libraries for this purpose, or sometimes use Strings. Sadly, JavaScript Numbers are also sometimes used, leading to real, end-user-visible rounding errors.
What’s the issue? Why aren’t JS Numbers good enough? In what sense are they not “exact”? How is it possible that JavaScript's Numbers get something wrong, and have been getting it wrong for so long?
As currently defined in JavaScript, Numbers are 64-bit binary floating-point numbers. The conversion from most decimal values to binary floats rarely is an exact match. For instance: the decimal number 0.5 can be exactly represented in binary, but not 0.1; in fact, the the 64-bit floating point number corresponding to 0.1 is actually 0.1000000000000000055511151231257827021181583404541015625. Same for 0.2, 0.3, … Statistically, most human-authored decimal numbers cannot be exactly represented as a binary floating-point number (AKA float).
The goal of the Decimal proposal is to add support to the JavaScript standard library for decimal numbers in a way that provides good ergonomics, functionality, and performance. JS programmers should feel comfortable using decimal numbers, when that’s appropriate. Being built-in to JavaScript means that we will get optimizable, well-maintained implementations that don’t require transmitting, storing, or parsing and jit-optimizing every additional JavaScript code.
Many currencies tend to be expressed with decimal quantities. Although it’s possible to represent money as integer “cents” (multiply all quantities by 100), this approach runs into a couple of issues:
Intl.NumberFormat only knows how to format JS Numbers, and can’t deal with an integer-and-exponent pair.In the examples that follow, we'll use Decimal128 objects. (Why "Decimal128"? See below!)
function calculateBill(items, tax) {
let total = new Decimal128(0);
for (let {price, count} of items) {
total = total.add(new Decimal128(price).times(new Decimal128(count)));
}
return total.multiply(tax.add(new Decimal128(1)));
}
let items = [{price: "1.25", count: 5}, {price: "5.00", count: 1}];
let tax = new Decimal128("0.0735");
let total = calculateBill(items, tax);
console.log(total.toFixed(2));Let's convert USD to EUR, given the exchange rate EUR --> USD.
let exchangeRateEurToUsd = new Decimal128("1.09");
let amountInUsd = new Decimal128("450.27");
let exchangeRateUsdToEur = new Decimal128(1).divide(exchangeRateEurToUsd);
let amountInEur = exchangeRateUsdToEur.multiply(amountInUsd);
console.log(amountInEur.round(2).toString());const options = {
minimumFractionDigits: 2,
maximumFractionDigits: 4
};
const formatter = new Intl.NumberFormat(options)
formatter.format(new Decimal128("1.0")); // "1.00"
formatter.format(new Decimal128("1.000")); // "1.000"
formatter.format(new Decimal128("1.00000")); // "1.000"Historically, JavaScript may not have been considered a language where exact decimal numbers are even representable, to say nothing of doing (exact) calculations. In some application architectures, JS only deals with a string representing a human-readable decimal quantity (e.g, "1.25"), and never does calculations or conversions. However, several trends push towards JS’s deeper involvement in with decimal quantities:
In all of these environments, the lack of decimal number support means that various workarounds have to be used (assuming, again, that programmers are even aware of the inherent mismatch between JS’s built-in binary floating-point numbers and proper decimal numbers):
In other words, with JS increasingly being used in contexts and scenarios where it traditionally did not appear, the need for being able to natively handle basic data, such as decimal numbers, that other systems already natively handle is increasing.
This use case implies the following goals:
In both frontend and backend settings, JavaScript is used to communicate with external systems, such as databases and foreign function interfaces to other programming languages. Many external systems already natively support decimal numbers. In such a setting, JavaScript is then the lower common denominator. With decimals in JavaScript, one has the confident that the numeric data one consumes and produces is handled exactly.
JavaScript is frequently used as a language to glue other systems together, whether in client, server or embedded applications. Its ease of programming and embedding, and ubiquity, lend itself to this sort of use case. Programmers often don’t have the option to choose another language. When decimals appear in these contexts, it adds more burden on the embedder to develop an application-specific way to handle things; such specificity makes things less composable.
This use case implies the following goals:
+, -, * should be availableInteraction with other systems brings the following requirements:
The following is fictional, but illustrates the idea. Notice the sql_decimal configuration option and how the values returned from the DB are handled in JS as Decimal values, rather than as strings or as JS Numbers:
const { Client } = require('pg');
const client = new Client({
user: 'username',
sql_decimal: 'decimal', // or 'string', 'number'
// ...more options
});
const boost = new Decimal128("1.05");
client.query('SELECT prices FROM data_with_numbers', (err, res) => {
if (err) throw err;
console.log(res.rows.map(row => row.prices.times(boost)));
client.end();
});If it works out reasonably to provide for it within the same proposal, it would also be nice to provide support for higher-precision applications of floating point numbers.
If Decimal is arbitrary-precision or supports greater precision than Number, it may also be used for applications which need very large floating point numbers, such as astronomical calculations, physics, or even certain games. In some sense, larger or arbitrary-precision binary floats (as supported by QuickJS, or IEEE 754 128-bit/256-bit binary floats) may be more efficient, but Decimal may also be suitable if the need is ultimately for human-consumable, and reproducible, calculations.
In addition to the goals which come directly from use cases mentioned above:
If Decimal becomes a part of standard JavaScript, it may be used in some built-in APIs in host environments:
postMessage, IndexedDB, etc.More host API interactions are discussed in #5.
Based on feedback from JS developers, engine implementors, and the members of the TC39 committee, we have nailed down a fairly concrete proposal. Please see the spec text (HTML version). are provided below. You’re encouraged to join the discussion by commenting on the issues linked below or filing your own.
We will use the Decimal128 data model for JavaScript decimals. Decimal128 is not a new standard; it was added to the IEEE 754 floating-point arithmetic standard in 2008. It represents the culmination of decades of research, both theoretical and practical, on decimal floating-point numbers. Values in the Decimal128 universe take up 128 bits. In this representation, up to 34 significant digits (that is, decimal digits) can be stored, with an exponent (power of ten) of +/- 6143.
The "BigDecimal" data model is based on unlimited-size decimals (no fixed bith-width), understood exactly as mathematical values.
From the champion group’s perspective, both BigDecimal and Decimal128 are both coherent, valid proposals that would meet the needs of the primary use case. Just looking at the diversity of semantics in other programming languages, and the lack of practical issues that programmers run into, shows us that there are many workable answers here.
Operators always calculate their exact answer. In particular, if two BigDecimals are multiplied, the precision of the result may be up to the sum of the operands. For this reason, BigDecimal.pow takes a mandatory options object, to ensure that the result does not go out of control in precision.
One can conceive of an arbitrary-precision version of decimals, and we have explored that route; historical information is available at bigdecimal-reference.md.
One difficulty with BigDecimal is that division is not available as a two-argument function because a rounding parameter is, in general, required. A BigDecimal.div function would be needed, where some options would be mandatory. See #13 for further discussion of division in BigDecimal.
Further discussion of the tradeoffs between BigDecimal and Decimal128 can be found in #8.
Imagine that every decimal number has, say, ten digits after the decimal point. Anything requiring, say, eleven digits after the decimal point would be unrepresentable. This is the world of fixed-precision decimals. The number ten is just an example; some research would be required to find out what a good number would be. One could even imagine that the precision of such numbers could be parameterized.
Rational numbers, AKA fractions, offer an adjacent approach to decimals. From a mathematical point of view, rationals are more expressive than decimals: every decimal is a kind of fraction (a signed integer divided by a power of ten), whereas some rationals, such as 1/3, cannot be (finitely) represented as decimals. So why not rationals?
Fractions would be an interesting thing to pursue in TC39, and are in many ways complementary to Decimal. The use cases for rationals overlap somewhat with the use cases for decimals. Many languages in the Lisp tradition (e.g., Racket) include rationals as a basic data type, alongside IEEE 754 64-bit binary floating point numbers; Ruby and Python also include fractions in their standard library.
We see rationals as complementary to Decimal because of a mismatch when it comes to two of the core operations on Decimals:
These could be defined on rationals, but are a bit of an inherent mismatch since rationals are not base 10.
Rational may still make sense as a separate data type, alongside Decimal. Further discussion of rationals in #6.
With Decimal we do not envision a new literal syntax. One could consider one, such as 123.456_789m is a Decimal value (#7), but we are choosing not to add new syntax in light of feedback we have received from JS engine implementors as this proposal has been discussed in multiple TC39 plenary meetings.
Decimal is based on IEEE 754 Decimal128, which is a standard for base-10 decimal numbers using 128 bits. We will offer a subset of the official Decimal128. There will be, in particular:
NaN of JS. The difference between quiet and singaling NaNs will be collapsed into a single Decimal NaN.NaN, they are distinct from JS's built-in Infinity and -Infinity.Decimal canonicalizes when converting to strings and after performing arithmetic operations. This means that Decimals do not expose information about trailing zeroes. Thus, "1.20" is valid syntax, but there is no way to distinguish 1.20 from 1.2. This is an important omission from the capabilities defined by IEEE 754 Decimal128.
Intl.NumberFormat and Temporal won't be supported.)The library of numerical functions here is kept deliberately minimal. It is based around targeting the primary use case, in which fairly straightforward calculations are envisioned. The secondary use case (data exchange) will involve probably little or no calculation at all. For the tertiary use case of scientific/numerical computations, developers may experiment in JavaScript, developing such libraries, and we may decide to standardize these functions in a follow-on proposal. We currently do not have good insight into the developer needs for this use case, except generically: square roots, exponentiation & logarithms, and trigonometric functions might be needed, but we are not sure if this is a complete list, and which are more important to have than others. In the meantime, one can use the various functions in JavaScript’s Math standard library.
Decimal128 objects can be constructed from Numbers, Strings, and BigInts. Similarly, there will be conversion from Decimal128 objects to Numbers, String, and BigInts.
toString() is similar to the behavior on Number, e.g., new Decimal128("123.456").toString() is "123.456". (#12)toFixed() is similar to Number's toFixed()toPrecison() is similar to Number's toPrecision()toExponential() is similar to Number's toExponential()Intl.NumberFormat.prototype.format should transparently support Decimal (#15)The vision of decimal sketched here represents the champions current thinking and goals. In our view, decimal as sketched so far is a valuable addition to the language. That said, we envision improvements and strive to achieve these, too, in a version 2 of the proposal. What follows is not part of the proposal as of today, but we are working to make the first version compatible with these future additions.
In earlier discussions about decimal, we advocated for such overloading arithmetic operations (+, *, etc.) and comparisons (==, <, etc.), as well as ===. But based on strong implementer feedback, we have decided to work with the following proposal:
+, *, and so on throw when either argument is a decimal value. Instead, one will have to use the add, multiply, etc. methods. Likewise, comparison operators such as ==, <, <=, etc. will also throw when either argument is a decimal. One should use the equals and lessThan methods instead.=== will work (won't throw an exception), but it will have its default object semantics; nothing special about decimal values will be involved.However, the door is not permanently closed to overloading. It is just that the bar for adding it to JS is very high. We may be able to meet that bar if we get enough positive developer feedback and work with implementors to find a path forward.
In earlier discussions of this proposal, we had advocated for adding new decimal literals to the language: 1.289m (notice the little m suffix). Indeed, since decimals are numbers—essentially, basic data akin to the existing binary floating-point numbers—it is quite reasonable to aim for giving them their own "space" in the syntax.
However, as with operator overloading, we have received strong implementor feedback that this is very unlikely to happen.
Nonetheless, we are working on making sure that the v1 version of the proposal, sketched here, is compatible with a future in which decimal literals exist. As with operator overloading, discussions with JS engine implementors need to be kept open to find out what can be done to add this feature. (On the assumption that a v1 of decimals exists, one can add support for literals fairly straightforwardly using a Babel transform.)
In our discussions we have consistently emphasized the need for basic arithmetic. And in the v1 of the proposal, we in fact stop there. One can imagine Decimal having all the power of the Math standard library object, with mathematical functions such as:
These can be more straightforwardly added in a v2 of Decimal. Based on developer feedback we have already received, we sense that there is relatively little need for these functions. But it is not unreasonable to expect that such feedback will arrive once a v1 of Decimal is widely used.
See the discussion above, about data models, where rationals are discussed.
This depends on implementations. Like BigInt, implementors may decide whether or not to optimize it, and what scenarios to optimize for. We believe that, with either alternative, it is possible to create a high-performance Decimal implementation. Historically, faced with a similar decision of BigInt vs Int64, TC39 decided on BigInt; such a decision might not map perfectly because of differences in the use cases. Further discussion: #27
One option that’s raised is allowing for greater precision in more capable environments. However, Decimal is all about avoiding unintended rounding. If rounding behavior depended on the environment, the goal would be compromised in those environments. Instead, this proposal attempts to find a single set of semantics that can be applied globally.
See COMPARISON.md for details.
See RELATED.md for details.
Many decimal implementations support a global option to set the maximum precision (e.g., Python, Ruby). In QuickJS, there is a “dynamically scoped” version of this: the setPrec method changes the maximum precision while a particular function is running, re-setting it after it returns. Default rounding modes could be set similarly.
Although the dynamic scoping version is a bit more contained, both versions are anti-modular: Code does not exist with independent behavior, but rather behavior that is dependent on the surrounding code that calls it. A reliable library would have to always set the precision around it.
There is further complexity when it comes to JavaScript’s multiple globals/Realms: a Decimal primitive value does not relate to anything global, so it would be inviable to store the state there. It would have to be across all the Decimals in the system. But then, this forms a cross-realm communication channel.
Therefore, this proposal does not contain any options to set the precision from the environment.
Mike Cowlishaw’s excellent Decimal FAQ explains many of the core design principles for decimal data types, which this proposal attempts to follow.
One notable exception is supporting trailing zeroes: Although Mike presents some interesting use cases, the Decimal champion group does not see these as being worth the complexity both for JS developers and implementors. Instead, Decimal values could be lossly represented as rationals, and are “canonicalized”.
This proposal can be seen as a follow-on to BigInt, which brought arbitrary-sized integers to JavaScript, and will be fully standardized in ES2020. However, unlike BigInt, Decimal (i) does not propose to intrduce a new primitive data type, (ii) does not propose operator overloading (which BigInt does support), and (iii) does not offer new syntax (numeric literla), which BigInt does add (e.g., 2345n).
--bignum flag)Your help would be really appreciated in this proposal! There are lots of ways to get involved:
See a full list of to-do tasks at #45.