Add Intl.Locale parameter type to toLocale[X]String signatures. (microsoft#47811)

* add Intl.Locale param type to locales argument in BigInt, Number, and Date methods

* update baselines

* add test for locales object arguments

* fix indentation

Author: jihndai

src/compiler/commandLineParser.ts

@@ -68,11 +68,13 @@ namespace ts {
         ["es2019.string", "lib.es2019.string.d.ts"],
         ["es2019.symbol", "lib.es2019.symbol.d.ts"],
         ["es2020.bigint", "lib.es2020.bigint.d.ts"],
+        ["es2020.date", "lib.es2020.date.d.ts"],
         ["es2020.promise", "lib.es2020.promise.d.ts"],
         ["es2020.sharedmemory", "lib.es2020.sharedmemory.d.ts"],
         ["es2020.string", "lib.es2020.string.d.ts"],
         ["es2020.symbol.wellknown", "lib.es2020.symbol.wellknown.d.ts"],
         ["es2020.intl", "lib.es2020.intl.d.ts"],
+        ["es2020.number", "lib.es2020.number.d.ts"],
         ["es2021.promise", "lib.es2021.promise.d.ts"],
         ["es2021.string", "lib.es2021.string.d.ts"],
         ["es2021.weakref", "lib.es2021.weakref.d.ts"],

src/lib/es2020.bigint.d.ts

@@ -1,3 +1,5 @@
+/// <reference lib="es2020.intl" />
+
 interface BigIntToLocaleStringOptions {
     /**
      * The locale matching algorithm to use.The default is "best fit". For information about this option, see the {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_negotiation Intl page}.
@@ -92,7 +94,7 @@ interface BigInt {
     toString(radix?: number): string;
 
     /** Returns a string representation appropriate to the host environment's current locale. */
-    toLocaleString(locales?: string, options?: BigIntToLocaleStringOptions): string;
+    toLocaleString(locales?: Intl.LocalesArgument, options?: BigIntToLocaleStringOptions): string;
 
     /** Returns the primitive value of the specified object. */
     valueOf(): bigint;

src/lib/es2020.d.ts

@@ -1,5 +1,7 @@
 /// <reference lib="es2019" />
 /// <reference lib="es2020.bigint" />
+/// <reference lib="es2020.date" />
+/// <reference lib="es2020.number" />
 /// <reference lib="es2020.promise" />
 /// <reference lib="es2020.sharedmemory" />
 /// <reference lib="es2020.string" />

src/lib/es2020.date.d.ts

@@ -0,0 +1,24 @@
+/// <reference lib="es2020.intl" />
+
+interface Date {
+    /**
+     * Converts a date and time to a string by using the current or specified locale.
+     * @param locales A locale string, array of locale strings, Intl.Locale object, or array of Intl.Locale objects that contain one or more language or locale tags. If you include more than one locale string, list them in descending order of priority so that the first entry is the preferred locale. If you omit this parameter, the default locale of the JavaScript runtime is used.
+     * @param options An object that contains one or more properties that specify comparison options.
+     */
+    toLocaleString(locales?: Intl.LocalesArgument, options?: Intl.DateTimeFormatOptions): string;
+
+    /**
+     * Converts a date to a string by using the current or specified locale.
+     * @param locales A locale string, array of locale strings, Intl.Locale object, or array of Intl.Locale objects that contain one or more language or locale tags. If you include more than one locale string, list them in descending order of priority so that the first entry is the preferred locale. If you omit this parameter, the default locale of the JavaScript runtime is used.
+     * @param options An object that contains one or more properties that specify comparison options.
+     */
+    toLocaleDateString(locales?: Intl.LocalesArgument, options?: Intl.DateTimeFormatOptions): string;
+
+    /**
+     * Converts a time to a string by using the current or specified locale.
+     * @param locales A locale string, array of locale strings, Intl.Locale object, or array of Intl.Locale objects that contain one or more language or locale tags. If you include more than one locale string, list them in descending order of priority so that the first entry is the preferred locale. If you omit this parameter, the default locale of the JavaScript runtime is used.
+     * @param options An object that contains one or more properties that specify comparison options.
+     */
+    toLocaleTimeString(locales?: Intl.LocalesArgument, options?: Intl.DateTimeFormatOptions): string;
+}

src/lib/es2020.intl.d.ts

@@ -58,6 +58,13 @@ declare namespace Intl {
      */
     type BCP47LanguageTag = string;
 
+    /**
+     * The locale(s) to use
+     *
+     * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument).
+     */
+    type LocalesArgument = UnicodeBCP47LocaleIdentifier | UnicodeBCP47LocaleIdentifier[] | Locale | Locale[] | undefined;
+
     /**
      * An object with some or all of properties of `options` parameter
      * of `Intl.RelativeTimeFormat` constructor.

src/lib/es2020.number.d.ts

@@ -0,0 +1,10 @@
+/// <reference lib="es2020.intl" />
+
+interface Number {
+    /**
+     * Converts a number to a string by using the current or specified locale.
+     * @param locales A locale string, array of locale strings, Intl.Locale object, or array of Intl.Locale objects that contain one or more language or locale tags. If you include more than one locale string, list them in descending order of priority so that the first entry is the preferred locale. If you omit this parameter, the default locale of the JavaScript runtime is used.
+     * @param options An object that contains one or more properties that specify comparison options.
+     */
+    toLocaleString(locales?: Intl.LocalesArgument, options?: Intl.NumberFormatOptions): string;
+}

src/lib/libs.json

@@ -44,11 +44,13 @@
         "es2019.string",
         "es2019.symbol",
         "es2020.bigint",
+        "es2020.date",
         "es2020.promise",
         "es2020.sharedmemory",
         "es2020.string",
         "es2020.symbol.wellknown",
         "es2020.intl",
+        "es2020.number",
         "es2021.string",
         "es2021.promise",
         "es2021.weakref",

tests/baselines/reference/bigintWithLib.types

@@ -66,26 +66,26 @@ stringVal = bigintVal.toLocaleString();
 >stringVal = bigintVal.toLocaleString() : string
 >stringVal : string
 >bigintVal.toLocaleString() : string
->bigintVal.toLocaleString : (locales?: string, options?: BigIntToLocaleStringOptions) => string
+>bigintVal.toLocaleString : (locales?: Intl.LocalesArgument, options?: BigIntToLocaleStringOptions) => string
 >bigintVal : bigint
->toLocaleString : (locales?: string, options?: BigIntToLocaleStringOptions) => string
+>toLocaleString : (locales?: Intl.LocalesArgument, options?: BigIntToLocaleStringOptions) => string
 
 stringVal = bigintVal.toLocaleString('de-DE');
 >stringVal = bigintVal.toLocaleString('de-DE') : string
 >stringVal : string
 >bigintVal.toLocaleString('de-DE') : string
->bigintVal.toLocaleString : (locales?: string, options?: BigIntToLocaleStringOptions) => string
+>bigintVal.toLocaleString : (locales?: Intl.LocalesArgument, options?: BigIntToLocaleStringOptions) => string
 >bigintVal : bigint
->toLocaleString : (locales?: string, options?: BigIntToLocaleStringOptions) => string
+>toLocaleString : (locales?: Intl.LocalesArgument, options?: BigIntToLocaleStringOptions) => string
 >'de-DE' : "de-DE"
 
 stringVal = bigintVal.toLocaleString('de-DE', { style: 'currency' });
 >stringVal = bigintVal.toLocaleString('de-DE', { style: 'currency' }) : string
 >stringVal : string
 >bigintVal.toLocaleString('de-DE', { style: 'currency' }) : string
->bigintVal.toLocaleString : (locales?: string, options?: BigIntToLocaleStringOptions) => string
+>bigintVal.toLocaleString : (locales?: Intl.LocalesArgument, options?: BigIntToLocaleStringOptions) => string
 >bigintVal : bigint
->toLocaleString : (locales?: string, options?: BigIntToLocaleStringOptions) => string
+>toLocaleString : (locales?: Intl.LocalesArgument, options?: BigIntToLocaleStringOptions) => string
 >'de-DE' : "de-DE"
 >{ style: 'currency' } : { style: string; }
 >style : string
@@ -95,9 +95,9 @@ stringVal = bigintVal.toLocaleString('de-DE', { style: 'currency', currency: 'EU
 >stringVal = bigintVal.toLocaleString('de-DE', { style: 'currency', currency: 'EUR' }) : string
 >stringVal : string
 >bigintVal.toLocaleString('de-DE', { style: 'currency', currency: 'EUR' }) : string
->bigintVal.toLocaleString : (locales?: string, options?: BigIntToLocaleStringOptions) => string
+>bigintVal.toLocaleString : (locales?: Intl.LocalesArgument, options?: BigIntToLocaleStringOptions) => string
 >bigintVal : bigint
->toLocaleString : (locales?: string, options?: BigIntToLocaleStringOptions) => string
+>toLocaleString : (locales?: Intl.LocalesArgument, options?: BigIntToLocaleStringOptions) => string
 >'de-DE' : "de-DE"
 >{ style: 'currency', currency: 'EUR' } : { style: string; currency: string; }
 >style : string

tests/baselines/reference/es2020IntlAPIs.symbols

@@ -5,7 +5,7 @@ const count = 26254.39;
 
 const date = new Date("2012-05-24");
 >date : Symbol(date, Decl(es2020IntlAPIs.ts, 2, 5))
->Date : Symbol(Date, Decl(lib.es5.d.ts, --, --), Decl(lib.es5.d.ts, --, --), Decl(lib.es5.d.ts, --, --), Decl(lib.scripthost.d.ts, --, --), Decl(lib.es2015.symbol.wellknown.d.ts, --, --))
+>Date : Symbol(Date, Decl(lib.es5.d.ts, --, --), Decl(lib.es5.d.ts, --, --), Decl(lib.es5.d.ts, --, --), Decl(lib.scripthost.d.ts, --, --), Decl(lib.es2015.symbol.wellknown.d.ts, --, --) ... and 1 more)
 
 function log(locale: string) {
 >log : Symbol(log, Decl(es2020IntlAPIs.ts, 2, 36))

tests/baselines/reference/localesObjectArgument.js

@@ -0,0 +1,40 @@
+//// [localesObjectArgument.ts]
+const enUS = new Intl.Locale("en-US");
+const deDE = new Intl.Locale("de-DE");
+const jaJP = new Intl.Locale("ja-JP");
+
+const now = new Date();
+const num = 1000;
+const bigint = 123456789123456789n;
+
+now.toLocaleString(enUS);
+now.toLocaleDateString(enUS);
+now.toLocaleTimeString(enUS);
+now.toLocaleString([deDE, jaJP]);
+now.toLocaleDateString([deDE, jaJP]);
+now.toLocaleTimeString([deDE, jaJP]);
+
+num.toLocaleString(enUS);
+num.toLocaleString([deDE, jaJP]);
+
+bigint.toLocaleString(enUS);
+bigint.toLocaleString([deDE, jaJP]);
+
+
+//// [localesObjectArgument.js]
+const enUS = new Intl.Locale("en-US");
+const deDE = new Intl.Locale("de-DE");
+const jaJP = new Intl.Locale("ja-JP");
+const now = new Date();
+const num = 1000;
+const bigint = 123456789123456789n;
+now.toLocaleString(enUS);
+now.toLocaleDateString(enUS);
+now.toLocaleTimeString(enUS);
+now.toLocaleString([deDE, jaJP]);
+now.toLocaleDateString([deDE, jaJP]);
+now.toLocaleTimeString([deDE, jaJP]);
+num.toLocaleString(enUS);
+num.toLocaleString([deDE, jaJP]);
+bigint.toLocaleString(enUS);
+bigint.toLocaleString([deDE, jaJP]);