| 1 | import { formatters } from "./_lib/format/formatters.js";
|
| 2 | import { longFormatters } from "./_lib/format/longFormatters.js";
|
| 3 | import type {
|
| 4 | AdditionalTokensOptions,
|
| 5 | ContextOptions,
|
| 6 | DateArg,
|
| 7 | FirstWeekContainsDateOptions,
|
| 8 | LocalizedOptions,
|
| 9 | WeekOptions,
|
| 10 | } from "./types.js";
|
| 11 | export { formatters, longFormatters };
|
| 12 | export { format as formatDate };
|
| 13 | export type { FormatOptions as FormatDateOptions };
|
| 14 | /**
|
| 15 | * The {@link format} function options.
|
| 16 | */
|
| 17 | export interface FormatOptions
|
| 18 | extends LocalizedOptions<"options" | "localize" | "formatLong">,
|
| 19 | WeekOptions,
|
| 20 | FirstWeekContainsDateOptions,
|
| 21 | AdditionalTokensOptions,
|
| 22 | ContextOptions<Date> {}
|
| 23 | /**
|
| 24 | * @name format
|
| 25 | * @alias formatDate
|
| 26 | * @category Common Helpers
|
| 27 | * @summary Format the date.
|
| 28 | *
|
| 29 | * @description
|
| 30 | * Return the formatted date string in the given format. The result may vary by locale.
|
| 31 | *
|
| 32 | * > ⚠️ Please note that the `format` tokens differ from Moment.js and other libraries.
|
| 33 | * > See: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md
|
| 34 | *
|
| 35 | * The characters wrapped between two single quotes characters (') are escaped.
|
| 36 | * Two single quotes in a row, whether inside or outside a quoted sequence, represent a 'real' single quote.
|
| 37 | * (see the last example)
|
| 38 | *
|
| 39 | * Format of the string is based on Unicode Technical Standard #35:
|
| 40 | * https://www.unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table
|
| 41 | * with a few additions (see note 7 below the table).
|
| 42 | *
|
| 43 | * Accepted patterns:
|
| 44 | * | Unit | Pattern | Result examples | Notes |
|
| 45 | * |---------------------------------|---------|-----------------------------------|-------|
|
| 46 | * | Era | G..GGG | AD, BC | |
|
| 47 | * | | GGGG | Anno Domini, Before Christ | 2 |
|
| 48 | * | | GGGGG | A, B | |
|
| 49 | * | Calendar year | y | 44, 1, 1900, 2017 | 5 |
|
| 50 | * | | yo | 44th, 1st, 0th, 17th | 5,7 |
|
| 51 | * | | yy | 44, 01, 00, 17 | 5 |
|
| 52 | * | | yyy | 044, 001, 1900, 2017 | 5 |
|
| 53 | * | | yyyy | 0044, 0001, 1900, 2017 | 5 |
|
| 54 | * | | yyyyy | ... | 3,5 |
|
| 55 | * | Local week-numbering year | Y | 44, 1, 1900, 2017 | 5 |
|
| 56 | * | | Yo | 44th, 1st, 1900th, 2017th | 5,7 |
|
| 57 | * | | YY | 44, 01, 00, 17 | 5,8 |
|
| 58 | * | | YYY | 044, 001, 1900, 2017 | 5 |
|
| 59 | * | | YYYY | 0044, 0001, 1900, 2017 | 5,8 |
|
| 60 | * | | YYYYY | ... | 3,5 |
|
| 61 | * | ISO week-numbering year | R | -43, 0, 1, 1900, 2017 | 5,7 |
|
| 62 | * | | RR | -43, 00, 01, 1900, 2017 | 5,7 |
|
| 63 | * | | RRR | -043, 000, 001, 1900, 2017 | 5,7 |
|
| 64 | * | | RRRR | -0043, 0000, 0001, 1900, 2017 | 5,7 |
|
| 65 | * | | RRRRR | ... | 3,5,7 |
|
| 66 | * | Extended year | u | -43, 0, 1, 1900, 2017 | 5 |
|
| 67 | * | | uu | -43, 01, 1900, 2017 | 5 |
|
| 68 | * | | uuu | -043, 001, 1900, 2017 | 5 |
|
| 69 | * | | uuuu | -0043, 0001, 1900, 2017 | 5 |
|
| 70 | * | | uuuuu | ... | 3,5 |
|
| 71 | * | Quarter (formatting) | Q | 1, 2, 3, 4 | |
|
| 72 | * | | Qo | 1st, 2nd, 3rd, 4th | 7 |
|
| 73 | * | | QQ | 01, 02, 03, 04 | |
|
| 74 | * | | QQQ | Q1, Q2, Q3, Q4 | |
|
| 75 | * | | QQQQ | 1st quarter, 2nd quarter, ... | 2 |
|
| 76 | * | | QQQQQ | 1, 2, 3, 4 | 4 |
|
| 77 | * | Quarter (stand-alone) | q | 1, 2, 3, 4 | |
|
| 78 | * | | qo | 1st, 2nd, 3rd, 4th | 7 |
|
| 79 | * | | qq | 01, 02, 03, 04 | |
|
| 80 | * | | qqq | Q1, Q2, Q3, Q4 | |
|
| 81 | * | | qqqq | 1st quarter, 2nd quarter, ... | 2 |
|
| 82 | * | | qqqqq | 1, 2, 3, 4 | 4 |
|
| 83 | * | Month (formatting) | M | 1, 2, ..., 12 | |
|
| 84 | * | | Mo | 1st, 2nd, ..., 12th | 7 |
|
| 85 | * | | MM | 01, 02, ..., 12 | |
|
| 86 | * | | MMM | Jan, Feb, ..., Dec | |
|
| 87 | * | | MMMM | January, February, ..., December | 2 |
|
| 88 | * | | MMMMM | J, F, ..., D | |
|
| 89 | * | Month (stand-alone) | L | 1, 2, ..., 12 | |
|
| 90 | * | | Lo | 1st, 2nd, ..., 12th | 7 |
|
| 91 | * | | LL | 01, 02, ..., 12 | |
|
| 92 | * | | LLL | Jan, Feb, ..., Dec | |
|
| 93 | * | | LLLL | January, February, ..., December | 2 |
|
| 94 | * | | LLLLL | J, F, ..., D | |
|
| 95 | * | Local week of year | w | 1, 2, ..., 53 | |
|
| 96 | * | | wo | 1st, 2nd, ..., 53th | 7 |
|
| 97 | * | | ww | 01, 02, ..., 53 | |
|
| 98 | * | ISO week of year | I | 1, 2, ..., 53 | 7 |
|
| 99 | * | | Io | 1st, 2nd, ..., 53th | 7 |
|
| 100 | * | | II | 01, 02, ..., 53 | 7 |
|
| 101 | * | Day of month | d | 1, 2, ..., 31 | |
|
| 102 | * | | do | 1st, 2nd, ..., 31st | 7 |
|
| 103 | * | | dd | 01, 02, ..., 31 | |
|
| 104 | * | Day of year | D | 1, 2, ..., 365, 366 | 9 |
|
| 105 | * | | Do | 1st, 2nd, ..., 365th, 366th | 7 |
|
| 106 | * | | DD | 01, 02, ..., 365, 366 | 9 |
|
| 107 | * | | DDD | 001, 002, ..., 365, 366 | |
|
| 108 | * | | DDDD | ... | 3 |
|
| 109 | * | Day of week (formatting) | E..EEE | Mon, Tue, Wed, ..., Sun | |
|
| 110 | * | | EEEE | Monday, Tuesday, ..., Sunday | 2 |
|
| 111 | * | | EEEEE | M, T, W, T, F, S, S | |
|
| 112 | * | | EEEEEE | Mo, Tu, We, Th, Fr, Sa, Su | |
|
| 113 | * | ISO day of week (formatting) | i | 1, 2, 3, ..., 7 | 7 |
|
| 114 | * | | io | 1st, 2nd, ..., 7th | 7 |
|
| 115 | * | | ii | 01, 02, ..., 07 | 7 |
|
| 116 | * | | iii | Mon, Tue, Wed, ..., Sun | 7 |
|
| 117 | * | | iiii | Monday, Tuesday, ..., Sunday | 2,7 |
|
| 118 | * | | iiiii | M, T, W, T, F, S, S | 7 |
|
| 119 | * | | iiiiii | Mo, Tu, We, Th, Fr, Sa, Su | 7 |
|
| 120 | * | Local day of week (formatting) | e | 2, 3, 4, ..., 1 | |
|
| 121 | * | | eo | 2nd, 3rd, ..., 1st | 7 |
|
| 122 | * | | ee | 02, 03, ..., 01 | |
|
| 123 | * | | eee | Mon, Tue, Wed, ..., Sun | |
|
| 124 | * | | eeee | Monday, Tuesday, ..., Sunday | 2 |
|
| 125 | * | | eeeee | M, T, W, T, F, S, S | |
|
| 126 | * | | eeeeee | Mo, Tu, We, Th, Fr, Sa, Su | |
|
| 127 | * | Local day of week (stand-alone) | c | 2, 3, 4, ..., 1 | |
|
| 128 | * | | co | 2nd, 3rd, ..., 1st | 7 |
|
| 129 | * | | cc | 02, 03, ..., 01 | |
|
| 130 | * | | ccc | Mon, Tue, Wed, ..., Sun | |
|
| 131 | * | | cccc | Monday, Tuesday, ..., Sunday | 2 |
|
| 132 | * | | ccccc | M, T, W, T, F, S, S | |
|
| 133 | * | | cccccc | Mo, Tu, We, Th, Fr, Sa, Su | |
|
| 134 | * | AM, PM | a..aa | AM, PM | |
|
| 135 | * | | aaa | am, pm | |
|
| 136 | * | | aaaa | a.m., p.m. | 2 |
|
| 137 | * | | aaaaa | a, p | |
|
| 138 | * | AM, PM, noon, midnight | b..bb | AM, PM, noon, midnight | |
|
| 139 | * | | bbb | am, pm, noon, midnight | |
|
| 140 | * | | bbbb | a.m., p.m., noon, midnight | 2 |
|
| 141 | * | | bbbbb | a, p, n, mi | |
|
| 142 | * | Flexible day period | B..BBB | at night, in the morning, ... | |
|
| 143 | * | | BBBB | at night, in the morning, ... | 2 |
|
| 144 | * | | BBBBB | at night, in the morning, ... | |
|
| 145 | * | Hour [1-12] | h | 1, 2, ..., 11, 12 | |
|
| 146 | * | | ho | 1st, 2nd, ..., 11th, 12th | 7 |
|
| 147 | * | | hh | 01, 02, ..., 11, 12 | |
|
| 148 | * | Hour [0-23] | H | 0, 1, 2, ..., 23 | |
|
| 149 | * | | Ho | 0th, 1st, 2nd, ..., 23rd | 7 |
|
| 150 | * | | HH | 00, 01, 02, ..., 23 | |
|
| 151 | * | Hour [0-11] | K | 1, 2, ..., 11, 0 | |
|
| 152 | * | | Ko | 1st, 2nd, ..., 11th, 0th | 7 |
|
| 153 | * | | KK | 01, 02, ..., 11, 00 | |
|
| 154 | * | Hour [1-24] | k | 24, 1, 2, ..., 23 | |
|
| 155 | * | | ko | 24th, 1st, 2nd, ..., 23rd | 7 |
|
| 156 | * | | kk | 24, 01, 02, ..., 23 | |
|
| 157 | * | Minute | m | 0, 1, ..., 59 | |
|
| 158 | * | | mo | 0th, 1st, ..., 59th | 7 |
|
| 159 | * | | mm | 00, 01, ..., 59 | |
|
| 160 | * | Second | s | 0, 1, ..., 59 | |
|
| 161 | * | | so | 0th, 1st, ..., 59th | 7 |
|
| 162 | * | | ss | 00, 01, ..., 59 | |
|
| 163 | * | Fraction of second | S | 0, 1, ..., 9 | |
|
| 164 | * | | SS | 00, 01, ..., 99 | |
|
| 165 | * | | SSS | 000, 001, ..., 999 | |
|
| 166 | * | | SSSS | ... | 3 |
|
| 167 | * | Timezone (ISO-8601 w/ Z) | X | -08, +0530, Z | |
|
| 168 | * | | XX | -0800, +0530, Z | |
|
| 169 | * | | XXX | -08:00, +05:30, Z | |
|
| 170 | * | | XXXX | -0800, +0530, Z, +123456 | 2 |
|
| 171 | * | | XXXXX | -08:00, +05:30, Z, +12:34:56 | |
|
| 172 | * | Timezone (ISO-8601 w/o Z) | x | -08, +0530, +00 | |
|
| 173 | * | | xx | -0800, +0530, +0000 | |
|
| 174 | * | | xxx | -08:00, +05:30, +00:00 | 2 |
|
| 175 | * | | xxxx | -0800, +0530, +0000, +123456 | |
|
| 176 | * | | xxxxx | -08:00, +05:30, +00:00, +12:34:56 | |
|
| 177 | * | Timezone (GMT) | O...OOO | GMT-8, GMT+5:30, GMT+0 | |
|
| 178 | * | | OOOO | GMT-08:00, GMT+05:30, GMT+00:00 | 2 |
|
| 179 | * | Timezone (specific non-locat.) | z...zzz | GMT-8, GMT+5:30, GMT+0 | 6 |
|
| 180 | * | | zzzz | GMT-08:00, GMT+05:30, GMT+00:00 | 2,6 |
|
| 181 | * | Seconds timestamp | t | 512969520 | 7 |
|
| 182 | * | | tt | ... | 3,7 |
|
| 183 | * | Milliseconds timestamp | T | 512969520900 | 7 |
|
| 184 | * | | TT | ... | 3,7 |
|
| 185 | * | Long localized date | P | 04/29/1453 | 7 |
|
| 186 | * | | PP | Apr 29, 1453 | 7 |
|
| 187 | * | | PPP | April 29th, 1453 | 7 |
|
| 188 | * | | PPPP | Friday, April 29th, 1453 | 2,7 |
|
| 189 | * | Long localized time | p | 12:00 AM | 7 |
|
| 190 | * | | pp | 12:00:00 AM | 7 |
|
| 191 | * | | ppp | 12:00:00 AM GMT+2 | 7 |
|
| 192 | * | | pppp | 12:00:00 AM GMT+02:00 | 2,7 |
|
| 193 | * | Combination of date and time | Pp | 04/29/1453, 12:00 AM | 7 |
|
| 194 | * | | PPpp | Apr 29, 1453, 12:00:00 AM | 7 |
|
| 195 | * | | PPPppp | April 29th, 1453 at ... | 7 |
|
| 196 | * | | PPPPpppp| Friday, April 29th, 1453 at ... | 2,7 |
|
| 197 | * Notes:
|
| 198 | * 1. "Formatting" units (e.g. formatting quarter) in the default en-US locale
|
| 199 | * are the same as "stand-alone" units, but are different in some languages.
|
| 200 | * "Formatting" units are declined according to the rules of the language
|
| 201 | * in the context of a date. "Stand-alone" units are always nominative singular:
|
| 202 | *
|
| 203 | * `format(new Date(2017, 10, 6), 'do LLLL', {locale: cs}) //=> '6. listopad'`
|
| 204 | *
|
| 205 | * `format(new Date(2017, 10, 6), 'do MMMM', {locale: cs}) //=> '6. listopadu'`
|
| 206 | *
|
| 207 | * 2. Any sequence of the identical letters is a pattern, unless it is escaped by
|
| 208 | * the single quote characters (see below).
|
| 209 | * If the sequence is longer than listed in table (e.g. `EEEEEEEEEEE`)
|
| 210 | * the output will be the same as default pattern for this unit, usually
|
| 211 | * the longest one (in case of ISO weekdays, `EEEE`). Default patterns for units
|
| 212 | * are marked with "2" in the last column of the table.
|
| 213 | *
|
| 214 | * `format(new Date(2017, 10, 6), 'MMM') //=> 'Nov'`
|
| 215 | *
|
| 216 | * `format(new Date(2017, 10, 6), 'MMMM') //=> 'November'`
|
| 217 | *
|
| 218 | * `format(new Date(2017, 10, 6), 'MMMMM') //=> 'N'`
|
| 219 | *
|
| 220 | * `format(new Date(2017, 10, 6), 'MMMMMM') //=> 'November'`
|
| 221 | *
|
| 222 | * `format(new Date(2017, 10, 6), 'MMMMMMM') //=> 'November'`
|
| 223 | *
|
| 224 | * 3. Some patterns could be unlimited length (such as `yyyyyyyy`).
|
| 225 | * The output will be padded with zeros to match the length of the pattern.
|
| 226 | *
|
| 227 | * `format(new Date(2017, 10, 6), 'yyyyyyyy') //=> '00002017'`
|
| 228 | *
|
| 229 | * 4. `QQQQQ` and `qqqqq` could be not strictly numerical in some locales.
|
| 230 | * These tokens represent the shortest form of the quarter.
|
| 231 | *
|
| 232 | * 5. The main difference between `y` and `u` patterns are B.C. years:
|
| 233 | *
|
| 234 | * | Year | `y` | `u` |
|
| 235 | * |------|-----|-----|
|
| 236 | * | AC 1 | 1 | 1 |
|
| 237 | * | BC 1 | 1 | 0 |
|
| 238 | * | BC 2 | 2 | -1 |
|
| 239 | *
|
| 240 | * Also `yy` always returns the last two digits of a year,
|
| 241 | * while `uu` pads single digit years to 2 characters and returns other years unchanged:
|
| 242 | *
|
| 243 | * | Year | `yy` | `uu` |
|
| 244 | * |------|------|------|
|
| 245 | * | 1 | 01 | 01 |
|
| 246 | * | 14 | 14 | 14 |
|
| 247 | * | 376 | 76 | 376 |
|
| 248 | * | 1453 | 53 | 1453 |
|
| 249 | *
|
| 250 | * The same difference is true for local and ISO week-numbering years (`Y` and `R`),
|
| 251 | * except local week-numbering years are dependent on `options.weekStartsOn`
|
| 252 | * and `options.firstWeekContainsDate` (compare [getISOWeekYear](https://date-fns.org/docs/getISOWeekYear)
|
| 253 | * and [getWeekYear](https://date-fns.org/docs/getWeekYear)).
|
| 254 | *
|
| 255 | * 6. Specific non-location timezones are currently unavailable in `date-fns`,
|
| 256 | * so right now these tokens fall back to GMT timezones.
|
| 257 | *
|
| 258 | * 7. These patterns are not in the Unicode Technical Standard #35:
|
| 259 | * - `i`: ISO day of week
|
| 260 | * - `I`: ISO week of year
|
| 261 | * - `R`: ISO week-numbering year
|
| 262 | * - `t`: seconds timestamp
|
| 263 | * - `T`: milliseconds timestamp
|
| 264 | * - `o`: ordinal number modifier
|
| 265 | * - `P`: long localized date
|
| 266 | * - `p`: long localized time
|
| 267 | *
|
| 268 | * 8. `YY` and `YYYY` tokens represent week-numbering years but they are often confused with years.
|
| 269 | * You should enable `options.useAdditionalWeekYearTokens` to use them. See: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md
|
| 270 | *
|
| 271 | * 9. `D` and `DD` tokens represent days of the year but they are often confused with days of the month.
|
| 272 | * You should enable `options.useAdditionalDayOfYearTokens` to use them. See: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md
|
| 273 | *
|
| 274 | * @param date - The original date
|
| 275 | * @param format - The string of tokens
|
| 276 | * @param options - An object with options
|
| 277 | *
|
| 278 | * @returns The formatted date string
|
| 279 | *
|
| 280 | * @throws `date` must not be Invalid Date
|
| 281 | * @throws `options.locale` must contain `localize` property
|
| 282 | * @throws `options.locale` must contain `formatLong` property
|
| 283 | * @throws use `yyyy` instead of `YYYY` for formatting years using [format provided] to the input [input provided]; see: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md
|
| 284 | * @throws use `yy` instead of `YY` for formatting years using [format provided] to the input [input provided]; see: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md
|
| 285 | * @throws use `d` instead of `D` for formatting days of the month using [format provided] to the input [input provided]; see: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md
|
| 286 | * @throws use `dd` instead of `DD` for formatting days of the month using [format provided] to the input [input provided]; see: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md
|
| 287 | * @throws format string contains an unescaped latin alphabet character
|
| 288 | *
|
| 289 | * @example
|
| 290 | * // Represent 11 February 2014 in middle-endian format:
|
| 291 | * const result = format(new Date(2014, 1, 11), 'MM/dd/yyyy')
|
| 292 | * //=> '02/11/2014'
|
| 293 | *
|
| 294 | * @example
|
| 295 | * // Represent 2 July 2014 in Esperanto:
|
| 296 | * import { eoLocale } from 'date-fns/locale/eo'
|
| 297 | * const result = format(new Date(2014, 6, 2), "do 'de' MMMM yyyy", {
|
| 298 | * locale: eoLocale
|
| 299 | * })
|
| 300 | * //=> '2-a de julio 2014'
|
| 301 | *
|
| 302 | * @example
|
| 303 | * // Escape string by single quote characters:
|
| 304 | * const result = format(new Date(2014, 6, 2, 15), "h 'o''clock'")
|
| 305 | * //=> "3 o'clock"
|
| 306 | */
|
| 307 | export declare function format(
|
| 308 | date: DateArg<Date> & {},
|
| 309 | formatStr: string,
|
| 310 | options?: FormatOptions,
|
| 311 | ): string;
|