intl.d.ts: cleanup, add missing features, fix library discrepancies

src/compiler/commandLineParser.ts

@@ -200,6 +200,7 @@ const libEntries: [string, string][] = [
     ["es2019.string", "lib.es2019.string.d.ts"],
     ["es2019.symbol", "lib.es2019.symbol.d.ts"],
     ["es2019.intl", "lib.es2019.intl.d.ts"],
+    ["es2020.array", "lib.es2020.array.d.ts"],
     ["es2020.bigint", "lib.es2020.bigint.d.ts"],
     ["es2020.date", "lib.es2020.date.d.ts"],
     ["es2020.promise", "lib.es2020.promise.d.ts"],

src/lib/es2015.core.d.ts

@@ -43,7 +43,13 @@ interface Array<T> {
      */
     copyWithin(target: number, start: number, end?: number): this;
 
-    toLocaleString(locales: string | string[], options?: Intl.NumberFormatOptions & Intl.DateTimeFormatOptions): string;
+    /**
+     * Returns a string representation of an array.
+     * Each element is converted to a string using its `toLocaleString` method, then concatenated using the list separator of the current locale.
+     * @param locales Passed as the `locales` parameter to each array element's `toLocaleString` method.
+     * @param options Passed as the `options` parameter to each array element's `toLocaleString` method.
+     */
+    toLocaleString(locales?: string | readonly string[], options?: object): string;
 }
 
 interface ArrayConstructor {
@@ -345,7 +351,13 @@ interface ReadonlyArray<T> {
      */
     findIndex(predicate: (value: T, index: number, obj: readonly T[]) => unknown, thisArg?: any): number;
 
-    toLocaleString(locales: string | string[], options?: Intl.NumberFormatOptions & Intl.DateTimeFormatOptions): string;
+    /**
+     * Returns a string representation of an array.
+     * Each element is converted to a string using its `toLocaleString` method, then concatenated using the list separator of the current locale.
+     * @param locales Passed as the `locales` parameter to each array element's `toLocaleString` method.
+     * @param options Passed as the `options` parameter to each array element's `toLocaleString` method.
+     */
+    toLocaleString(locales?: string | readonly string[], options?: object): string;
 }
 
 interface RegExp {
@@ -437,6 +449,22 @@ interface String {
      */
     startsWith(searchString: string, position?: number): boolean;
 
+    /**
+     * Converts all alphabetic characters to lowercase, using locale-sensitive case mappings.
+     * @param locales A Unicode BCP 47 locale identifier, or list of identifiers, specifying the preferred locale to use for the conversion.
+     * This method does not perform locale matching; instead, it always selects the first supported locale.
+     * If omitted, the default locale is used.
+     */
+    toLocaleLowerCase(locales?: string | readonly string[]): string;
+
+    /**
+     * Converts all alphabetic characters to uppercase, using locale-sensitive case mappings.
+     * @param locales A Unicode BCP 47 locale identifier, or list of identifiers, specifying the preferred locale to use for the conversion.
+     * This method does not perform locale matching; instead, it always selects the first supported locale.
+     * If omitted, the default locale is used.
+     */
+    toLocaleUpperCase(locales?: string | readonly string[]): string;
+
     /**
      * Returns an `<a>` HTML anchor element and sets the name attribute to the text value
      * @deprecated A legacy feature for browser compatibility
@@ -543,37 +571,91 @@ interface StringConstructor {
 }
 
 interface Int8Array {
-    toLocaleString(locales: string | string[], options?: Intl.NumberFormatOptions): string;
+    /**
+     * Returns a string representation of a TypedArray.
+     * Each element is converted to a string using its `toLocaleString` method, then concatenated using the list separator of the current locale.
+     * @param locales A Unicode BCP 47 locale identifier, or list of identifiers, specifying the preferred locale to use for the conversion. If omitted, the default locale is used.
+     * @param options Corresponds to the `options` parameter of the `Intl.NumberFormat` constructor.
+     */
+    toLocaleString(locales?: string | readonly string[], options?: Intl.NumberFormatOptions): string;
 }
 
 interface Uint8Array {
-    toLocaleString(locales: string | string[], options?: Intl.NumberFormatOptions): string;
+    /**
+     * Returns a string representation of a TypedArray.
+     * Each element is converted to a string using its `toLocaleString` method, then concatenated using the list separator of the current locale.
+     * @param locales A Unicode BCP 47 locale identifier, or list of identifiers, specifying the preferred locale to use for the conversion. If omitted, the default locale is used.
+     * @param options Corresponds to the `options` parameter of the `Intl.NumberFormat` constructor.
+     */
+    toLocaleString(locales?: string | readonly string[], options?: Intl.NumberFormatOptions): string;
 }
 
 interface Uint8ClampedArray {
-    toLocaleString(locales: string | string[], options?: Intl.NumberFormatOptions): string;
+    /**
+     * Returns a string representation of a TypedArray.
+     * Each element is converted to a string using its `toLocaleString` method, then concatenated using the list separator of the current locale.
+     * @param locales A Unicode BCP 47 locale identifier, or list of identifiers, specifying the preferred locale to use for the conversion. If omitted, the default locale is used.
+     * @param options Corresponds to the `options` parameter of the `Intl.NumberFormat` constructor.
+     */
+    toLocaleString(locales?: string | readonly string[], options?: Intl.NumberFormatOptions): string;
 }
 
 interface Int16Array {
-    toLocaleString(locales: string | string[], options?: Intl.NumberFormatOptions): string;
+    /**
+     * Returns a string representation of a TypedArray.
+     * Each element is converted to a string using its `toLocaleString` method, then concatenated using the list separator of the current locale.
+     * @param locales A Unicode BCP 47 locale identifier, or list of identifiers, specifying the preferred locale to use for the conversion. If omitted, the default locale is used.
+     * @param options Corresponds to the `options` parameter of the `Intl.NumberFormat` constructor.
+     */
+    toLocaleString(locales?: string | readonly string[], options?: Intl.NumberFormatOptions): string;
 }
 
 interface Uint16Array {
-    toLocaleString(locales: string | string[], options?: Intl.NumberFormatOptions): string;
+    /**
+     * Returns a string representation of a TypedArray.
+     * Each element is converted to a string using its `toLocaleString` method, then concatenated using the list separator of the current locale.
+     * @param locales A Unicode BCP 47 locale identifier, or list of identifiers, specifying the preferred locale to use for the conversion. If omitted, the default locale is used.
+     * @param options Corresponds to the `options` parameter of the `Intl.NumberFormat` constructor.
+     */
+    toLocaleString(locales?: string | readonly string[], options?: Intl.NumberFormatOptions): string;
 }
 
 interface Int32Array {
-    toLocaleString(locales: string | string[], options?: Intl.NumberFormatOptions): string;
+    /**
+     * Returns a string representation of a TypedArray.
+     * Each element is converted to a string using its `toLocaleString` method, then concatenated using the list separator of the current locale.
+     * @param locales A Unicode BCP 47 locale identifier, or list of identifiers, specifying the preferred locale to use for the conversion. If omitted, the default locale is used.
+     * @param options Corresponds to the `options` parameter of the `Intl.NumberFormat` constructor.
+     */
+    toLocaleString(locales?: string | readonly string[], options?: Intl.NumberFormatOptions): string;
 }
 
 interface Uint32Array {
-    toLocaleString(locales: string | string[], options?: Intl.NumberFormatOptions): string;
+    /**
+     * Returns a string representation of a TypedArray.
+     * Each element is converted to a string using its `toLocaleString` method, then concatenated using the list separator of the current locale.
+     * @param locales A Unicode BCP 47 locale identifier, or list of identifiers, specifying the preferred locale to use for the conversion. If omitted, the default locale is used.
+     * @param options Corresponds to the `options` parameter of the `Intl.NumberFormat` constructor.
+     */
+    toLocaleString(locales?: string | readonly string[], options?: Intl.NumberFormatOptions): string;
 }
 
 interface Float32Array {
-    toLocaleString(locales: string | string[], options?: Intl.NumberFormatOptions): string;
+    /**
+     * Returns a string representation of a TypedArray.
+     * Each element is converted to a string using its `toLocaleString` method, then concatenated using the list separator of the current locale.
+     * @param locales A Unicode BCP 47 locale identifier, or list of identifiers, specifying the preferred locale to use for the conversion. If omitted, the default locale is used.
+     * @param options Corresponds to the `options` parameter of the `Intl.NumberFormat` constructor.
+     */
+    toLocaleString(locales?: string | readonly string[], options?: Intl.NumberFormatOptions): string;
 }
 
 interface Float64Array {
-    toLocaleString(locales: string | string[], options?: Intl.NumberFormatOptions): string;
+    /**
+     * Returns a string representation of a TypedArray.
+     * Each element is converted to a string using its `toLocaleString` method, then concatenated using the list separator of the current locale.
+     * @param locales A Unicode BCP 47 locale identifier, or list of identifiers, specifying the preferred locale to use for the conversion. If omitted, the default locale is used.
+     * @param options Corresponds to the `options` parameter of the `Intl.NumberFormat` constructor.
+     */
+    toLocaleString(locales?: string | readonly string[], options?: Intl.NumberFormatOptions): string;
 }

src/lib/es2016.intl.d.ts

@@ -1,13 +1,8 @@
 declare namespace Intl {
     /**
-     * The `Intl.getCanonicalLocales()` method returns an array containing
-     * the canonical locale names. Duplicates will be omitted and elements
-     * will be validated as structurally valid language tags.
-     *
-     * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/getCanonicalLocales)
-     *
-     * @param locale A list of String values for which to get the canonical locale names
-     * @returns An array containing the canonical and validated locale names.
+     * Takes a list of locale identifiers, and returns a deduplicated list of their canonical names.
+     * Structurally invalid identifiers will cause an error to be thrown.
+     * @param locales A Unicode BCP 47 locale identifier, or list of identifiers.
      */
-    function getCanonicalLocales(locale?: string | readonly string[]): string[];
+    function getCanonicalLocales(locales?: string | readonly string[]): string[];
 }

src/lib/es2017.intl.d.ts

@@ -1,26 +1,30 @@
 declare namespace Intl {
     interface DateTimeFormatPartTypesRegistry {
-        day: any;
-        dayPeriod: any;
-        era: any;
-        hour: any;
-        literal: any;
-        minute: any;
-        month: any;
-        second: any;
-        timeZoneName: any;
-        weekday: any;
-        year: any;
+        day: "day";
+        dayPeriod: "dayPeriod";
+        era: "era";
+        hour: "hour";
+        literal: "literal";
+        minute: "minute";
+        month: "month";
+        second: "second";
+        timeZoneName: "timeZoneName";
+        weekday: "weekday";
+        year: "year";
     }
-
-    type DateTimeFormatPartTypes = keyof DateTimeFormatPartTypesRegistry;
+    type DateTimeFormatPartTypes = DateTimeFormatPartTypesRegistry[keyof DateTimeFormatPartTypesRegistry];
 
     interface DateTimeFormatPart {
         type: DateTimeFormatPartTypes;
         value: string;
     }
 
     interface DateTimeFormat {
+        /**
+         * Formats a date as a string, according to the selected locale and formatting options,
+         * and returns the result as a list of locale-specific string tokens.
+         * @param date A `Date` object or timestamp. If undefined, defaults to the value of `Date.now()`.
+         */
         formatToParts(date?: Date | number): DateTimeFormatPart[];
     }
 }

src/lib/es2018.intl.d.ts

@@ -1,10 +1,9 @@
 declare namespace Intl {
-    // http://cldr.unicode.org/index/cldr-spec/plural-rules#TOC-Determining-Plural-Categories
     type LDMLPluralRule = "zero" | "one" | "two" | "few" | "many" | "other";
     type PluralRuleType = "cardinal" | "ordinal";
 
     interface PluralRulesOptions {
-        localeMatcher?: "lookup" | "best fit" | undefined;
+        localeMatcher?: LocaleMatcherAlgorithm | undefined;
         type?: PluralRuleType | undefined;
         minimumIntegerDigits?: number | undefined;
         minimumFractionDigits?: number | undefined;
@@ -18,48 +17,75 @@ declare namespace Intl {
         pluralCategories: LDMLPluralRule[];
         type: PluralRuleType;
         minimumIntegerDigits: number;
-        minimumFractionDigits: number;
-        maximumFractionDigits: number;
+        minimumFractionDigits?: number;
+        maximumFractionDigits?: number;
         minimumSignificantDigits?: number;
         maximumSignificantDigits?: number;
     }
 
     interface PluralRules {
-        resolvedOptions(): ResolvedPluralRulesOptions;
+        /**
+         * Returns the plural rule identifier for the given number, according to the selected locale and parsing options.
+         * @param n The number to parse.
+         */
         select(n: number): LDMLPluralRule;
+
+        /** Returns the locale and options computed during initialization of this `PluralRules` instance. */
+        resolvedOptions(): ResolvedPluralRulesOptions;
     }
 
     interface PluralRulesConstructor {
         new (locales?: string | readonly string[], options?: PluralRulesOptions): PluralRules;
-        (locales?: string | readonly string[], options?: PluralRulesOptions): PluralRules;
-        supportedLocalesOf(locales: string | readonly string[], options?: { localeMatcher?: "lookup" | "best fit"; }): string[];
+        readonly prototype: PluralRules;
+
+        /**
+         * Takes a list of locale identifiers, and returns the subset of identifiers that are supported by the current implementation of `PluralRules`.
+         * If none of the provided locales are supported, an empty array is returned.
+         * @param locales A Unicode BCP 47 locale identifier, or list of identifiers.
+         * @param options Options for the locale matching algorithm.
+         */
+        supportedLocalesOf(locales?: string | readonly string[], options?: SupportedLocalesOptions): string[];
     }
 
-    const PluralRules: PluralRulesConstructor;
+    var PluralRules: PluralRulesConstructor;
 
     interface NumberFormatPartTypeRegistry {
-        literal: never;
-        nan: never;
-        infinity: never;
-        percent: never;
-        integer: never;
-        group: never;
-        decimal: never;
-        fraction: never;
-        plusSign: never;
-        minusSign: never;
-        percentSign: never;
-        currency: never;
+        literal: "literal";
+        nan: "nan";
+        infinity: "infinity";
+        percent: "percent";
+        integer: "integer";
+        group: "group";
+        decimal: "decimal";
+        fraction: "fraction";
+        plusSign: "plusSign";
+        minusSign: "minusSign";
+        percentSign: "percentSign";
+        currency: "currency";
     }
-
-    type NumberFormatPartTypes = keyof NumberFormatPartTypeRegistry;
+    type NumberFormatPartTypes = NumberFormatPartTypeRegistry[keyof NumberFormatPartTypeRegistry];
 
     interface NumberFormatPart {
         type: NumberFormatPartTypes;
         value: string;
     }
 
     interface NumberFormat {
-        formatToParts(number?: number | bigint): NumberFormatPart[];
+        /**
+         * Formats a number as a string, according to the selected locale and formatting options,
+         * and returns the result as a list of locale-specific string tokens.
+         * @param value The value to be formatted.
+         */
+        formatToParts(value?: number): NumberFormatPart[];
+    }
+
+    type DateTimeFormatOptionsHourCycle = "h11" | "h12" | "h23" | "h24";
+
+    interface DateTimeFormatOptions {
+        hourCycle?: DateTimeFormatOptionsHourCycle | undefined;
+    }
+
+    interface ResolvedDateTimeFormatOptions {
+        hourCycle?: DateTimeFormatOptionsHourCycle;
     }
 }

src/lib/es2019.intl.d.ts

@@ -1,5 +1,5 @@
 declare namespace Intl {
     interface DateTimeFormatPartTypesRegistry {
-        unknown: never;
+        unknown: "unknown";
     }
 }