Skip to content

Commit 316e85f

Browse files
committed
feat(lib/es2020.intl): Add TSDoc for Intl.RelativeTimeFormat by review request microsoft#36084 (comment);
1 parent 5b05277 commit 316e85f

1 file changed

Lines changed: 221 additions & 5 deletions

File tree

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

Lines changed: 221 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,48 +1,264 @@
11
declare namespace Intl {
2-
type RelativeTimeFormatUnit = "year" | "quarter" | "month" | "week" | "day" | "hour" | "minute" | "second";
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+
*/
337
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+
*/
446
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+
*/
555
type RelativeTimeFormatStyle = "long" | "short" | "narrow";
656

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+
*/
765
interface RelativeTimeFormatOptions {
866
localeMatcher?: RelativeTimeFormatLocaleMatcher;
967
numeric?: RelativeTimeFormatNumeric;
1068
style?: RelativeTimeFormatStyle;
1169
}
1270

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+
*/
1380
interface ResolvedRelativeTimeFormatOptions {
14-
locale: string;
81+
locale: BCP47LanguageTag;
1582
style: RelativeTimeFormatStyle;
1683
numeric: RelativeTimeFormatNumeric;
1784
numberingSystem: string;
1885
}
1986

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+
*/
2095
interface RelativeTimeFormatPart {
2196
type: string;
2297
value: string;
2398
unit?: RelativeTimeFormatUnit;
2499
}
25100

26101
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+
*/
27131
format(
28132
value: number,
29133
unit: RelativeTimeFormatUnit,
30134
): 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+
*/
31164
formatToParts(
32165
value: number,
33166
unit: RelativeTimeFormatUnit,
34167
): 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+
*/
35180
resolvedOptions(): ResolvedRelativeTimeFormatOptions;
36181
}
37182

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+
*/
38194
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+
*/
39223
new(
40-
locales?: string | string[],
224+
locales?: BCP47LanguageTag | BCP47LanguageTag[],
41225
options?: RelativeTimeFormatOptions,
42226
): 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+
*/
43259
supportedLocalesOf(
44-
locales: string | string[],
260+
locales: BCP47LanguageTag | BCP47LanguageTag[],
45261
options?: RelativeTimeFormatOptions,
46-
): string[];
262+
): BCP47LanguageTag[];
47263
};
48264
}

0 commit comments

Comments
 (0)