Intl Enumeration API Specification

List supported values of options in pre-existing ECMA 402 API.

Stage 2

• Advanced to Stage 1 in TC39 June 2020 meeting.
• Advanced to Stage 2 in TC39 September 2020 meeting.
• Update in TC39 Nov 2020 meeting.
• Update in TC39 Apr 2021 meeting.
• Plan to propose for Stage 3 advancement in TC39 May 2021 meeting

Entrance Criteria for Stage 1 (Proposal)

• Identified “champion” who will advance the addition: Frank Yung-Fong Tang
• Prose outlining the problem or need and the general shape of a solution: See this document
• Illustrative examples of usage: See this document
• High-level API: See this document
• Discussion of key algorithms, abstractions and semantics
• Identification of potential “cross-cutting” concerns and implementation challenges/complexity
• A publicly available repository for the proposal that captures the above requirements: https://github.com/tc39/proposal-intl-enumeration

Entrance Criteria for Stage 2 (Draft)

• Above
• Initial spec text: https://tc39.es/proposal-intl-enumeration
• Acceptance Signifies: The committee expects the feature to be developed and eventually included in the standard

Entrance Criteria for Stage 3 (Candidate)

• Above
• Complete spec text
• Designated reviewers have signed off on the current spec text
• All ECMAScript editors have signed off on the current spec text
• Acceptance Signifies: The solution is complete and no further work is possible without implementation experience, significant usage and external feedback.

Motivation

Overview

One method of Intl, return iteratable based on options

Intl.supportedValuesOf(key, [options])

Background

tc39/ecma402#435

Use case

Feature Tests for newly added values in options supported in Intl API. For example, web developer may want to use Chinese calendar if avaiable, or ROC calendar as a fallback if avaiable, otherwise Gregorian calendar as final resort. This API allow the code to check which calendar are avaiable and therefor to decide the fallback logic such as importing polyfill from the server.

Prior Arts

Get the List of TimeZone

• Use Cases:
  • How to get list of all timezones in javascript on Stack Overflow
• Prior Arts:
  • momentjs moment.tz.names
  • tzdb
  • countries-and-timezones
  • country-timezone

Get the List of Currency Codes

• Use Cases: *
• Prior Arts:
  • currency-codes

Usage example

// Find out the supported calendars
for (const calendar of Intl.supportedValuesOf("calendar")) {
   // 'buddhist', 'chinese',  ... 'islamicc'
}
// Find out the supported currencies
for (const currency of Intl.supportedValuesOf("currency")) {
   // 'AED', 'AFN', 'ALL', ... 'ZWL'
}
// Find out the supported numbering systems
for (const numberingSystem of Intl.supportedValuesOf("numberingSystem")) {
  // 'adlm', 'ahom', 'arab', ...  'wara', 'wcho'
}
// Find out the supported time zones
for (const timeZone of Intl.supportedValuesOf("timeZone")) {
  // 'Africa/Abidjan', 'Africa/Accra', ... 'Pacific/Wallis'
}
// Find out the supported time zones of region "US"
for (const timeZoneInUS of Intl.supportedValuesOf("timeZone", {region: "US")) {
  // "America/Adak", "America/Anchorage", ... "America/Yakutat", "Pacific/Honolulu"
}
// Find out the supported units
for (const unit of Intl.supportedValuesOf("unit") {
  // 'acre', 'bit', 'byte', ... 'year'
}
// Find out the supported units of 'digital' kind
for (const unit of Intl.supportedValuesOf("unit", {kind: "digital"}) {
  // 'bit', 'byte', 'gigabit', ... 'terabit', 'terabyte'
}

// Find out the supported collation
for (const collation of Intl.supportedValuesOf("collation", {region: "TW")}) {
  // 'stroke', 'pinyin', ... 'zhuyin'
}

Authors

• Frank Tang (@FrankYFTang)

Designated reviewers

• Shane Carr @sffc
• Jordan Harband @ljharb

ECMAScript editors

• Richard Gibson @gibson042

Proposal

Spec

• https://tc39.es/proposal-intl-enumeration/

References

Analysis of Privacy / Fingerprinting Concerns

• “Intl.Enumeration Privacy Implications Mozilla’s Recommendation”., Tom Ritter, Anne van Kesteren, Steven Englehardt, Zibi Braniecki, Mozilla, Feb 4, 2021.
• Discussion during 2021-03 ECMA402 Meeting
• Duscussion during 2021-04 ECMA402 Meeting (link to be added soon)

Implementation Status

• v8 tracking bug
• Mozilla
• JSC
• Test262

============================ Ignore Text Below ============================

The following are from the template, will be deleted later

This repo is setup by following instruction on TC39 template-for-proposals

  Your explainer can point readers to the `index.html` generated from `spec.emu`
  via markdown like

  ```markdown
  You can browse the [ecmarkup output](https://ACCOUNT.github.io/PROJECT/)
  or browse the [source](https://github.com/ACCOUNT/PROJECT/blob/master/spec.emu).
  ```

  where *ACCOUNT* and *PROJECT* are the first two path elements in your project's Github URL.
  For example, for github.com/**tc39**/**template-for-proposals**, *ACCOUNT* is "tc39"
  and *PROJECT* is "template-for-proposals".

Maintain your proposal repo

1. Make your changes to spec.emu (ecmarkup uses HTML syntax, but is not HTML, so I strongly suggest not naming it ".html")
2. Any commit that makes meaningful changes to the spec, should run npm run build and commit the resulting output.
3. Whenever you update ecmarkup, run npm run build and commit any changes that come from that dependency.