Editorial: Add NormalizeOptionsObject (tc39#480)

In order to later be able to move GetOption into ECMA-262 in sync with
Temporal, we add NormalizeOptionsObject and NormalizeOptionsObjectLegacy
as abstract operations.

NormalizeOptionsObject and GetOption are intended to be moved into
ECMA-262 at the same time, while NormalizeOptionsObjectLegacy is
intended to stay in ECMA-402. NormalizeOptionsObjectLegacy describes the
somewhat unexpected boxing behaviour when passing a primitive as the
options parameter in a formatter constructor. This behaviour may need to
be preserved for web-compatibility reasons, but new Intl objects going
forward should use the NormalizeOptionsObject behaviour.

spec/collator.html

@@ -16,10 +16,7 @@ <h1>InitializeCollator ( _collator_, _locales_, _options_ )</h1>
 
       <emu-alg>
         1. Let _requestedLocales_ be ? CanonicalizeLocaleList(_locales_).
-        1. If _options_ is *undefined*, then
-          1. Let _options_ be ObjectCreate(*null*).
-        1. Else,
-          1. Let _options_ be ? ToObject(_options_).
+        1. Set _options_ to ? NormalizeOptionsObjectLegacy(_options_).
         1. Let _usage_ be ? GetOption(_options_, *"usage"*, *"string"*, &laquo; *"sort"*, *"search"* &raquo;, *"sort"*).
         1. Set _collator_.[[Usage]] to _usage_.
         1. If _usage_ is *"sort"*, then

spec/locale.html

@@ -113,10 +113,7 @@ <h1>Intl.Locale ( _tag_ [ , _options_ ] )</h1>
           1. Let _tag_ be _tag_.[[Locale]].
         1. Else,
           1. Let _tag_ be ? ToString(_tag_).
-        1. If _options_ is *undefined*, then
-          1. Let _options_ be ! ObjectCreate(*null*).
-        1. Else,
-          1. Let _options_ be ? ToObject(_options_).
+        1. Set _options_ to ? NormalizeOptionsObjectLegacy(_options_).
         1. Set _tag_ to ? ApplyOptionsToTag(_tag_, _options_).
         1. Let _opt_ be a new Record.
         1. Let _calendar_ be ? GetOption(_options_, *"calendar"*, *"string"*, *undefined*, *undefined*).

spec/negotiation.html

@@ -293,11 +293,8 @@ <h1>SupportedLocales ( _availableLocales_, _requestedLocales_, _options_ )</h1>
       </p>
 
       <emu-alg>
-        1. If _options_ is *undefined*, then
-          1. Let _matcher_ be *"best fit"*.
-        1. Else,
-          1. Let _options_ be ? ToObject(_options_).
-          1. Let _matcher_ be ? GetOption(_options_, *"localeMatcher"*, *"string"*, &laquo; *"lookup"*, *"best fit"* &raquo;, *"best fit"*).
+        1. Set _options_ to ? NormalizeOptionsObjectLegacy(_options_).
+        1. Let _matcher_ be ? GetOption(_options_, *"localeMatcher"*, *"string"*, &laquo; *"lookup"*, *"best fit"* &raquo;, *"best fit"*).
         1. If _matcher_ is *"best fit"*, then
           1. Let _supportedLocales_ be BestFitSupportedLocales(_availableLocales_, _requestedLocales_).
         1. Else,
@@ -306,6 +303,36 @@ <h1>SupportedLocales ( _availableLocales_, _requestedLocales_, _options_ )</h1>
       </emu-alg>
     </emu-clause>
 
+    <emu-clause id="sec-normalizeoptionsobject" aoid="NormalizeOptionsObject">
+      <h1>NormalizeOptionsObject ( _options_ )</h1>
+      <p>
+        The abstract operation NormalizeOptionsObject massages _options_ into an Object to be subsequently passed to GetOption.
+        It throws a TypeError if _options_ is not undefined and not an Object.
+      </p>
+      <emu-alg>
+        1. If _options_ is *undefined*, then
+          1. Return ! ObjectCreate(*null*).
+        1. If Type(_options_) is Object, then
+          1. Return _options_.
+        1. Throw a *TypeError* exception.
+      </emu-alg>
+    </emu-clause>
+
+    <emu-clause id="sec-normalizeoptionsobjectlegacy" aoid="NormalizeOptionsObjectLegacy">
+      <h1>NormalizeOptionsObjectLegacy ( _options_ )</h1>
+      <p>
+        The abstract operation NormalizeOptionsObjectLegacy massages _options_ into an Object to be subsequently passed to GetOption.
+        It only throws an exception if _options_ is null.
+        If _options_ is a primitive, then it makes a best-effort attempt at coercing _options_ to an Object.
+        Newer spec code should use NormalizeOptionsObject instead.
+      </p>
+      <emu-alg>
+        1. If _options_ is *undefined*, then
+          1. Return ! ObjectCreate(*null*).
+        1. Return ? ToObject(_options_).
+      </emu-alg>
+    </emu-clause>
+
     <emu-clause id="sec-getoption" aoid="GetOption">
       <h1>GetOption ( _options_, _property_, _type_, _values_, _fallback_ )</h1>
 

spec/numberformat.html

@@ -57,10 +57,7 @@ <h1>InitializeNumberFormat ( _numberFormat_, _locales_, _options_ )</h1>
 
       <emu-alg>
         1. Let _requestedLocales_ be ? CanonicalizeLocaleList(_locales_).
-        1. If _options_ is *undefined*, then
-          1. Let _options_ be ObjectCreate(*null*).
-        1. Else,
-          1. Let _options_ be ? ToObject(_options_).
+        1. Set _options_ to ? NormalizeOptionsObjectLegacy(_options_).
         1. Let _opt_ be a new Record.
         1. Let _matcher_ be ? GetOption(_options_, *"localeMatcher"*, *"string"*, &laquo; *"lookup"*, *"best fit"* &raquo;, *"best fit"*).
         1. Set _opt_.[[localeMatcher]] to _matcher_.

spec/pluralrules.html

@@ -13,10 +13,7 @@ <h1>InitializePluralRules ( _pluralRules_, _locales_, _options_ )</h1>
 
       <emu-alg>
         1. Let _requestedLocales_ be ? CanonicalizeLocaleList(_locales_).
-        1. If _options_ is *undefined*, then
-          1. Let _options_ be ObjectCreate(*null*).
-        1. Else,
-          1. Let _options_ be ? ToObject(_options_).
+        1. Set _options_ to ? NormalizeOptionsObjectLegacy(_options_).
         1. Let _opt_ be a new Record.
         1. Let _matcher_ be ? GetOption(_options_, *"localeMatcher"*, *"string"*, &laquo; *"lookup"*, *"best fit"* &raquo;, *"best fit"*).
         1. Set _opt_.[[localeMatcher]] to _matcher_.

spec/relativetimeformat.html

@@ -17,10 +17,7 @@ <h1>InitializeRelativeTimeFormat ( _relativeTimeFormat_, _locales_, _options_ )<
 
       <emu-alg>
         1. Let _requestedLocales_ be ? CanonicalizeLocaleList(_locales_).
-        1. If _options_ is *undefined*, then
-          1. Let _options_ be ObjectCreate(*null*).
-        1. Else,
-          1. Let _options_ be ? ToObject(_options_).
+        1. Set _options_ to ? NormalizeOptionsObjectLegacy(_options_).
         1. Let _opt_ be a new Record.
         1. Let _matcher_ be ? GetOption(_options_, *"localeMatcher"*, *"string"*, «*"lookup"*, *"best fit"*», *"best fit"*).
         1. Set _opt_.[[LocaleMatcher]] to _matcher_.