Amount + Sequence Units

[sffc]

Now that both of these proposals are Stage 2 🎊, we need to figure out how they fit together.

We had some brainstorming discussions with myself and @eemeli and @lucacasonato and @ljharb and others at TC39.

Some points that people have raised; not all of these bullet points are universally held:

• Adding sequence units should not (significantly) hurt ergonomics of non-sequence units
• Sequence units should be first-class in most functionality, including the constructor, convertTo, and formatting
• We should try to keep just 1 Amount type, not adding a second to support sequence units

There are a handful of shapes to consider:

1. Amount is a single unit; sequence units are returned as arrays
2. Amount is a sequence unit; single units are returned as objects
3. Amount is a sequence unit; getting a single unit means querying the first entry of it

A design that seems to solve most of the design constraints is an Amount.prototype.total function that behaves like this:

let amt1 = new Amount(123, { unit: "centimeter" });
amt1.getMeasures()  // [{ unit: "centimeter", value: 123 }]
amt1.total()  // { unit: "centimeter", value: 123 }]

let amt2 = amt1.convertTo({ units: ["meter", "centimeter"] });
amt1.getMeasures()  // [{ unit: "meter", value: 1 }, { unit: "centimeter", value: 23 }]
amt2.total()  // { unit: "meter", value: 1.23 }

Some open questions:

• Maybe .getMeasures() should be a getter that returns a deeply frozen array
• Maybe we should allow unit: "meter-and-centimeter" and/or drop the units option
• Should we still have a .unit getter, and if so, what should it return?
• Should we still have a .value getter, and if so, what should it return?
• Should we allow only sanctioned units to be a member of a sequence unit, so that we can enforce the correct order and implement .total(), or should we throw in .total() when the unit is not sanctioned? Also see Include conversion data for all units, not just Intl-sanctioned units? #117

[gibson042]

A design that seems to solve most of the design constraints is an Amount.prototype.total function that behaves like this:

let amt1 = new Amount(123, { unit: "centimeter" });
amt1.getMeasures() // [{ unit: "centimeter", value: 123 }]
amt1.total() // { unit: "centimeter", value: 123 }]

let amt2 = amt1.convertTo({ units: ["meter", "centimeter"] });
amt1.getMeasures() // [{ unit: "meter", value: 1 }, { unit: "centimeter", value: 23 }]
amt2.total() // { unit: "meter", value: 1.23 }

This seems reasonable to me, modulo bikeshedding. I'm assuming that total will be similar to Temporal.Duration.prototype.total and accept an argument controlling the output unit?

My opinion on the open questions:

• Maybe .getMeasures() should be a getter that returns a deeply frozen array

I'm fine with either.

• Maybe we should allow unit: "meter-and-centimeter" and/or drop the units option

Representation of units should remain limited to string, so amount.convertTo({ unit: "meter-and-centimeter" }). I'd also prefer to make that strict, although GetOption currently doesn't (it uses ToString).

• Should we still have a .unit getter, and if so, what should it return?

Yes, and it should return the sequence unit string (e.g., "meter-and-centimeter").

• Should we still have a .value getter, and if so, what should it return?

I think dropping it would make for bad ergonomics, so it should probably remain and return a frozen array of primitives (e.g., [3, 11]) or Record<SimpleUnitString, Primitive> (e.g., { foot: 3, inch: 11 }) that gets created at construction and stored in an internal slot.

• Should we allow only sanctioned units to be a member of a sequence unit, so that we can enforce the correct order and implement .total(), or should we throw in .total() when the unit is not sanctioned? Also see Include conversion data for all units, not just Intl-sanctioned units? #117

Having sequence units means applying special behavior to unit strings that contain "-and-", but I think it's fine for those to remain relatively arbitrary (e.g., new Amount({ bushel: 4, peck: 2 }, { unit: "bushel-and-peck" })). But convertTo/total/etc. should be limited to a sanctioned list.

[eemeli]

The third proposal that needs to be kept in mind is the intl unit protocol, i.e. how Intl.NF.p.format() reads its argument. I would find it quite awkward if that protocol ended up requiring a method function call.

One property of our current (pre-sequence-unit-supporting) design that I appreciate is that Number(a.value) and String(a.value) will always work.

I also think that keeping the unit identifier as a single string with -and- infixes is appropriate, and preferable to it sometimes being a single string, and sometimes an array of strings.

I would be comfortable restricting valid sequence unit identifiers to be only the ones supported by CLDR data; I do not believe that there is a strong use case to be made for e.g. bushel-and-peck, but I would prefer for arbitrary single-value user-definable units to continue to be supported.

Regarding the scalar representation of sequence unit values, the only strong arguments for preferring the smallest rather than largest unit as the base that I'm aware of are 1) the loss in precision/accuracy for non-decimal values, and 2) potential confusion regarding the base used for fraction digit rounding. If we were to retain and provide accessors to both a scalar and a sequence of values representation, I believe these concerns can be addressed; this can allow us to always presume that the largest unit is used for scalar representation.

With the above in mind, my current preferred solution for sequence unit handling in Amount would have the following API:

class Amount {
  get value(): number | bigint | string
  get values(): ReadonlyArray<number | bigint | string>
  get unit(): string | null

  constructor(value: number | bigint | string | Array<number | bigint | string>, options)
  convertTo(options): Amount
  ...
}

The way this would work is that every Amount could be constructed from either a single scalar, or an array of scalars, and that it would provide access to both a scalar .value and a frozen array of scalars .values. The single-scalar representation would always be tied to the largest unit. The spec would need to ensure that the conversion between these can be done lazily, so that no extra work gets done. Attempting to construct a sequence unit Amount from unsupported units would throw. For conversions and formatting, the array of scalars would always be preferred as the source value when using sequence units.

The intl unit protocol would be to:

1. Look for a .unit field.
2. If the unit has an -and- infix and the object contains a .values array, use that.
3. Else, look for a .value field.
4. If a unit and a value or array of values is available, apply the protocol.

[gibson042]

The way this would work is that every Amount could be constructed from either a single scalar, or an array of scalars

I don't think I can get behind this. For one, there will be unavoidable confusion about e.g. new Amount(6, { unit: "foot-and-inch" }). But also, I think mapping such scalars into the largest unit will break round-tripping anyway—there is no Number of feet that can produce new Amount(3.6, { unit: "inch" }), and no terminating decimal string of feet that can produce new Amount(8, { unit: "inch" }).

[ljharb]

I kind of think that it might be better to retain "Amount" as only ever being for a single unit - but having a static method like Amount.combine(amounts, primaryUnit) - amounts is an array of Amount objects whose units are all convertible within each other, and primaryUnit is a unit they're all convertible to - and to leave the "foot and inch" stuff to just formatting. Thoughts?

[gibson042]

I think that would fail to support valuable use cases like new Amount({ foot: 7, inch: 6 }, { unit: "foot-and-inch" }).convertTo({ unit: "meter" }).

[ljharb]

My suggestion would be to support that use case like this:
Amount.combine([{ foot: 7 }, { inch: 6 }], 'foot').convertTo({ unit: 'meter' })

The first part would be an Amount with 7.5 feet.

[eemeli]

For one, there will be unavoidable confusion about e.g. new Amount(6, { unit: "foot-and-inch" }).

The way I see it, this confusion would be quite minor, especially as it can be avoided by alternative approaches like

new Amount([6, 0], { unit: "foot-and-inch" })

or

new Amount(6, { unit: "foot" }).convertTo({ unit: "foot-and-inch" })

We could also prohibit single-scalar constructors for sequence units, but tbh that's starting to seem unnecessary to me.

But also, I think mapping such scalars into the largest unit will break round-tripping anyway—there is no Number of feet that can produce new Amount(3.6, { unit: "inch" }), [...]

We can avoid round-tripping errors here by never round-tripping. As in, for an Amount built from a scalar, assign that scalar to its .value and calculate the .values from it; for an Amount build from an array of scalars, assign those array values to .values, and calculate the .value from them.

This does mean that in some cases the equivalences of .value and .values might not be equal:

let a = new Amount(0.3, { unit: 'foot-and-inch' })
a.value // 0.3
a.values // [0, 3.5999999999999996]

let b = new Amount([0, 3.5999999999999996], { unit: 'foot-and-inch' })
b.value // 0.29999999999999993
b.values // [0, 3.5999999999999996]

If we use the more exact conversions proposed in #115, I'm pretty sure that this disparity goes away.

[...] and no terminating decimal string of feet that can produce new Amount(8, { unit: "inch" }).

I don't think I understand this part. Is this also about round-tripping? And is this about Number values, or decimal one? I see this:

0.6666666666666666 * 12 === 8 
0.6666666666666667 * 12 === 8

[sffc]

I like @eemeli's design.

I think @ljharb's design is also workable, but needs to be fleshed out more. It's basically the first option in the OP, "Amount is a single unit; sequence units are returned as arrays" except that sequence units are also accepted as arrays.

With @ljharb's design, I am assuming that:

1. Amount always holds a single unit (or null)
2. Amount.prototype.convertTo returns either an Amount (for a single unit) or an Amount[] (for a sequence unit)

If this is true, it means that amt.convertTo("meter-and-centimeter").toLocaleString("en") won't behave as expected (but it will not throw since Array.prototype.toLocaleString is defined!). It was pointed out to me that this might be acceptable if we just document that amt.toLocaleString("en", { unit: "meter-and-centimeter" }) is the recommended calling convention.

With either of these, we could still choose to have Amount.prototype.total().

[ljharb]

That's not exactly what I suggested. I'm suggesting that the entire class of "meter-and-centimeter" units simply not be a thing except in formatter options - that an Amount can only ever be for a single conceptual unit, and the only time you'd display it as multiple units (3'4", eg) is in formatted output, for display purposes only.

[sffc]

It's important to me that we are able to represent sequence units in non-intl code because:

1. If it is intl-only, then people need to parse intl output to figure out how their inputs get split into the sequence units, which we need to avoid
2. Intl should not perform unit conversion or balancing itself; as with Intl.DurationFormat, this task should be generally delegated to another API
3. Intl formatters should be as thin as possible with as much data represented in the input type as possible

[gibson042]

For one, there will be unavoidable confusion about e.g. new Amount(6, { unit: "foot-and-inch" }).

The way I see it, this confusion would be quite minor, especially as it can be avoided by alternative approaches like

new Amount([6, 0], { unit: "foot-and-inch" })

or

new Amount(6, { unit: "foot" }).convertTo({ unit: "foot-and-inch" })

We could also prohibit single-scalar constructors for sequence units, but tbh that's starting to seem unnecessary to me.

Single-scalar values with sequence units are the very crux of my "unavoidable confusion" complaint, and IMO must not be acceptable. Both of your examples above are clear precisely because they don't have that pattern.

But also, I think mapping such scalars into the largest unit will break round-tripping anyway—there is no Number of feet that can produce new Amount(3.6, { unit: "inch" }), [...]

We can avoid round-tripping errors here by never round-tripping. As in, for an Amount built from a scalar, assign that scalar to its .value and calculate the .values from it; for an Amount build from an array of scalars, assign those array values to .values, and calculate the .value from them.

My point is that if new Amount(Number(x), { unit: "foot-and-inch" }) were supported and subject to semantics in which the scalar argument is interpreted as the largest unit, then there is no value x for which the result is equivalent to new Amount(3.6, { unit: "inch" }) (because there is no binary64 Number value between 0.299999999999999988897769753748434595763683319091796875 and 0.3000000000000000444089209850062616169452667236328125 and interpreting the former as feet maps to 3.599999_999999_999644_728632_119949_907064_437866_210937_5 inches while interpreting the latter as feet maps to 3.600000_000000_000532_907051_820075_139403_343200_683593_75 inches, which are respectively strictly less and strictly greater than 3.600000_000000_000088_817841_970012_523233_890533_447265_625), disproving the claim that "every Amount could be constructed from either a single scalar, or an array of scalars".

This does mean that in some cases the equivalences of .value and .values might not be equal:

let a = new Amount(0.3, { unit: 'foot-and-inch' })
a.value // 0.3
a.values // [0, 3.5999999999999996]

let b = new Amount([0, 3.5999999999999996], { unit: 'foot-and-inch' })
b.value // 0.29999999999999993
b.values // [0, 3.5999999999999996]

If we use the more exact conversions proposed in #115, I'm pretty sure that this disparity goes away.

I'm pretty sure it doesn't; multiplication by twelve just maps the Number values that tightly bound real number 0.3 to Number values that don't tightly bound real number 3.6.

[...] and no terminating decimal string of feet that can produce new Amount(8, { unit: "inch" }).

I don't think I understand this part. Is this also about round-tripping? And is this about Number values, or decimal one? I see this:

0.6666666666666666 * 12 === 8 
0.6666666666666667 * 12 === 8

I don't remember exactly what I was going for here, but I do remember that "string" was significant to it. I think it related to the difference between new Amount("0.6666666666666666", { unit: "foot" }) and new Amount(0.6666666666666666, { unit: "foot" }), which might actually be meaningless anyway.

[sffc]

My point is that if new Amount(Number(x), { unit: "foot-and-inch" }) were supported and subject to semantics in which the scalar argument is interpreted as the largest unit, then there is no value x for which the result is equivalent to new Amount(3.6, { unit: "inch" })

Right, in the same way that there is no x such that new Amount(x, { unit: "foot" }) is exactly equal to your inch amount.

I think @eemeli's solution where, if you really care about this equality, you can build new Amount([0, 3.6], { unit: "foot-and-inch" }), seems fine.

I get your point about the tight bounds, though. It's a little unfortunate that you can have two Amounts with the same value but different values. I think it's fine, but if others want to retain a higher degree of equivalence, we can just define values to be the source of truth after construction, the thing that gets compared for equality and round-tripped through serialization.

[gibson042]

It's a little unfortunate that you can have two Amounts with the same value but different values. I think it's fine, but if others want to retain a higher degree of equivalence, we can just define values to be the source of truth after construction, the thing that gets compared for equality and round-tripped through serialization.

Or we can avoid such gymnastics by prohibiting single-scalar values with sequence units such that all conversions are explicit. new Amount([0, 3.6], { unit: "foot-and-inch" }) doesn't have a singular scalar value, so it shouldn't have a scalar-valued value. Instead, value should be either undefined or a frozen non-primitive as suggested in #118 (comment) (e.g., [0, 3.6] or { foot: 0, inch: 3.6 }).

[sffc]

I think it's not a good design if amount.value is defined sometimes but not all the time.

In Temporal, we decided to have a .year and .month on all dates, including those in lunisolar calendars and calendars with eras, for a similar reason. We researched the constraints developers expect for those fields and designed around those constraints.

[sffc]

Observation: populating .value with the value converted into the largest unit is indistinguishable from the previously proposed .total() function, except for being a getter instead of a method.