Skip to content

Commit dbaeed5

Browse files
DmitryMakhnevDmitry Makhnev
DmitryMakhnev
and
Dmitry Makhnev
authored
Add d.ts for Intl.RelativeTimeFormat (microsoft#36084)
* feat(lib/es2020.intl): Add `Intl.RelativeTimeFormat` (part of microsoft#29129); * fix(lib/es2020.intl): fix for tests and linters `Intl.RelativeTimeFormat` (part of microsoft#29129); * feat(lib/es2020.intl): Add TSDoc for `Intl.RelativeTimeFormat` by review request microsoft#36084 (comment); * fix(lib/es2020.intl): Fix for tests; Co-authored-by: Dmitry Makhnev <[email protected]>
1 parent 5f597e6 commit dbaeed5

File tree

6 files changed

+271
-4
lines changed

6 files changed

+271
-4
lines changed

‎src/compiler/commandLineParser.ts

+1
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,7 @@ namespace ts {
5353
["es2020.promise", "lib.es2020.promise.d.ts"],
5454
["es2020.string", "lib.es2020.string.d.ts"],
5555
["es2020.symbol.wellknown", "lib.es2020.symbol.wellknown.d.ts"],
56+
["es2020.intl", "lib.es2020.intl.d.ts"],
5657
["esnext.array", "lib.es2019.array.d.ts"],
5758
["esnext.symbol", "lib.es2019.symbol.d.ts"],
5859
["esnext.asynciterable", "lib.es2018.asynciterable.d.ts"],

‎src/lib/es2020.d.ts

+1
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,4 @@
33
/// <reference lib="es2020.promise" />
44
/// <reference lib="es2020.string" />
55
/// <reference lib="es2020.symbol.wellknown" />
6+
/// <reference lib="es2020.intl" />

‎src/lib/es2020.intl.d.ts

+264
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,264 @@
1+
declare namespace Intl {
2+
3+
/**
4+
* [BCP 47 language tag](http://tools.ietf.org/html/rfc5646) definition.
5+
*
6+
* [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument).
7+
*
8+
* [Wikipedia](https://en.wikipedia.org/wiki/IETF_language_tag).
9+
*/
10+
type BCP47LanguageTag = string;
11+
12+
/**
13+
* Unit to use in the relative time internationalized message.
14+
*
15+
* [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/format#Parameters).
16+
*
17+
* [Specification](https://tc39.es/ecma402/#sec-singularrelativetimeunit).
18+
*/
19+
type RelativeTimeFormatUnit =
20+
| "year" | "years"
21+
| "quarter" | "quarters"
22+
| "month" | "months"
23+
| "week" | "weeks"
24+
| "day" | "days"
25+
| "hour" | "hours"
26+
| "minute" | "minutes"
27+
| "second" | "seconds"
28+
;
29+
30+
/**
31+
* The locale matching algorithm to use.
32+
*
33+
* [MDN](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_negotiation).
34+
*
35+
* [Specification](https://tc39.es/ecma402/#sec-InitializeRelativeTimeFormat).
36+
*/
37+
type RelativeTimeFormatLocaleMatcher = "lookup" | "best fit";
38+
39+
/**
40+
* The format of output message.
41+
*
42+
* [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#Parameters).
43+
*
44+
* [Specification](https://tc39.es/ecma402/#sec-InitializeRelativeTimeFormat).
45+
*/
46+
type RelativeTimeFormatNumeric = "always" | "auto";
47+
48+
/**
49+
* The length of the internationalized message.
50+
*
51+
* [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#Parameters).
52+
*
53+
* [Specification](https://tc39.es/ecma402/#sec-InitializeRelativeTimeFormat).
54+
*/
55+
type RelativeTimeFormatStyle = "long" | "short" | "narrow";
56+
57+
/**
58+
* An object with some or all of properties of `options` parameter
59+
* of `Intl.RelativeTimeFormat` constructor.
60+
*
61+
* [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#Parameters).
62+
*
63+
* [Specification](https://tc39.es/ecma402/#sec-InitializeRelativeTimeFormat).
64+
*/
65+
interface RelativeTimeFormatOptions {
66+
localeMatcher?: RelativeTimeFormatLocaleMatcher;
67+
numeric?: RelativeTimeFormatNumeric;
68+
style?: RelativeTimeFormatStyle;
69+
}
70+
71+
/**
72+
* An object with properties reflecting the locale
73+
* and formatting options computed during initialization
74+
* of the `Intel.RelativeTimeFormat` object
75+
*
76+
* [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/resolvedOptions#Description).
77+
*
78+
* [Specification](https://tc39.es/ecma402/#table-relativetimeformat-resolvedoptions-properties)
79+
*/
80+
interface ResolvedRelativeTimeFormatOptions {
81+
locale: BCP47LanguageTag;
82+
style: RelativeTimeFormatStyle;
83+
numeric: RelativeTimeFormatNumeric;
84+
numberingSystem: string;
85+
}
86+
87+
/**
88+
* An object representing the relative time format in parts
89+
* that can be used for custom locale-aware formatting.
90+
*
91+
* [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/formatToParts#Using_formatToParts).
92+
*
93+
* [Specification](https://tc39.es/ecma402/#sec-FormatRelativeTimeToParts).
94+
*/
95+
interface RelativeTimeFormatPart {
96+
type: string;
97+
value: string;
98+
unit?: RelativeTimeFormatUnit;
99+
}
100+
101+
interface RelativeTimeFormat {
102+
/**
103+
* Formats a value and a unit according to the locale
104+
* and formatting options of the given
105+
* [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RelativeTimeFormat)
106+
* object.
107+
*
108+
* While this method automatically provides the correct plural forms,
109+
* the grammatical form is otherwise as neutral as possible.
110+
* It is the caller's responsibility to handle cut-off logic
111+
* such as deciding between displaying "in 7 days" or "in 1 week".
112+
* This API does not support relative dates involving compound units.
113+
* e.g "in 5 days and 4 hours".
114+
*
115+
* @param value - Numeric value to use in the internationalized relative time message
116+
*
117+
* @param unit - [Unit](https://tc39.es/ecma402/#sec-singularrelativetimeunit)
118+
* to use in the relative time internationalized message.
119+
* Possible values are: `"year"`, `"quarter"`, `"month"`, `"week"`,
120+
* `"day"`, `"hour"`, `"minute"`, `"second"`.
121+
* Plural forms are also permitted.
122+
*
123+
* @throws `RangeError` if `unit` was given something other than `unit` possible values
124+
*
125+
* @returns Internationalized relative time message as string
126+
*
127+
* [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/format).
128+
*
129+
* [Specification](https://tc39.es/ecma402/#sec-Intl.RelativeTimeFormat.prototype.format).
130+
*/
131+
format(
132+
value: number,
133+
unit: RelativeTimeFormatUnit,
134+
): string;
135+
136+
/**
137+
* A version of the format method which it returns an array of objects
138+
* which represent "parts" of the object,
139+
* separating the formatted number into its constituent parts
140+
* and separating it from other surrounding text.
141+
* These objects have two properties:
142+
* `type` a NumberFormat formatToParts type, and `value`,
143+
* which is the String which is the component of the output.
144+
* If a "part" came from NumberFormat,
145+
* it will have a unit property which indicates the `unit` being formatted;
146+
* literals which are part of the larger frame will not have this property.
147+
*
148+
* @param value - Numeric value to use in the internationalized relative time message
149+
*
150+
* @param unit - [Unit](https://tc39.es/ecma402/#sec-singularrelativetimeunit)
151+
* to use in the relative time internationalized message.
152+
* Possible values are: `"year"`, `"quarter"`, `"month"`, `"week"`,
153+
* `"day"`, `"hour"`, `"minute"`, `"second"`.
154+
* Plural forms are also permitted.
155+
*
156+
* @throws `RangeError` if `unit` was given something other than `unit` possible values
157+
*
158+
* @returns Array of [FormatRelativeTimeToParts](https://tc39.es/ecma402/#sec-FormatRelativeTimeToParts)
159+
*
160+
* [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/formatToParts).
161+
*
162+
* [Specification](https://tc39.es/ecma402/#sec-Intl.RelativeTimeFormat.prototype.formatToParts).
163+
*/
164+
formatToParts(
165+
value: number,
166+
unit: RelativeTimeFormatUnit,
167+
): RelativeTimeFormatPart[];
168+
169+
/**
170+
* Provides access to the locale and options computed during initialization of this `Intl.RelativeTimeFormat` object.
171+
*
172+
* @returns A new object with properties reflecting the locale
173+
* and formatting options computed during initialization
174+
* of the `Intel.RelativeTimeFormat` object.
175+
*
176+
* [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/resolvedOptions).
177+
*
178+
* [Specification](https://tc39.es/ecma402/#sec-intl.relativetimeformat.prototype.resolvedoptions)
179+
*/
180+
resolvedOptions(): ResolvedRelativeTimeFormatOptions;
181+
}
182+
183+
/**
184+
* The [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RelativeTimeFormat)
185+
* object is a constructor for objects that enable language-sensitive relative time formatting.
186+
*
187+
* Part of [Intl object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl)
188+
* namespace and the [ECMAScript Internationalization API](https://www.ecma-international.org/publications/standards/Ecma-402.htm).
189+
*
190+
* [Compatibility](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat#Browser_compatibility).
191+
*
192+
* [Polyfills](https://github.com/tc39/proposal-intl-relative-time#polyfills).
193+
*/
194+
const RelativeTimeFormat: {
195+
/**
196+
* Constructor creates [Intl.RelativeTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RelativeTimeFormat)
197+
* objects
198+
*
199+
* @param locales - A string with a [BCP 47 language tag](http://tools.ietf.org/html/rfc5646), or an array of such strings.
200+
* For the general form and interpretation of the locales argument,
201+
* see the [`Intl` page](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_identification_and_negotiation).
202+
*
203+
* @param options - An [object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#Parameters)
204+
* with some or all of options of the formatting.
205+
* An object with some or all of the following properties:
206+
* - `localeMatcher` - The locale matching algorithm to use.
207+
* Possible values are `"lookup"` and `"best fit"`; the default is `"best fit"`.
208+
* For information about this option, see [Intl page](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_negotiation).
209+
* - `numeric` - The format of output message.
210+
* Possible values are: `"always"` (default, e.g., `1 day ago`) or `"auto"` (e.g., `yesterday`).
211+
* The `"auto"` value allows to not always have to use numeric values in the output.
212+
* - `style` - The length of the internationalized message. Possible values are:
213+
* `"long"` (default, e.g., in 1 month),
214+
* `"short"` (e.g., in 1 mo.)
215+
* or `"narrow"` (e.g., in 1 mo.). The narrow style could be similar to the short style for some locales.
216+
*
217+
* @returns [Intl.RelativeTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RelativeTimeFormat) object.
218+
*
219+
* [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat).
220+
*
221+
* [Specification](https://tc39.es/ecma402/#sec-intl-relativetimeformat-constructor).
222+
*/
223+
new(
224+
locales?: BCP47LanguageTag | BCP47LanguageTag[],
225+
options?: RelativeTimeFormatOptions,
226+
): RelativeTimeFormat;
227+
228+
/**
229+
* Returns an array containing those of the provided locales
230+
* that are supported in date and time formatting
231+
* without having to fall back to the runtime's default locale.
232+
*
233+
* @param locales - A string with a [BCP 47 language tag](http://tools.ietf.org/html/rfc5646), or an array of such strings.
234+
* For the general form and interpretation of the locales argument,
235+
* see the [`Intl` page](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_identification_and_negotiation).
236+
*
237+
* @param options - An [object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#Parameters)
238+
* with some or all of options of the formatting.
239+
* An object with some or all of the following properties:
240+
* - `localeMatcher` - The locale matching algorithm to use.
241+
* Possible values are `"lookup"` and `"best fit"`; the default is `"best fit"`.
242+
* For information about this option, see [Intl page](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_negotiation).
243+
* - `numeric` - The format of output message.
244+
* Possible values are: `"always"` (default, e.g., `1 day ago`) or `"auto"` (e.g., `yesterday`).
245+
* The `"auto"` value allows to not always have to use numeric values in the output.
246+
* - `style` - The length of the internationalized message. Possible values are:
247+
* `"long"` (default, e.g., in 1 month),
248+
* `"short"` (e.g., in 1 mo.)
249+
* or `"narrow"` (e.g., in 1 mo.). The narrow style could be similar to the short style for some locales.
250+
*
251+
* @returns An array containing those of the provided locales
252+
* that are supported in date and time formatting
253+
* without having to fall back to the runtime's default locale.
254+
*
255+
* [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/supportedLocalesOf).
256+
*
257+
* [Specification](https://tc39.es/ecma402/#sec-Intl.RelativeTimeFormat.supportedLocalesOf).
258+
*/
259+
supportedLocalesOf(
260+
locales: BCP47LanguageTag | BCP47LanguageTag[],
261+
options?: RelativeTimeFormatOptions,
262+
): BCP47LanguageTag[];
263+
};
264+
}

‎src/lib/libs.json

+1
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@
4444
"es2020.promise",
4545
"es2020.string",
4646
"es2020.symbol.wellknown",
47+
"es2020.intl",
4748
"esnext.intl",
4849
"esnext.string",
4950
"esnext.promise",

0 commit comments

Comments
 (0)