Intl 2021 Updates

lib/lib.es2021.d.ts

@@ -22,3 +22,4 @@ and limitations under the License.
 /// <reference lib="es2021.promise" />
 /// <reference lib="es2021.string" />
 /// <reference lib="es2021.weakref" />
+/// <reference lib="es2021.intl" />

src/compiler/commandLineParser.ts

@@ -71,6 +71,7 @@ namespace ts {
         ["es2021.promise", "lib.es2021.promise.d.ts"],
         ["es2021.string", "lib.es2021.string.d.ts"],
         ["es2021.weakref", "lib.es2021.weakref.d.ts"],
+        ["es2021.intl", "lib.es2021.intl.d.ts"],
         ["esnext.array", "lib.es2019.array.d.ts"],
         ["esnext.symbol", "lib.es2019.symbol.d.ts"],
         ["esnext.asynciterable", "lib.es2018.asynciterable.d.ts"],

src/lib/README.md

@@ -1,8 +1,26 @@
 # Read this!
 
-The files within this directory are used to generate `lib.d.ts` and `lib.es6.d.ts`.
+The files within this directory are copied and deployed with TypeScript as the set of APIs  available as a part of the JavaScript language.
+
+There are three main domains of APIs in `src/lib`:
+
+ - **ECMAScript language features** - e.g. JavaScript APIs like functions on Array etc which are documented in [ECMA-262](https://tc39.es/ecma262/)
+ - **DOM APIs** - e.g. APIs which are available in Web Browsers
+ - **Intl APIs** - e.g. APIs scoped to `Intl` which are documented in [ECMA-402](https://www.ecma-international.org/publications-and-standards/standards/ecma-402/)
+
+Finished proposals, anything in here can safely be added according to the years the proposal was added:
+
+ - [JavaScript](https://github.com/tc39/proposals/blob/master/finished-proposals.md)
+ - [Intl](https://github.com/tc39/proposals/blob/master/ecma402/finished-proposals.md)
+
+## How do we figure out when to add something?
+
+TypeScript has a rule-of-thumb to only add something when it has got far enough through the standards process that it is more or less confirmed. For JavaScript APIs and language features, that usually means the proposal is at stage 3 or later.
+
+For the DOM APIs, which are a bit more free-form we have ask that APIs are available (un-prefixed/flagged) in at least 2 browser _engines_ (e.g. not just 2 chromium browsers.) 
 
 ## Generated files
 
-Any files ending in `.generated.d.ts` aren't meant to be edited by hand.
+The DOM files ending in `.generated.d.ts` aren't meant to be edited by hand.
+
 If you need to make changes to such files, make a change to the input files for [**our library generator**](https://github.com/Microsoft/TSJS-lib-generator).

src/lib/es2018.intl.d.ts

@@ -5,13 +5,13 @@ declare namespace Intl {
     type PluralRuleType = "cardinal" | "ordinal";
 
     interface PluralRulesOptions {
-        localeMatcher?: "lookup" | "best fit";
-        type?: PluralRuleType;
-        minimumIntegerDigits?: number;
-        minimumFractionDigits?: number;
-        maximumFractionDigits?: number;
-        minimumSignificantDigits?: number;
-        maximumSignificantDigits?: number;
+        localeMatcher?: "lookup" | "best fit" | undefined;
+        type?: PluralRuleType | undefined;
+        minimumIntegerDigits?: number | undefined;
+        minimumFractionDigits?: number | undefined;
+        maximumFractionDigits?: number | undefined;
+        minimumSignificantDigits?: number | undefined;
+        maximumSignificantDigits?: number | undefined;
     }
 
     interface ResolvedPluralRulesOptions {
@@ -33,9 +33,16 @@ declare namespace Intl {
     const PluralRules: {
         new (locales?: string | string[], options?: PluralRulesOptions): PluralRules;
         (locales?: string | string[], options?: PluralRulesOptions): PluralRules;
-        supportedLocalesOf(
-            locales: string | string[],
-            options?: PluralRulesOptions,
-        ): string[];
+
+        supportedLocalesOf(locales: string | string[], options?: { localeMatcher?: "lookup" | "best fit" }): string[];
     };
+
+    interface NumberFormatPart {
+        type: "compact" | "currency" | "decimal" | "exponentInteger" | "exponentMinusSign" | "exponentSeparator" | "fraction" | "group" | "infinity" | "integer" | "literal" | "minusSign" | "nan" | "plusSign" | "percentSign" | "unit" | "unknown";
+        value: string;
+    }
+
+    interface NumberFormat {
+        formatToParts(number?: number | bigint): NumberFormatPart[];
+    }
 }

src/lib/es2021.intl.d.ts

@@ -0,0 +1,9 @@
+declare namespace Intl {
+
+    interface DateTimeFormatOptions {
+        dateStyle?: "full" | "long" | "medium" | "short" | undefined;
+        timeStyle?: "full" | "long" | "medium" | "short" | undefined;
+        dayPeriod?: "narrow" | "short" | "long" | undefined;
+        fractionalSecondDigits?: 0 | 1 | 2 | 3 | undefined;
+    }
+}

src/lib/es5.d.ts

@@ -4295,12 +4295,12 @@ declare var Float64Array: Float64ArrayConstructor;
 
 declare namespace Intl {
     interface CollatorOptions {
-        usage?: string;
-        localeMatcher?: string;
-        numeric?: boolean;
-        caseFirst?: string;
-        sensitivity?: string;
-        ignorePunctuation?: boolean;
+        usage?: string | undefined;
+        localeMatcher?: string | undefined;
+        numeric?: boolean | undefined;
+        caseFirst?: string | undefined;
+        sensitivity?: string | undefined;
+        ignorePunctuation?: boolean | undefined;
     }
 
     interface ResolvedCollatorOptions {
@@ -4324,17 +4324,17 @@ declare namespace Intl {
     };
 
     interface NumberFormatOptions {
-        localeMatcher?: string;
-        style?: string;
-        currency?: string;
-        currencyDisplay?: string;
-        currencySign?: string;
-        useGrouping?: boolean;
-        minimumIntegerDigits?: number;
-        minimumFractionDigits?: number;
-        maximumFractionDigits?: number;
-        minimumSignificantDigits?: number;
-        maximumSignificantDigits?: number;
+        localeMatcher?: string | undefined;
+        style?: string | undefined;
+        currency?: string | undefined;
+        currencyDisplay?: string | undefined;
+        currencySign?: string | undefined;
+        useGrouping?: boolean | undefined;
+        minimumIntegerDigits?: number | undefined;
+        minimumFractionDigits?: number | undefined;
+        maximumFractionDigits?: number | undefined;
+        minimumSignificantDigits?: number | undefined;
+        maximumSignificantDigits?: number | undefined;
     }
 
     interface ResolvedNumberFormatOptions {
@@ -4362,19 +4362,19 @@ declare namespace Intl {
     };
 
     interface DateTimeFormatOptions {
-        localeMatcher?: "best fit" | "lookup";
-        weekday?: "long" | "short" | "narrow";
-        era?: "long" | "short" | "narrow";
-        year?: "numeric" | "2-digit";
-        month?: "numeric" | "2-digit" | "long" | "short" | "narrow";
-        day?: "numeric" | "2-digit";
-        hour?: "numeric" | "2-digit";
-        minute?: "numeric" | "2-digit";
-        second?: "numeric" | "2-digit";
-        timeZoneName?: "long" | "short";
-        formatMatcher?: "best fit" | "basic";
-        hour12?: boolean;
-        timeZone?: string;
+        localeMatcher?: "best fit" | "lookup" | undefined;
+        weekday?: "long" | "short" | "narrow" | undefined;
+        era?: "long" | "short" | "narrow" | undefined;
+        year?: "numeric" | "2-digit" | undefined;
+        month?: "numeric" | "2-digit" | "long" | "short" | "narrow" | undefined;
+        day?: "numeric" | "2-digit" | undefined;
+        hour?: "numeric" | "2-digit" | undefined;
+        minute?: "numeric" | "2-digit" | undefined;
+        second?: "numeric" | "2-digit" | undefined;
+        timeZoneName?: "long" | "short" | undefined;
+        formatMatcher?: "best fit" | "basic" | undefined;
+        hour12?: boolean | undefined;
+        timeZone?: string | undefined;
     }
 
     interface ResolvedDateTimeFormatOptions {

src/lib/esnext.intl.d.ts

@@ -1,12 +1,3 @@
 declare namespace Intl {
-    type NumberFormatPartTypes = "compact" | "currency" | "decimal" | "exponentInteger" | "exponentMinusSign" | "exponentSeparator" | "fraction" | "group" | "infinity" | "integer" | "literal" | "minusSign" | "nan" | "plusSign" | "percentSign" | "unit" | "unknown";
-
-    interface NumberFormatPart {
-        type: NumberFormatPartTypes;
-        value: string;
-    }
-
-    interface NumberFormat {
-        formatToParts(number?: number | bigint): NumberFormatPart[];
-    }
+   // Empty for now
 }

src/lib/libs.json

@@ -51,6 +51,7 @@
         "es2021.string",
         "es2021.promise",
         "es2021.weakref",
+        "es2021.intl",
         "esnext.intl",
         // Default libraries
         "es5.full",

tests/baselines/reference/bigintWithLib.symbols

@@ -241,16 +241,16 @@ let z = 12n; // should emit type bigint in declaration file
 // Test Intl methods with new parameter type
 new Intl.NumberFormat("fr").format(3000n);
 >new Intl.NumberFormat("fr").format : Symbol(Intl.NumberFormat.format, Decl(lib.es5.d.ts, --, --), Decl(lib.es2020.bigint.d.ts, --, --))
->Intl.NumberFormat : Symbol(Intl.NumberFormat, Decl(lib.es5.d.ts, --, --), Decl(lib.es5.d.ts, --, --), Decl(lib.es2020.bigint.d.ts, --, --))
+>Intl.NumberFormat : Symbol(Intl.NumberFormat, Decl(lib.es5.d.ts, --, --), Decl(lib.es5.d.ts, --, --), Decl(lib.es2018.intl.d.ts, --, --), Decl(lib.es2020.bigint.d.ts, --, --))
 >Intl : Symbol(Intl, Decl(lib.es5.d.ts, --, --), Decl(lib.es2017.intl.d.ts, --, --), Decl(lib.es2018.intl.d.ts, --, --), Decl(lib.es2020.bigint.d.ts, --, --), Decl(lib.es2020.intl.d.ts, --, --))
->NumberFormat : Symbol(Intl.NumberFormat, Decl(lib.es5.d.ts, --, --), Decl(lib.es5.d.ts, --, --), Decl(lib.es2020.bigint.d.ts, --, --))
+>NumberFormat : Symbol(Intl.NumberFormat, Decl(lib.es5.d.ts, --, --), Decl(lib.es5.d.ts, --, --), Decl(lib.es2018.intl.d.ts, --, --), Decl(lib.es2020.bigint.d.ts, --, --))
 >format : Symbol(Intl.NumberFormat.format, Decl(lib.es5.d.ts, --, --), Decl(lib.es2020.bigint.d.ts, --, --))
 
 new Intl.NumberFormat("fr").format(bigintVal);
 >new Intl.NumberFormat("fr").format : Symbol(Intl.NumberFormat.format, Decl(lib.es5.d.ts, --, --), Decl(lib.es2020.bigint.d.ts, --, --))
->Intl.NumberFormat : Symbol(Intl.NumberFormat, Decl(lib.es5.d.ts, --, --), Decl(lib.es5.d.ts, --, --), Decl(lib.es2020.bigint.d.ts, --, --))
+>Intl.NumberFormat : Symbol(Intl.NumberFormat, Decl(lib.es5.d.ts, --, --), Decl(lib.es5.d.ts, --, --), Decl(lib.es2018.intl.d.ts, --, --), Decl(lib.es2020.bigint.d.ts, --, --))
 >Intl : Symbol(Intl, Decl(lib.es5.d.ts, --, --), Decl(lib.es2017.intl.d.ts, --, --), Decl(lib.es2018.intl.d.ts, --, --), Decl(lib.es2020.bigint.d.ts, --, --), Decl(lib.es2020.intl.d.ts, --, --))
->NumberFormat : Symbol(Intl.NumberFormat, Decl(lib.es5.d.ts, --, --), Decl(lib.es5.d.ts, --, --), Decl(lib.es2020.bigint.d.ts, --, --))
+>NumberFormat : Symbol(Intl.NumberFormat, Decl(lib.es5.d.ts, --, --), Decl(lib.es5.d.ts, --, --), Decl(lib.es2018.intl.d.ts, --, --), Decl(lib.es2020.bigint.d.ts, --, --))
 >format : Symbol(Intl.NumberFormat.format, Decl(lib.es5.d.ts, --, --), Decl(lib.es2020.bigint.d.ts, --, --))
 >bigintVal : Symbol(bigintVal, Decl(bigintWithLib.ts, 1, 3))