Add GetAmountConvertToUnit definitions to both ECMA-262 and ECMA-402 by eemeli · Pull Request #110 · tc39/proposal-amount

eemeli · 2026-05-16T22:12:50Z

Fixes #109 by adding an AO to ECMA-262 that's superseded by a redefinition in ECMA-402.

~~The actual extraction of preferred units from the CLDR units.xml is left as a TODO.~~ Edit: now included.

The preferences depend on unit category, usage, region, and value thresholds. The categories we get from validity/unit.xml, the region is calculated from the first-choice locale, and the preferences themselves are in supplemental/units.xml.

As the data always includes 001 ("the world") as one of the regions for each supported category + usage combination, no locale fallback is ever done during .convertTo(), as all well-formed locales are supported.

github-actions · 2026-05-16T22:13:15Z

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-09-28 01:16 UTC

jessealama · 2026-05-18T03:15:32Z

This looks good. Thanks!

gibson042

Thanks! I have many suggestions, but this is an excellent starting point.

gibson042

I'd like to name the Records that are passed between operations, but won't insist on it being part of this PR. The rest of this review is a large handful of non-blocking suggestions.

Options should be read in alphabetical order (see #95 and review feedback on #110), and alphabetically "locale" precedes "usage".

gibson042

I think this is still slightly too far off from #95.

gibson042 · 2026-08-19T14:46:40Z

+        1. Let _requestedLocales_ be ? CanonicalizeLocaleList(_locale_).
+        1. If _requestedLocales_ is an empty List, let _resolvedLocale_ be DefaultLocale(); else let _resolvedLocale_ be the first element of _requestedLocales_.


This should use actual locale negotiation rather than just picking the first element; again, see #95.

Agree. I propose to punt that to a separate branch that tackles #95.

Nope, for conversion every entry includes a 001 region, which means that the region of a valid locale will always be supported, and that therefore we will never fall back to a second-choice locale.

This does raise the question of whether we should have a region option instead of a locale option, as the data is region-dependent rather than language-dependent.

I've tweaked things so that we use RegionPreference here, which also picks up region. In light of the fact taht every category and usage has a 001 entry, no requested locale can go unsupported, so I'm not sure I see how negotiation should go. I may be missing something. Perhaps file an issue to tackle this?

On region versus locale, I'd lean toward keeping locale. UTS 35 takes a locale as input, and it matches how Intl.Locale handles region-based data (calendars, hour cycles). That strikes me as sufficient, or do we need more here?

gibson042 · 2026-08-19T14:51:42Z

+        1. Let _unit_ be ~unset~.
+        1. For each element _entry_ of _preferredUnits_, do
+          1. Set _unit_ to _entry_.[[Unit]].
+          1. Let _convertedValue_ be ? ConvertUnitValue(_sourceValue_, _sourceUnit_, _unit_).


It's a bit awkward to specify O(n) ConvertUnitValue calls (n - 1 in SelectTargetUnit and the last in Amount.prototype.convertTo). I'm not objecting, but we should look for ways to improve that.

Agree. Would you like to file a follow-on issue to track this?

…ad of locale

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

… options

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

Rename two leftover uses of _matchingElements_ to _matchingUnits_, declare GetPreferredUnits as returning a List of Records now that it can no longer throw, drop the ? at its call site accordingly, and add the missing closing asterisk in *"001"*.

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

The String branch of `.convertTo` collapsed "-0" to the mathematical value 0 before building the Number used for the conversion, so the sign got lost.

Move every observable property read into `SetAmountOptions` that ECMA-402 redefines with the help of a new `[[ExtendedOptions]]` field. `SetAmountOptions` also validates unit syntax as soon as the unit is read.

`GetOptionsObject` moved from ECMA-402 to ECMA-262.

gibson042

LGTM after a large handful of tweaks.

gibson042 · 2026-09-24T18:28:19Z

    so `amount.convertTo("milliliter")` is the same as `amount.convertTo({ unit: "milliliter" })`.
  * `locale` (String or Array of Strings or undefined):
    The locale for which the preferred unit of the corresponding category is determined.
+    Unit preferences depend only on the region of the locale, determined as in ECMA-402's [RegionPreference](https://tc39.es/ecma402/#sec-regionpreference): (1) the `rg` Unicode extension, if present ('US' for `en-GB-u-rg-uszzzz`), (2) the locale's region subtag (`GB` for `en-GB`), and finally (3) the most likely region for the locale (`US` for `en`).


Suggested change

Unit preferences depend only on the region of the locale, determined as in ECMA-402's [RegionPreference](https://tc39.es/ecma402/#sec-regionpreference): (1) the `rg` Unicode extension, if present ('US' for `en-GB-u-rg-uszzzz`), (2) the locale's region subtag (`GB` for `en-GB`), and finally (3) the most likely region for the locale (`US` for `en`).

Unit preferences depend only on the region of the locale, determined as in ECMA-402's [RegionPreference](https://tc39.es/ecma402/#sec-regionpreference): (1) the `rg` Unicode extension if present ("US" for `en-GB-u-rg-uszzzz`), (2) the locale's region subtag if present ("CH" for `de-CH`), the most likely region for the locale if known ("BR" for `pt`), and finally "001" (the World) as an ultimate fallback.

gibson042 · 2026-09-24T18:29:20Z

+        <h1>Amount Options Record</h1>
+        <p>
+          An <dfn variants="Amount Options Records">Amount Options Record</dfn> is a Record holding the resolved values of the options
+          accepted by the Amount constructor and by <emu-xref href="#sec-amount.prototype.convertto">Amount.prototype.convertTo</emu-xref>.


Simplification:

Suggested change

accepted by the Amount constructor and by <emu-xref href="#sec-amount.prototype.convertto">Amount.prototype.convertTo</emu-xref>.

accepted by the Amount constructor and by <emu-xref href="#sec-amount.prototype.convertto" title></emu-xref>.

gibson042 · 2026-09-24T18:31:59Z

-            1. Set _roundingMode_ to ? GetOption(_opts_, *"roundingMode"*, ~string~, « *"ceil"*, *"floor"*, *"expand"*, *"trunc"*, *"halfCeil"*, *"halfFloor"*, *"halfExpand"*, *"halfTrunc"*, *"halfEven"* », *"halfEven"*).
-            1. Set _significantDigits_ to ? GetOption(_opts_, *"significantDigits"*, ~number~, ~empty~, *undefined*).
-            1. Let _unit_ be ? GetOption(_opts_, *"unit"*, ~string~, ~empty~, *undefined*).
+            1. If ParseText(_opts_, |UnitIdentifier|) is not a Parse Node, throw a *RangeError* exception.


This may change based on discussion in next week's plenary, but I at least am advocating for

Suggested change

1. If ParseText(_opts_, |UnitIdentifier|) is not a Parse Node, throw a *RangeError* exception.

1. If ParseText(_opts_, |UnitIdentifier|) is not a Parse Node, throw a *SyntaxError* exception.

gibson042 · 2026-09-24T21:02:45Z

+        <p>
+          An ECMAScript implementation that includes the ECMA-402 Internationalization API
+          must implement this abstract operation as specified in the ECMA-402 specification.
+          If an ECMAScript implementation does not include the ECMA-402 API,
+          SetAmountOptions performs the following steps when called:
+        </p>


Nit:

Suggested change



An ECMAScript implementation that includes the ECMA-402 Internationalization API

must implement this abstract operation as specified in the ECMA-402 specification.

If an ECMAScript implementation does not include the ECMA-402 API,

SetAmountOptions performs the following steps when called:





An ECMAScript implementation that includes the ECMA-402 Internationalization API

must implement this abstract operation as specified in ECMA-402.

Otherwise, SetAmountOptions performs the following steps when called:



(mirroring e.g. AvailableNamedTimeZoneIdentifiers)

gibson042 · 2026-09-24T21:14:45Z

+          SetAmountOptions (
+            _target_: an Amount Options Record,
+            _source_: an Object,
+          ): either a normal completion containing ~unused~ or a throw completion


I think we want to read "locale" and "usage" for conversion but not construction, which means that distinction should be expressed in a parameter.

Suggested change

SetAmountOptions (

_target_: an Amount Options Record,

_source_: an Object,

): either a normal completion containing ~unused~ or a throw completion

SetAmountOptions (

_target_: an Amount Options Record,

_source_: an Object,

_purpose_: ~construction~ or ~unit-conversion~,

): either a normal completion containing ~unused~ or a throw completion

gibson042 · 2026-09-24T21:28:54Z

+
+    <emu-clause id="sup-amount-options-record">
+      <h1>Amount Options Record</h1>
+      <p>In an implementation that includes the ECMA-402 Internationalization API, the [[ExtendedOptions]] field of an <emu-xref href="#sec-amount-options-record">Amount Options Record</emu-xref> that has been populated by SetAmountOptions is a Record with fields [[Locale]] (an ECMAScript language value) and [[Usage]] (a String or *undefined*).</p>


Suggested change

In an implementation that includes the ECMA-402 Internationalization API, the [[ExtendedOptions]] field of an <emu-xref href="#sec-amount-options-record">Amount Options Record</emu-xref> that has been populated by SetAmountOptions is a Record with fields [[Locale]] (an ECMAScript language value) and [[Usage]] (a String or *undefined*).

In an implementation that includes the ECMA-402 Internationalization API, the [[ExtendedOptions]] field of an <emu-xref href="#sec-amount-options-record">Amount Options Record</emu-xref> that has been populated by SetAmountOptions is a Record with fields [[Locales]] (a Language Priority List or *undefined*) and [[Usage]] (a String or *undefined*).

gibson042 · 2026-09-24T21:35:42Z

+        1. Let _locale_ be _extendedOpts_.[[Locale]].
+        1. Let _usage_ be _extendedOpts_.[[Usage]].
+        1. If _unit_ is not *undefined*, then
+          1. If _usage_ is not *undefined* or _locale_ is not *undefined*, throw a *TypeError* exception.
+          1. Return _unit_.
+        1. If _usage_ is *undefined*, then
+          1. If _locale_ is *undefined*, throw a *TypeError* exception.
+          1. Set _usage_ to *"default"*.
+        1. Let _sourceUnit_ be _conversionSource_.[[Unit]].
+        1. Let _sourceValue_ be GetAmountNumericValue(_conversionSource_).
+        1. Let _category_ be ? GetUnitCategory(_sourceUnit_).
+        1. Let _requestedLocales_ be ? CanonicalizeLocaleList(_locale_).
+        1. If _requestedLocales_ is an empty List, let _resolvedLocale_ be DefaultLocale(); else let _resolvedLocale_ be the first element of _requestedLocales_.


Suggested change

1. Let _locale_ be _extendedOpts_.[[Locale]].

1. Let _usage_ be _extendedOpts_.[[Usage]].

1. If _unit_ is not *undefined*, then

1. If _usage_ is not *undefined* or _locale_ is not *undefined*, throw a *TypeError* exception.

1. Return _unit_.

1. If _usage_ is *undefined*, then

1. If _locale_ is *undefined*, throw a *TypeError* exception.

1. Set _usage_ to *"default"*.

1. Let _sourceUnit_ be _conversionSource_.[[Unit]].

1. Let _sourceValue_ be GetAmountNumericValue(_conversionSource_).

1. Let _category_ be ? GetUnitCategory(_sourceUnit_).

1. Let _requestedLocales_ be ? CanonicalizeLocaleList(_locale_).

1. If _requestedLocales_ is an empty List, let _resolvedLocale_ be DefaultLocale(); else let _resolvedLocale_ be the first element of _requestedLocales_.

1. Let _requestedLocales_ be _extendedOpts_.[[Locales]].

1. Let _usage_ be _extendedOpts_.[[Usage]].

1. If _unit_ is not *undefined*, then

1. If _usage_ is not *undefined* or _requestedLocales_ is not *undefined*, throw a *TypeError* exception.

1. Return _unit_.

1. If _usage_ is *undefined*, then

1. If _requestedLocales_ is *undefined*, throw a *TypeError* exception.

1. Set _usage_ to *"default"*.

1. Let _sourceUnit_ be _conversionSource_.[[Unit]].

1. Let _sourceValue_ be GetAmountNumericValue(_conversionSource_).

1. Let _category_ be ? GetUnitCategory(_sourceUnit_).

1. If _requestedLocales_ is an empty List, let _resolvedLocale_ be DefaultLocale(); else let _resolvedLocale_ be the first element of _requestedLocales_.

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

Ref tc39#110 (comment)

…d in ECMA-402 Ref tc39#110 (comment) Ref tc39#110 (comment)

* Meta: Mention "001" as the ultimate region fallback * Editorial: Simplify internal references * Editorial: Use conventional prose for describing operations superseded in ECMA-402

eemeli force-pushed the convert-options branch from 46f7cdf to 3c8bebf Compare May 17, 2026 19:45

eemeli requested a review from jessealama May 17, 2026 19:50

jessealama approved these changes May 18, 2026

View reviewed changes

Comment thread spec.emu Outdated

eemeli commented May 18, 2026

View reviewed changes

Comment thread spec.emu

gibson042 suggested changes May 18, 2026

View reviewed changes

eemeli requested a review from gibson042 May 18, 2026 15:16

gibson042 approved these changes May 18, 2026

View reviewed changes

Comment thread spec.emu Outdated

Comment thread spec.emu Outdated

Comment thread spec.emu Outdated

Comment thread spec.emu Outdated

Comment thread intl.emu

Comment thread intl.emu Outdated

Comment thread intl.emu

jessealama force-pushed the convert-options branch 3 times, most recently from fd51602 to 964a6d1 Compare August 19, 2026 08:31

jessealama added a commit that referenced this pull request Aug 19, 2026

Read the locale option before the usage option

29fbabd

Options should be read in alphabetical order (see #95 and review feedback on #110), and alphabetically "locale" precedes "usage".

jessealama mentioned this pull request Aug 19, 2026

GetPreferredUnits asserts constraints on its region argument instead of expressing them in the parameter type #151

Open

jessealama requested a review from gibson042 August 19, 2026 12:14

gibson042 suggested changes Aug 19, 2026

View reviewed changes

eemeli and others added 14 commits August 27, 2026 17:05

Add GetAmountConvertToUnit definitions to both ECMA-262 and ECMA-402

60542f2

Include sourceUnit & region in GetPreferredAmountUnit arguments inste…

39944ef

…ad of locale

We also need sourceValue for some preferences

82f03d1

Add full implementation, with data from CLDR

dec71db

Apply suggestions from code review

151af0c

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

Call GetAmountOptions from GetAmountConvertToOptions to handle common…

e6a55c1

… options

Add usage fallbacking

f76cd07

Include editorial note with TODO for region containment fallbacking

7ee3539

Update intl.emu

51cb855

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

Update intl.emu

45c96b1

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

Rename GetAmountConvertToUnit to SelectTargetUnit

e830c03

Check the source unit category before reading conversion options

d237a5a

GetAmountoptions: Broaden description (no just construction)

17026a8

jessealama and others added 6 commits September 7, 2026 09:25

Update spec.emu

5be2a52

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

Preserve negative zero when converting a String-valued Amount

65f56ab

The String branch of `.convertTo` collapsed "-0" to the mathematical value 0 before building the Number used for the conversion, so the sign got lost.

Consolidate option reads into SetAmountOptions

102da2e

Move every observable property read into `SetAmountOptions` that ECMA-402 redefines with the help of a new `[[ExtendedOptions]]` field. `SetAmountOptions` also validates unit syntax as soon as the unit is read.

Use RegionPreference to get a region

9252fdc

Mention how we compute unit preferences

e0a5a03

Bump 402 biblio

1dce668

jessealama requested a review from gibson042 September 7, 2026 08:55

eemeli commented Sep 7, 2026

View reviewed changes

Comment thread README.md Outdated

jessealama added 3 commits September 7, 2026 13:49

Briefly specify how we extract region from a locale

3aeace7

Bump 262 biblio and sync package-lock.json

450e445

`GetOptionsObject` moved from ECMA-402 to ECMA-262.

Remove .npmrc, which was disablin package-lock.json updates

c9c4a4e

jessealama mentioned this pull request Sep 10, 2026

Specify sequence units #161

Draft

jessealama added this pull request to stack #162 September 10, 2026 15:03

This was referenced Sep 22, 2026

Round Amount values directly instead of through an Intl formatter #164

Open

Share RenderInExponentialNotation AO with Number.prototype.toExponential #165

Open

Render Number-backed Amounts using Number.p.toExponential #166

Open

gibson042 approved these changes Sep 24, 2026

View reviewed changes

jessealama and others added 4 commits September 28, 2026 03:09

Update intl.emu

4ee727a

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

Update intl.emu

2b56f9e

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

Update spec.emu

f09f71c

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

Use the renamed GetAmountNumberValue at its call sites

bf6bec2

jessealama merged commit cd03999 into main Sep 28, 2026
3 checks passed

jessealama deleted the convert-options branch September 28, 2026 01:16

gibson042 added a commit to gibson042/proposal-amount that referenced this pull request Sep 28, 2026

Meta: Mention "001" as the ultimate region fallback

55a7b4b

Ref tc39#110 (comment)

gibson042 added a commit to gibson042/proposal-amount that referenced this pull request Sep 28, 2026

Editorial: Simplify internal references

8079ef3

Ref tc39#110 (comment)

gibson042 added a commit to gibson042/proposal-amount that referenced this pull request Sep 28, 2026

Editorial: Use conventional prose for describing operations supersede…

cfc8055

…d in ECMA-402 Ref tc39#110 (comment) Ref tc39#110 (comment)

This was referenced Sep 28, 2026

Add editorial changes suggested in the review of #110 #169

Merged

Normative: Read "locale" and "usage" for unit conversion but not construction #170

Open

Normative: Throw SyntaxError rather than RangeError for an ill-formed unit identifier #171

Open

		1. Let _requestedLocales_ be ? CanonicalizeLocaleList(_locale_).
		1. If _requestedLocales_ is an empty List, let _resolvedLocale_ be DefaultLocale(); else let _resolvedLocale_ be the first element of _requestedLocales_.

	accepted by the Amount constructor and by <emu-xref href="#sec-amount.prototype.convertto">Amount.prototype.convertTo</emu-xref>.
	accepted by the Amount constructor and by <emu-xref href="#sec-amount.prototype.convertto" title></emu-xref>.

	1. If ParseText(_opts_, \|UnitIdentifier\|) is not a Parse Node, throw a RangeError exception.
	1. If ParseText(_opts_, \|UnitIdentifier\|) is not a Parse Node, throw a SyntaxError exception.

	<p>In an implementation that includes the ECMA-402 Internationalization API, the [[ExtendedOptions]] field of an <emu-xref href="#sec-amount-options-record">Amount Options Record</emu-xref> that has been populated by SetAmountOptions is a Record with fields [[Locale]] (an ECMAScript language value) and [[Usage]] (a String or undefined).</p>
	<p>In an implementation that includes the ECMA-402 Internationalization API, the [[ExtendedOptions]] field of an <emu-xref href="#sec-amount-options-record">Amount Options Record</emu-xref> that has been populated by SetAmountOptions is a Record with fields [[Locales]] (a Language Priority List or undefined) and [[Usage]] (a String or undefined).</p>

Conversation

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

Uh oh!

Uh oh!

github-actions Bot commented May 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jessealama commented May 18, 2026

Uh oh!

Uh oh!

Uh oh!

gibson042 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gibson042 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gibson042 left a comment

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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gibson042 left a comment

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!

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!

eemeli commented May 16, 2026 •

edited

Loading

github-actions Bot commented May 16, 2026 •

edited

Loading