Decimal Stage 1 Update: Amounts

<style> /* make code examples suck less */ pre code { margin: 0 !important; font-size: 1.25em !important; } pre { padding: 0 !important; text-align: left !important; } .align-left { text-align: left !important; } .small-li li { font-size: 0.85em !important; } </style>  # Decimal Stage 1 Update: Amounts Jesse Alama (Igalia, in partnership with Bloomberg & Google) jesse@igalia.com April 2025 --- ## What's new * We've settled on the semantics and API of Decimal but haven't yet resolved the Intl side of things. * We propose a new `Decimal.Something` class for storing a decimal value with a precision. * The name is TBD! Maybe `Decimal.Amount`? `Decimal.WithPrecision`? * This small class rounds out the Intl story for Decimal. * Looking forward: If `Decimal.Something` is accepted, the measure proposal may add fields to this new class to store a unit or currency indicator. --- ## Motivation & use cases * For *internationalization* we would like to have a "number" that knows its own precision (not just a point on the number line) * Usage of Number with Intl is currently error-prone, and a new numeric type should not be created with the same footgun. * The need exists in parallel to the need for exact decimal values (as mathematical values) currently met by our "canonicalized" variant of IEEE 754 Decimal128 in `Decimal` --- ## How this amounts idea came about * In the last plenary, we discussed the overlap between the decimal and measure proposal. * We even suggested "merging" the proposals, but the consensus was that they should remain separate (use cases too different). * We discussed having three classes: for (i) Decimal, (ii) "number plus precision", and (iii) measure. But this didn't get much traction. --- ## Separating units * The discussion of units (including currency codes) naturally suggests a number of issues that can be separated from the underlying number. * `Decimal` focuses on *numbers*, with or without precision, freeing us from concerns about units. * The measure proposal could then expand `Decimal.Something`, rather than introducing a new class. --- ## API for `Decimal.Something` * Data constructed using convenience functions on `Decimal.prototype` * Maybe with `new`, too, or via a static `.from` method? * Accessor for the underlying Decimal and precision * `toString` * No arithmetic (use `Decimal`) * Integration with `Intl.NumberFormat` and `Intl.PluralRules`. * Immutable --- ## Example: Creating one of these objects ```js new Decimal("42.56").togetherWithSignificantDigits(2); new Decimal("42.56").togetherWithFractionalDigits(5); ``` _⚠️ method names are just placeholders!_ --- ## Intl diff * We propose that `Intl.PluralRules` not handle `Decimal` values * `Intl.NumberFormat` can continue to handle bare `Decimal`s, perhaps requiring a number of fractional/significant digits * Instead, `Intl.Plural` should handle `Decimal.Something` values * `Intl.NumberFormat` should handle `Decimal.Something` values, too, regardless of the decision above regarding bare Decimals --- ## Integration with the [measure proposal](https://github.com/tc39/proposal-measure) The measure proposal can be slotted in later, with a unit or currency attached to an amount: ```js let d = new Decimal("5.613"); d.withUnit("kg"); // 5.613 kilograms d.toAmount(5, "significantDigits").withUnit("kg"); // 5.6130 kilograms ``` _⚠️ method names are just placeholders!_ <small>(This assumes Decimal happens before Measure, or at the same time. Measure doesn't actually *need* Decimal. If Decimal doesn't happen, we can still work on Measure.)</small> --- ## Conclusion * Measure and Decimal remain separate * Decimal [spec text](https://github.com/tc39/proposal-decimal/pull/188#commits-pushed-8ba3bba) available * If `Decimal.Something` or something like it looks good, we intend to ask for Stage 2 for decimal at the next plenary --- ## Discussion