Update spec text by jessealama · Pull Request #84 · tc39/proposal-amount

jessealama · 2026-02-24T10:07:50Z

The [[Value]] internal slot now stores the original JavaScript value type (a disjunction of Number, BigInt, or String) rather than always a mathematical value. When precision options are applied or unit conversion is performed, the value is stored as a decimal digit string. The [[FractionDigits]] internal slot has been removed. The .fractionDigits, .significantDigits, and .with() are removed; a .value accessor is added that returns [[Value]] directly. We also now refer to CLDR's units data.

There's a a new Amount.prototype.convertTo() for unit conversion. 402 overrides this to add support for locale- and usage-based conversion via CLDR's unit preferences.

New AOs:

GetUnitConversionFactor: Returns the CLDR-derived scalar factor and offset for converting a unit to its category's base unit
ConvertUnitValue: Converts a Number value between two units via their shared base unit, using Number arithmetic
GetConvertToDigitOptions: Reads Intl.NumberFormat-style digit options from an options bag
ApplyDigitOptions: Rounds a Number per digit options and returns a String
ResolveUnitPreference: Resolves a target unit from locale and usage via CLDR unit preferences (402-only)

ApplyDigitOptions is essentially just 402's FormatNumericToString without referrring to some internal slots in Intl.NF.

github-actions · 2026-02-24T10:08:14Z

PR Preview Action v1.8.1
🚀 View preview at https://tc39.github.io/proposal-amount/pr-preview/pr-84/
Built to branch `gh-pages` at 2026-02-26 06:36 UTC. Preview will be ready when the GitHub Pages deployment is complete.

gibson042

ApplyDigitOptions is essentially just 402's FormatNumericToString without referrring to some internal slots in Intl.NF.

Does that mean that FormatNumericToString can be simplified to leverage ApplyDigitOptions?

spec.emu

gibson042 · 2026-02-24T20:05:22Z

spec.emu

+      <emu-clause id="sec-amount-getunitconversionfactor" type="abstract operation">
+        <h1>GetUnitConversionFactor (
+          _unit_: a String
+        ): either a normal completion containing a Record with fields [[Category]] (a String), [[Factor]] (a Number), and [[Offset]] (a Number) or a throw completion
+        </h1>
+        <dl class="header">
+          <dt>description</dt>
+          <dd>It returns the conversion data for converting _unit_ to its base unit within its unit category.</dd>
+        </dl>
+        <emu-alg>
+          1. If _unit_ is not recognized as a unit for which conversion data is available, throw a *RangeError* exception.
+          1. Return an implementation-defined Record { [[Category]], [[Factor]], [[Offset]] } where [[Category]] is a String identifying the unit category of _unit_ (e.g., *"length"*, *"mass"*, *"temperature"*), [[Factor]] is a Number representing the multiplication factor for converting from _unit_ to the base unit of its category, and [[Offset]] is a Number representing the additive offset for converting from _unit_ to the base unit (*+0*<sub>𝔽</sub> for most units; non-zero for temperature units such as *"fahrenheit"*).
+        </emu-alg>
+        <emu-note>
+          <p>Implementations should provide conversion data consistent with the Unicode Common Locale Data Repository (CLDR) <code>units.xml</code> supplemental data. The formula for converting a value in _unit_ to its base unit is: <i>baseValue</i> = <i>value</i> × [[Factor]] + [[Offset]].</p>
+          <p>CLDR expresses conversion factors as rational numbers (e.g., 0.3048/12 for inch-to-meter). These rational values are converted to Numbers before use, so conversion arithmetic is subject to the precision of IEEE 754 binary64. For example, converting 1.75 feet to inches yields 1.75 × 0.3048 / (0.3048 / 12) = 20.999999999999996, not exactly 21.</p>
+        </emu-note>
+      </emu-clause>


I was expecting a normative reference to CLDR file units.xml, not a suggestion that allows for arbitrary implementation divergence. This description isn't even appropriate for type="abstract operation"; it would need type="implementation-defined abstract operation".

I saw the implementation-defined abstract operation suggestions, thanks! This is my honest best guess for how to normatively refer to CLDR. At a minimum, I suppose we ought to add CDLR to the Bibliography. But as for the verbiage for normatively referring, I didn't quite know what to say except this. Any advice is welcome.

The spec enumerates Normative References, and sample use thereof can be seen in e.g. AvailableNamedTimeZoneIdentifiers.

spec.emu

intl.emu

gibson042 · 2026-02-24T20:53:33Z

intl.emu

+        1. Let _region_ be the region subtag of the result of applying the <emu-xref href="#sec-canonicalizelocalelist">CanonicalizeLocaleList</emu-xref> algorithm to _locale_, or the likely region if no region subtag is present.
+        1. Let _preferredUnit_ be the implementation-defined preferred unit for _category_, _region_, and _usage_ based on CLDR unit preferences data.


Please be less handwavy.

I wasn't quite sure what else to write here; the handwaviness isn't intentional. I guess one step forward would be to say what types of values these are (String, of course), but I'm open to suggestions.

For starters, CanonicalizeLocaleList doesn't make sense if we already have a single string, although I think we probably do want to support amount.convertTo({ locale: ["zh-hant", "zh-hans"] }) just like number.toLocaleString(["zh-hant", "zh-hans"]), and presumably also Unicode extension subtags "ms" (Measurement system) and "mu" (Measurement unit override). I think we'll want to go through ResolveLocale, possibly via ResolveOptions, and in either case that means this algorithm must provide available locales and their corresponding data.

That sounds great. I had a multi-locale approach in mind, but the issue with measurement systems and overrides is a bit new to me and I'm hesitant to unilaterally add spec text; I'd like to discuss this in the JS numerics call first. I agree that we'll want to go through ResolveLocale/ResolveOptions, but I wonder what kind of extension to 402 we're talking about here. cc @ben-allen

We now resolve locales in the established string-or-array-of-strings way, but for now I'm punting on the issue of resolving things like measurement systems and unit overrides.

gibson042 · 2026-02-24T20:58:58Z

intl.emu

      </dl>
      <emu-alg>
-        1. <ins>If _value_ has the [[Value]] and [[FractionDigits]] internal slots, let _primValue_ be RenderAmountValueWithFractionDigits(_value_.[[Value]], _value_.[[FractionDigits]]) else</ins><del>Let</del> <ins>let</ins _primValue_ be ? ToPrimitive(_value_, ~number~).
+        1. <ins>If _value_ has the [[Value]] internal slot, let _primValue_ be _value_.[[Value]]; else</ins> <del>Let</del> <ins>let</ins> _primValue_ be ? ToPrimitive(_value_, ~number~).


This is dangerous; even if there's not currently any userspace-exposed object with a [[Value]] slot other than an Amount instance, that could change at any time. The spec needs a better means of brand-checking than this.

eemeli

Sorry, I'm not finding time atm to do a complete review, so submitting just a few comments for now.

Beyond the currently-changed lines, we should leave RS: StringIntlMV as a TODO, given how it's building on top of keep-trailing-zeros, and the implementation that's here is already known to be missing details like the accurate handling of inputs with negative exponents.

spec.emu

Co-authored-by: Richard Gibson <richard.gibson@gmail.com>

jessealama · 2026-02-25T14:12:27Z

ApplyDigitOptions is essentially just 402's FormatNumericToString without referrring to some internal slots in Intl.NF.

Does that mean that FormatNumericToString can be simplified to leverage ApplyDigitOptions?

Yeah that sounds good; that's what I was trying to hint at. I suppose one way to proceed would be to (1) do the refactoring in 402, then (2) copy-and-paste that newly refactored AO (ApplyDigitOptions) here, with a comment about its origins in 402, then, if/once this propo (3) remove ApplyDigitOptions from 402, since it would exist in 262?

Prevent any kind of mixing of Amounts with other values, e.g., via mathematical operators.

sffc

Mostly good; I don't like taking Intl.NF digit options spec and putting it in 262 but I guess that what we need to do in some form if we are going to be using those same options in Amount. We should discuss that further. But it doesn't block stage 2.

intl.emu

sffc · 2026-02-26T09:22:40Z

spec.emu

+        </dl>
+        <emu-alg>
+          1. If _unit_ is not recognized as a unit for which conversion data is available, throw a *RangeError* exception.
+          1. Return an implementation-defined Record { [[Category]], [[Factor]], [[Offset]] } where [[Category]] is a String identifying the unit category of _unit_ (e.g., *"length"*, *"mass"*, *"temperature"*), [[Factor]] is a Number representing the multiplication factor for converting from _unit_ to the base unit of its category, and [[Offset]] is a Number representing the additive offset for converting from _unit_ to the base unit (*+0*<sub>𝔽</sub> for most units; non-zero for temperature units such as *"fahrenheit"*).


Note: there are also nonlinear conversions such as the Richter scale and Beaufort scale.

How should we handle these cases? One approach would be to have a converters that specify how to go to and from units (I'm thinking of a Record that would have toUnit and fromUnit keys whose values are mathematical functions). This would be inching us towards a "symbolic" approach with rational numbers that we discussed earlier.

Richter isn't supported by Intl.NumberFormat or CLDR, and while Beaufort is supported by CLDR/ICU, it's not supported by Intl.NumberFormat. It's also the only entry with a special rule.

I don't think we should initially aim to support special conversions.

sffc · 2026-02-26T09:24:54Z

spec.emu

+          1. Return an implementation-defined Record { [[Category]], [[Factor]], [[Offset]] } where [[Category]] is a String identifying the unit category of _unit_ (e.g., *"length"*, *"mass"*, *"temperature"*), [[Factor]] is a Number representing the multiplication factor for converting from _unit_ to the base unit of its category, and [[Offset]] is a Number representing the additive offset for converting from _unit_ to the base unit (*+0*<sub>𝔽</sub> for most units; non-zero for temperature units such as *"fahrenheit"*).
+        </emu-alg>
+        <emu-note>
+          <p>Implementations should provide conversion data consistent with the Unicode Common Locale Data Repository (CLDR) <code>units.xml</code> supplemental data. The formula for converting a value in _unit_ to its base unit is: <i>baseValue</i> = <i>value</i> × [[Factor]] + [[Offset]].</p>


Do we want to actually normatively reference units.xml? What benefit do we get from that versus some other independent researcher's data that conforms to the same contract?

I was also a bit uncomfortable referencing units.xml. The only alternative I can see is to hardcode (some of) the data into 262.

I think we do want to normatively refer to units.xml. See #80 (comment) to prior art for such Unicode references.

Do we want to actually normatively reference units.xml? What benefit do we get from that versus some other independent researcher's data that conforms to the same contract?

An objective artifact against which nonconformance can be definitively identified. There is no research to be done regarding e.g. the ratio between meters and feet.

sffc · 2026-02-26T09:26:48Z

spec.emu

+      </emu-clause>
+
+      <emu-clause id="sec-amount-getconverttodigitoptions" type="abstract operation">
+        <h1>GetConvertToDigitOptions (


Thought: I'm not happy with GetNumberFormatDigitOptions spec text bleeding into other parts of the spec. This AO is not one to be proud of.

I've gone a step further and removed those AOs entirely. It seems to me that the min/max digit stuff is a display concern that probably belongs in Intl.NumberFormat or a 402-specific override of .convertTo. I've tweaked things so that both the 262 and 402 .convertTo now use the same approach to precision as the constructor (the fractionDigits, significantDigits, and rounding options).

wdyt @eemeli ? Where should the min/max fraction/significant digit stuff go? I feel this conflicts with what you sketched in #80 . Maybe I'm misunderstanding something.

Min/max fraction/significant digit handling during conversion should end up in 262, as explicit-unit conversion is ending up in 262, and the rounding issues that are addressed by those options and the default behaviour around them are not 402 problems.

spec.emu

Co-authored-by: Richard Gibson <richard.gibson@gmail.com>

Delete GetConvertToDigitOptions and ApplyDigitOptions; both convertTo variants now use GetAmountOptions (fractionDigits/significantDigits/roundingMode).

Co-authored-by: Richard Gibson <richard.gibson@gmail.com>

spec.emu

Co-authored-by: Eemeli Aro <eemeli@mozilla.com>

jessealama added 3 commits February 24, 2026 10:29

Refactor spec text: new value model, remove .with(), add .convertTo()

9003f80

Update 402: toLocaleString, convertTo with locale/usage

e5e960b

Add note about CLDR rational conversion factors and Number precision

bb0c92d

jessealama marked this pull request as ready for review February 24, 2026 10:18

Note that ApplyDigitOptions is adapted from 402's FormatNumericToString

09a42b8

jessealama requested review from ben-allen and eemeli February 24, 2026 10:40

gibson042 suggested changes Feb 24, 2026

View reviewed changes

eemeli reviewed Feb 25, 2026

View reviewed changes

spec.emu Outdated Show resolved Hide resolved

jessealama and others added 4 commits February 25, 2026 15:03

Update intl.emu

edba2c6

Co-authored-by: Richard Gibson <richard.gibson@gmail.com>

Update spec.emu

71d99e4

Co-authored-by: Richard Gibson <richard.gibson@gmail.com>

Update spec.emu

712227c

Co-authored-by: Richard Gibson <richard.gibson@gmail.com>

Update spec.emu

0165382

Co-authored-by: Richard Gibson <richard.gibson@gmail.com>

jessealama added 5 commits February 25, 2026 15:40

Remove Amount.prototype[Symbol.toPrimitive]

7b240b9

Make Symbol.toPrimitive always throw TypeError

72eabc5

Prevent any kind of mixing of Amounts with other values, e.g., via mathematical operators.

Say 'integral Number' instead of 'integral number'

2220cbf

Use CopyDataProperties in toLocaleString

f955c79

Fix locale handling in ResolveUnitPreference

f83d429

jessealama force-pushed the update-spec-text branch from 82da3e7 to f83d429 Compare February 26, 2026 08:57

Remove Symbol.toPrimive

a4dddcf

sffc reviewed Feb 26, 2026

View reviewed changes

jessealama and others added 7 commits February 26, 2026 10:42

Cite CLDR

8ce04ad

Normatively reference CLDR for unit conversion and preferences

760fabb

Remove changes to ToIntlMathematicalValue

e4c87d2

Query for a locale matcher option

1789d23

Pass source value to ResolveUnitPreference

3e2ad60

Apply suggestion from @gibson042

84321b8

Co-authored-by: Richard Gibson <richard.gibson@gmail.com>

Simplify convertTo to use constructor's precision model

2845782

Delete GetConvertToDigitOptions and ApplyDigitOptions; both convertTo variants now use GetAmountOptions (fractionDigits/significantDigits/roundingMode).

jessealama and others added 2 commits February 26, 2026 14:32

Apply suggestion from @gibson042

ec53adf

Co-authored-by: Richard Gibson <richard.gibson@gmail.com>

whitespace

7f5945c

eemeli reviewed Feb 27, 2026

View reviewed changes

spec.emu Outdated Show resolved Hide resolved

Apply suggestion from @eemeli

fe0793a

Co-authored-by: Eemeli Aro <eemeli@mozilla.com>

		1. Let _region_ be the region subtag of the result of applying the <emu-xref href="#sec-canonicalizelocalelist">CanonicalizeLocaleList</emu-xref> algorithm to _locale_, or the likely region if no region subtag is present.
		1. Let _preferredUnit_ be the implementation-defined preferred unit for _category_, _region_, and _usage_ based on CLDR unit preferences data.

Conversation

jessealama commented Feb 24, 2026

Uh oh!

github-actions bot commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Built to branch gh-pages at 2026-02-26 06:36 UTC. Preview will be ready when the GitHub Pages deployment is complete.

Uh oh!

gibson042 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eemeli left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jessealama commented Feb 25, 2026

Uh oh!

sffc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jessealama Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eemeli Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

github-actions bot commented Feb 24, 2026 •

edited

Loading

Built to branch `gh-pages` at 2026-02-26 06:36 UTC.
Preview will be ready when the GitHub Pages deployment is complete.

jessealama Feb 26, 2026 •

edited

Loading

eemeli Feb 26, 2026 •

edited

Loading