Add Intl.ListFormat to es2021 lib

[vhfmag]

Suggestion

🔍 Search Terms

• Intl.ListFormat
• Intl
• ListFormat

✅ Viability Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

⭐ Suggestion

Add Intl.ListFormat to es2021 lib types (as per Finished Proposals).

Bringing this API to Typescript has been directly suggested before, but didn't follow the issue templates (#46866), and was also mentioned before (#45646 (comment), #29129 (comment)), but, as I couldn't find any specific active issue where the feature suggestion is being considered, I'm opening this issue.

📃 Motivating Example

Code that uses the Intl.ListFormat API should not fail type checking:

new Intl.ListFormat('bg', {type: 'conjunction'}).format(['a','b','c'])
new Intl.ListFormat('bg', {type: 'disjunction'}).formatToParts(['a','b','c'])

💻 Use Cases

new Intl.ListFormat('bg', {type: 'conjunction'}).format(['a','b','c'])
new Intl.ListFormat('bg', {type: 'disjunction'}).formatToParts(['a','b','c'])

[saschanaz]

It's ES2021 per the Finished Proposals list.

[vhfmag]

Thanks for pointing that out, I've updated the issue accordingly.

[chasm]

Is there a workaround for this?

[vhfmag]

Personally, I used something like:

declare namespace Intl {
    type ListType = "conjunction" | "disjunction";

    interface ListFormatOptions {
        localeMatcher?: "lookup" | "best fit";
        type?: ListType;
        style?: "long" | "short" | "narrow";
    }

    interface ListFormatPart {
        type: "element" | "literal";
        value: string;
    }

    class ListFormat {
        constructor(locales?: string | string[], options?: ListFormatOptions);
        format(values: any[]): string;
        formatToParts(values: any[]): ListFormatPart[];
        supportedLocalesOf(
            locales: string | string[],
            options?: ListFormatOptions,
        ): string[];
    }
}

[chasm]

Thanks for the help. That works great for making the linting errors go away, but (I'm using Deno) I still get [ERROR]: Property 'ListFormat' does not exist on type 'typeof Intl'. when I try to bundle it or run tests. And yet it works fine in the Deno REPL, so I know that it does exist.... I guess I don't understand Deno/TS enough to see what's going on.

[andreubotella]

The Deno REPL uses swc to transpile TypeScript without doing any type-checking, so that difference doesn't mean Deno or TypeScript comes with typings for Intl.ListFormat.

[chasm]

Yes. I understood that. The types are missing, but the REPL cares not. But the actual code must be there or it wouldn't work at all, no? The VSCode linter picks up the above namespace declaration and the red squiggles go away, but clearly the bundler and test in Deno do not, as they fail the type check.

[vhfmag]

@chasm I haven't much experience with it, but I found this in Deno's docs:

Another option is to use a configuration file that is configured to include the type definitions, by supplying a "types" value to the "compilerOptions". For example:

{
  "compilerOptions": {
    "types": [
      "./types.d.ts",
      "https://deno.land/x/pkg@1.0.0/types.d.ts",
      "/Users/me/pkg/types.d.ts"
    ]
  }
}

Maybe refering to the .d.ts file would make the bundler aware of it?