UNPKG

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