Intl Enumeration API Specification

April 21, 2021 · View on GitHub

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

Stage 2

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)

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

https://github.com/tc39/ecma402/issues/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

Get the List of 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

References

Analysis of Privacy / Fingerprinting Concerns

Implementation Status

============================ 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.