Decimal.Amount

[sffc]

I wanted to suggest a direction that solves many of our current issues while also leaving the door open for more flexibility in the future.

Along with the Decimal proposal, we introduce one new type: Decimal.Amount. Key features:

• Is immutable
• Always holds a Decimal as the numeric type (not polymorphic)
• Supports a precision, designed such that implementations may store the precision in the bits of the Decimal
  • i.e., precision is defined according to the Decimal128 cohorts. The distinction between withFractionDigits and withSignificantDigits is flattened when setting the precision on a Decimal.Amount.
  • (2.5m).withFractionalDigits(2).equals((2.5m).withSignificantDigits(3)) === true
• The unit or currency is optional and is held in its own slot
  • This proposal is independent of how we express currency vs unit, whether we allow custom units, etc. We have separate issues to debate those concerns.
• Can be created via from functions, a constructor, and/or convenience methods on Decimal

Some prototype functions would be:

• Decimal.prototype.withUnit returns a Decimal.Amount with the specified unit (and no trailing zeros)
• Decimal.prototype.withFractionalDigits returns a Decimal.Amount with a null unit and the specified number of digits after the decimal separator, which may involve adding trailing zeros
• Decimal.prototype.withSignificantDigits behaves similarly but counts from the most significant digit
• Decimal.Amount.prototype.withUnit and Decimal.Prototype.withFractionalDigits that allow for the precision and unit to be set in an immutable way
• Decimal.Amount.prototype.equals which performs "full" equality (decimal numeric value, precision, and unit)

Problems this solves right now:

• Ergonomic, immutable data type for currency and measurement amounts
• Intl formatting and plural selection with units and trailing zeros, including MessageFormat
• Ability to represent and round-trip Full Decimal128 in JavaScript

What this direction allows us to do in the future:

• Have additional types that support other numeric types like numbers, BitInts, or Rationals
  • example: BigInt.Amount
• Use as a basis for some type of unit conversion API

[jessealama]

I like this.

It sounds like this approach is agnostic about units. They're always present, but what they mean is unspecified. One question I have is about forward compatibility, in which we give some semantics to units. I'd like to eventually see a world where amounts with convertible units get compared. Example:

new Decimal.Amount({unit: "g", value: "1000"}

should perhaps be treated as equal to

new Decimal.Amount({unit: "kg", value: "1"})

Perhaps one way to achieve that would be to have .equals work as you suggest, namely component-wise strict comparison. A later version of this proposal could then support comparison options that allow for comparison to work for CLDR-specified units, like so:

let grams = new Decimal.Amount({unit: "g", value: "1000"});
let kilograms = new Decimal.Amount(unit: "kg", value: "1"});
grams.equals(kilograms); // false
grams.equals(kilograms, { convertUnits: true }); // true

[jessealama]

I wonder if we want to make it possible to create an Amount where we specify significant digits, as an alternative to fractional digits. I'm thinking of a "precision mode" (not the greatest of names), with two possibilities:

• fractional digits
• significant digits

(Maybe we could have fractional digits be a default. I think this is probably what most programmers have in mind when they think of decimal numbers.)

[jessealama]

Do we want to namespace this under Decimal or perhaps Intl?

[sffc]

We discussed this in the champions call.

My responses to @jessealama's comments/questions:

Comparing meter and kilometer: Comparison across units should come with a unit conversion API and shouldn't happen automatically in my mental model.

A "thin" unit conversion API could be one that works only on SI prefixes, since that is exactly representable in Decimal128 (conversion from "kilometer" to "meter", for instance). In this world, your desire could be expressed as, for example, grams.normalizeUnit().equals(kilograms.normalizeUnit())

Specifying fractional vs significant digits: In my model, the fractional/significant digit settings get applied to the decimal immediately at the call site. For example:

let d = new Decimal("2.5");
d.withSignificantDigits(3).equals(d.withFractionDigits(2)) // true

Name of the type: Giving it the name Decimal.Amount is a fundamental piece of my latest proposal.

1. It clarifies that the Amount contains a Decimal and not some other numeric type
2. It leaves open the possibility that we could have Amounts for other numeric types, such as BigInt.Amount, Number.Amount, or Rational.Amount
3. It looks like a natural extension of Decimal (which it is), rather than a whole new global type
4. It emphasizes that Amount has use cases beyond just the Intl interface, specifically offering an immutable primordial for client libraries to pass around currency/unit-annotated numbers, and representing precision in Decimals for round-tripping with other libraries

[eemeli]

It looks like a natural extension of Decimal (which it is), rather than a whole new global type

Would such a Decimal.Amount also inherit capabilities like .add() and other operations that are planned to be available on Decimal? As a developer, that would be my presumption from the .with*() API style, as that's what the corresponding Array and Temporal methods effectively do.

If Amount operations are not supported, then I don't think we should present Amount as an extensions of something which would support those operations.

[nicolo-ribaudo]

(I'm neither Jesse nor Shane, but I was in the meeting two weeks ago where they discussed it)

No, Decimal.Amount would not support .add() and friends. The idea was that the more information you add, the less you can do with the number (this is similar to how, for example, 1+2 is a totally valid operation but as soon as I tell you that 1 is liters and 2 is meters it becomes invalid). While there isn't a technical limitation to supporting .add() to numbers with precision, we've clearly seen from the past discussions in the committee that there is no single good way of doing it. Precision propagation varies on the context, and it's better to force developers to do it themselves than to provide a default way.

Decimal.Amount is an extension of Decimal only when it comes to the information it carries. Maybe .with is not the best prefix for those methods if you think it comes with the expectation of getting back an object that has at least all the same methods as the original one, rather than just at least all the same information.

[sffc]

As a developer, that would be my presumption from the .with*() API style, as that's what the corresponding Array and Temporal methods effectively do.

Good point. In Temporal, we generally use toFoo as the function name when transitioning between types. I think we should consider renaming the functions to say to instead of with. For example, Decimal.prototype.toAmount which takes an argument with the unit and/or precision. We can bikeshed the exact signature and behavior of that function later during Stage 2.

[eemeli]

toAmount would definitely be better than withUnit, withFractionalDigits, and withSignificantDigits, but why is it needed? And would it be the only such method?

What is the gain in ergonomics that's being enabled here over a plain new Amount(value, options), or even new Decimal.Amount(value, options)? It seems like we're doing quite a bit of work to avoid the new, and I don't understand the reason for that.

[sffc]

I'm fine with also having a constructor on Decimal.Amount.

I think a starting point is basically

Decimal.prototype.toAmount = function(...args) {
    return new Decimal.Amount(this, ...args);
}

But, Temporal introduced the design pattern of low-level constructors and favoring factory methods. I think we should lean into that design more than constructors.

Some more strawpeople:

let d = Decimal.from("1.23");

let a1 = d.toAmount({ fractionDigits: 5 });
a1.toString(); // "1.23000"
a1.equals(d); // false

let a2 = d.toAmount({ significantDigits: 6 });
a1.equals(a2); // true

let a3 = d.toAmount({ significantDigits: 4 });
a1.equals(a3); // false

let a4 = a1.withUnit("meter");
a4.toString(); // not yet determined but perhaps "1.23000[meter]"
a4.equals(a1); // false

let a5 = d.toAmount({
    fractionDigits: 5,
    unit: "meter",
});
a5.equals(a4); // true

[nicolo-ribaudo]

I was going to say "I dislike .toAmount because it will need an option bag do distinguish between fractional vs significant digits", but that example where you pass bot the precision and the unit in a single call is very nice.

[jessealama]

Indeed, a two-argument .toAmount is the current thinking and is implemented in the (unmerged) version of the polyfill.

[jessealama]

One line of thinking with the constructor for Decimal.Amount is that it would be opinionated. It would take two arguments: a (decimal) String s, and a Number p. The interpretation of p would always be in terms of significant digits. We could switch that to fractional digits, but the point is that the constructor would have an unambiguous interpretation. (For Decimal.Amount it's somewhat convenient to use significant digits because IEEE 754 Decimal128 has a hard limit -- 34 -- on the maximum number of significant digits that can be contained in a value.)

[sffc]

@eemeli had some questions about roundtripping precision. Here's my mental model for how that works:

let amount = Decimal.Amount.from("6.200");

amount.toString(); // 6.200

let doubledDecimal = amount.toDecimal().times(new Decimal("2"));

doubledDecimal.toString(); // 12.4

let doubledAmount = doubledDecimal.toAmount({ significantDigits: amount.significantDigits() });

doubledAmount.toString(); // 12.40

let doubledAmountFrac = doubledDecimal.toAmount({ fractionDigits: amount.fractionDigits() });

doubledAmountFrac.toString(); // 12.400

@gibson042 says "this example is comprehensible and unsurprising"