Various Intl-related constructors and methods reject Intl.Locale objects in locales parameter

[lionel-rowe]

lib Update Request

Various Intl-related constructors and methods reject Intl.Locale objects in their locales parameter.

Related to #47802 (Signature for toLocale[X]String is missing Intl.Locale), but the updated signature is still missing for various other Intl-related constructors and methods.

Draft fix here:
main...lionel-rowe:TypeScript:fix/locales-argument

I can submit as a PR once this issue is accepted, or happy for someone else to pick it up otherwise.

Configuration Check

My compilation target is ES2022 and my lib is the default.

Missing/Incorrect Definition

Various, including but not limited to:

• String#toLocaleUpperCase
• Intl.Collator constructor
• Intl.DateTimeFormat constructor
• Intl.ListFormat constructor
• Intl.Segmenter constructor

Sample Code

const locale = new Intl.Locale('es')

// these now work as expected, thanks to https://github.com/microsoft/TypeScript/pull/47811
0 .toLocaleString(locale)
new Date(0).toLocaleDateString(locale)

// ...but these all give `Argument of type 'Locale' is not assignable to parameter of type 'string | string[] | undefined'.`
// All function as expected without throwing in JS (browser/node/deno)
'x'.toLocaleUpperCase(locale)
new Intl.Collator(locale)
new Intl.DateTimeFormat(locale)
new Intl.ListFormat(locale)
new Intl.Segmenter(locale, { granularity: 'word' })

Documentation Link

https://tc39.es/ecma402/#sec-canonicalizelocalelist

CanonicalizeLocaleList is called on all such locales arguments, iterating through them as an array, checking for the [[InitializedLocale]] internal slot (used to identify Intl.Locale objects), and reading the [[Locale]] internal slot if it exists (for Intl.Locale objects, this is the string representation of the locale). Thus 'x'.toLocaleUpperCase('es') behaves identically to 'x'.toLocaleUpperCase(new Locale('es'))

🔎 Search Terms

• locales
• Intl.Locale
• LocalesArgument
• CanonicalizeLocaleList

[singhBinary]

A workaround

declare namespace Intl {
  type Key = 'calendar' | 'collation' | 'currency' | 'numberingSystem' | 'timeZone' | 'unit';

  type 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;
  }

  function supportedValuesOf(input: Key): string[];

  class DateTimeFormat {
    constructor(locales?: string | string[], options?: DateTimeFormatOptions);
    format(date?: Date | number): string;
  }
}

[lionel-rowe]

A workaround

@singhBinary what's this a workaround for? This doesn't seem to be related to this issue, which concerns allowing Intl.Locale or Intl.Locale[] for locales parameters to various Intl-related web APIs.

[marcosbrasil]

If someone have facing that same problem as me with toLocaleDateString options, just type like:

const options: Intl.DateTimeFormatOptions = {
    weekday: "long",
    year: "numeric",
    month: "short",
    day: "numeric",
}

[lionel-rowe]

If someone have facing that same problem as me with toLocaleDateString options, just type like:

@marcosbrasil I'm not sure what problem you're referring to, this is your first comment on this issue. Did you mean to comment on a different issue? This also doesn't seem related to Intl.Locale objects.

[marcosbrasil]

@lionel-rowe , sorry if that was inappropriate, feel free to remove my comment if that is the case. But this issue was the most "foundable" so I thought that someone with the same issue, would end up coming here. The issue is related with toLocaleDateString and the second arg options.

const options = {
    weekday: "long",
    year: "numeric",
    month: "short",
    day: "numeric",
}

date.toLocaleDateString('pt-br', options)

This generates the following error:

No overload matches this call.
  Overload 1 of 3, '(locales?: LocalesArgument, options?: DateTimeFormatOptions | undefined): string', gave the following error.
    Argument of type '{ weekday: string; year: string; month: string; day: string; }' is not assignable to parameter of type 'DateTimeFormatOptions'.
      Types of property 'weekday' are incompatible.
        Type 'string' is not assignable to type '"long" | "short" | "narrow" | undefined'.
  Overload 2 of 3, '(locales?: string | string[] | undefined, options?: DateTimeFormatOptions | undefined): string', gave the following error.
    Argument of type '{ weekday: string; year: string; month: string; day: string; }' is not assignable to parameter of type 'DateTimeFormatOptions'.

[lionel-rowe]

sorry if that was inappropriate, feel free to remove my comment if that is the case

@marcosbrasil No worries! I can't remove/hide comments as I'm not a maintainer of this repository (perhaps a maintainer can help tidy up this thread if they come across it), but in future, I recommend Reddit or Stack Overflow for this kind of question rather than posting in or opening an issue. GitHub issues are usually for reporting bugs or feature requests to do with the library itself, rather than debugging your own userland code.

I wrote up an explanation of your issue and how to fix it in this TypeScript playground.