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