UNPKG

21.6 kBTypeScriptView Raw
1import type {
2 AdditionalTokensOptions,
3 FirstWeekContainsDateOptions,
4 LocalizedOptions,
5 WeekOptions,
6} from "./types.js";
7/**
8 * The {@link isMatch} function options.
9 */
10export interface IsMatchOptions
11 extends LocalizedOptions<"options" | "match" | "formatLong">,
12 WeekOptions,
13 FirstWeekContainsDateOptions,
14 AdditionalTokensOptions {}
15/**
16 * @name isMatch
17 * @category Common Helpers
18 * @summary validates the date string against given formats
19 *
20 * @description
21 * Return the true if given date is string correct against the given format else
22 * will return false.
23 *
24 * > ⚠️ Please note that the `format` tokens differ from Moment.js and other libraries.
25 * > See: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md
26 *
27 * The characters in the format string wrapped between two single quotes characters (') are escaped.
28 * Two single quotes in a row, whether inside or outside a quoted sequence, represent a 'real' single quote.
29 *
30 * Format of the format string is based on Unicode Technical Standard #35:
31 * https://www.unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table
32 * with a few additions (see note 5 below the table).
33 *
34 * Not all tokens are compatible. Combinations that don't make sense or could lead to bugs are prohibited
35 * and will throw `RangeError`. For example usage of 24-hour format token with AM/PM token will throw an exception:
36 *
37 * ```javascript
38 * isMatch('23 AM', 'HH a')
39 * //=> RangeError: The format string mustn't contain `HH` and `a` at the same time
40 * ```
41 *
42 * See the compatibility table: https://docs.google.com/spreadsheets/d/e/2PACX-1vQOPU3xUhplll6dyoMmVUXHKl_8CRDs6_ueLmex3SoqwhuolkuN3O05l4rqx5h1dKX8eb46Ul-CCSrq/pubhtml?gid=0&single=true
43 *
44 * Accepted format string patterns:
45 * | Unit |Prior| Pattern | Result examples | Notes |
46 * |---------------------------------|-----|---------|-----------------------------------|-------|
47 * | Era | 140 | G..GGG | AD, BC | |
48 * | | | GGGG | Anno Domini, Before Christ | 2 |
49 * | | | GGGGG | A, B | |
50 * | Calendar year | 130 | y | 44, 1, 1900, 2017, 9999 | 4 |
51 * | | | yo | 44th, 1st, 1900th, 9999999th | 4,5 |
52 * | | | yy | 44, 01, 00, 17 | 4 |
53 * | | | yyy | 044, 001, 123, 999 | 4 |
54 * | | | yyyy | 0044, 0001, 1900, 2017 | 4 |
55 * | | | yyyyy | ... | 2,4 |
56 * | Local week-numbering year | 130 | Y | 44, 1, 1900, 2017, 9000 | 4 |
57 * | | | Yo | 44th, 1st, 1900th, 9999999th | 4,5 |
58 * | | | YY | 44, 01, 00, 17 | 4,6 |
59 * | | | YYY | 044, 001, 123, 999 | 4 |
60 * | | | YYYY | 0044, 0001, 1900, 2017 | 4,6 |
61 * | | | YYYYY | ... | 2,4 |
62 * | ISO week-numbering year | 130 | R | -43, 1, 1900, 2017, 9999, -9999 | 4,5 |
63 * | | | RR | -43, 01, 00, 17 | 4,5 |
64 * | | | RRR | -043, 001, 123, 999, -999 | 4,5 |
65 * | | | RRRR | -0043, 0001, 2017, 9999, -9999 | 4,5 |
66 * | | | RRRRR | ... | 2,4,5 |
67 * | Extended year | 130 | u | -43, 1, 1900, 2017, 9999, -999 | 4 |
68 * | | | uu | -43, 01, 99, -99 | 4 |
69 * | | | uuu | -043, 001, 123, 999, -999 | 4 |
70 * | | | uuuu | -0043, 0001, 2017, 9999, -9999 | 4 |
71 * | | | uuuuu | ... | 2,4 |
72 * | Quarter (formatting) | 120 | Q | 1, 2, 3, 4 | |
73 * | | | Qo | 1st, 2nd, 3rd, 4th | 5 |
74 * | | | QQ | 01, 02, 03, 04 | |
75 * | | | QQQ | Q1, Q2, Q3, Q4 | |
76 * | | | QQQQ | 1st quarter, 2nd quarter, ... | 2 |
77 * | | | QQQQQ | 1, 2, 3, 4 | 4 |
78 * | Quarter (stand-alone) | 120 | q | 1, 2, 3, 4 | |
79 * | | | qo | 1st, 2nd, 3rd, 4th | 5 |
80 * | | | qq | 01, 02, 03, 04 | |
81 * | | | qqq | Q1, Q2, Q3, Q4 | |
82 * | | | qqqq | 1st quarter, 2nd quarter, ... | 2 |
83 * | | | qqqqq | 1, 2, 3, 4 | 3 |
84 * | Month (formatting) | 110 | M | 1, 2, ..., 12 | |
85 * | | | Mo | 1st, 2nd, ..., 12th | 5 |
86 * | | | MM | 01, 02, ..., 12 | |
87 * | | | MMM | Jan, Feb, ..., Dec | |
88 * | | | MMMM | January, February, ..., December | 2 |
89 * | | | MMMMM | J, F, ..., D | |
90 * | Month (stand-alone) | 110 | L | 1, 2, ..., 12 | |
91 * | | | Lo | 1st, 2nd, ..., 12th | 5 |
92 * | | | LL | 01, 02, ..., 12 | |
93 * | | | LLL | Jan, Feb, ..., Dec | |
94 * | | | LLLL | January, February, ..., December | 2 |
95 * | | | LLLLL | J, F, ..., D | |
96 * | Local week of year | 100 | w | 1, 2, ..., 53 | |
97 * | | | wo | 1st, 2nd, ..., 53th | 5 |
98 * | | | ww | 01, 02, ..., 53 | |
99 * | ISO week of year | 100 | I | 1, 2, ..., 53 | 5 |
100 * | | | Io | 1st, 2nd, ..., 53th | 5 |
101 * | | | II | 01, 02, ..., 53 | 5 |
102 * | Day of month | 90 | d | 1, 2, ..., 31 | |
103 * | | | do | 1st, 2nd, ..., 31st | 5 |
104 * | | | dd | 01, 02, ..., 31 | |
105 * | Day of year | 90 | D | 1, 2, ..., 365, 366 | 7 |
106 * | | | Do | 1st, 2nd, ..., 365th, 366th | 5 |
107 * | | | DD | 01, 02, ..., 365, 366 | 7 |
108 * | | | DDD | 001, 002, ..., 365, 366 | |
109 * | | | DDDD | ... | 2 |
110 * | Day of week (formatting) | 90 | E..EEE | Mon, Tue, Wed, ..., Su | |
111 * | | | EEEE | Monday, Tuesday, ..., Sunday | 2 |
112 * | | | EEEEE | M, T, W, T, F, S, S | |
113 * | | | EEEEEE | Mo, Tu, We, Th, Fr, Sa, Su | |
114 * | ISO day of week (formatting) | 90 | i | 1, 2, 3, ..., 7 | 5 |
115 * | | | io | 1st, 2nd, ..., 7th | 5 |
116 * | | | ii | 01, 02, ..., 07 | 5 |
117 * | | | iii | Mon, Tue, Wed, ..., Su | 5 |
118 * | | | iiii | Monday, Tuesday, ..., Sunday | 2,5 |
119 * | | | iiiii | M, T, W, T, F, S, S | 5 |
120 * | | | iiiiii | Mo, Tu, We, Th, Fr, Sa, Su | 5 |
121 * | Local day of week (formatting) | 90 | e | 2, 3, 4, ..., 1 | |
122 * | | | eo | 2nd, 3rd, ..., 1st | 5 |
123 * | | | ee | 02, 03, ..., 01 | |
124 * | | | eee | Mon, Tue, Wed, ..., Su | |
125 * | | | eeee | Monday, Tuesday, ..., Sunday | 2 |
126 * | | | eeeee | M, T, W, T, F, S, S | |
127 * | | | eeeeee | Mo, Tu, We, Th, Fr, Sa, Su | |
128 * | Local day of week (stand-alone) | 90 | c | 2, 3, 4, ..., 1 | |
129 * | | | co | 2nd, 3rd, ..., 1st | 5 |
130 * | | | cc | 02, 03, ..., 01 | |
131 * | | | ccc | Mon, Tue, Wed, ..., Su | |
132 * | | | cccc | Monday, Tuesday, ..., Sunday | 2 |
133 * | | | ccccc | M, T, W, T, F, S, S | |
134 * | | | cccccc | Mo, Tu, We, Th, Fr, Sa, Su | |
135 * | AM, PM | 80 | a..aaa | AM, PM | |
136 * | | | aaaa | a.m., p.m. | 2 |
137 * | | | aaaaa | a, p | |
138 * | AM, PM, noon, midnight | 80 | b..bbb | AM, PM, noon, midnight | |
139 * | | | bbbb | a.m., p.m., noon, midnight | 2 |
140 * | | | bbbbb | a, p, n, mi | |
141 * | Flexible day period | 80 | B..BBB | at night, in the morning, ... | |
142 * | | | BBBB | at night, in the morning, ... | 2 |
143 * | | | BBBBB | at night, in the morning, ... | |
144 * | Hour [1-12] | 70 | h | 1, 2, ..., 11, 12 | |
145 * | | | ho | 1st, 2nd, ..., 11th, 12th | 5 |
146 * | | | hh | 01, 02, ..., 11, 12 | |
147 * | Hour [0-23] | 70 | H | 0, 1, 2, ..., 23 | |
148 * | | | Ho | 0th, 1st, 2nd, ..., 23rd | 5 |
149 * | | | HH | 00, 01, 02, ..., 23 | |
150 * | Hour [0-11] | 70 | K | 1, 2, ..., 11, 0 | |
151 * | | | Ko | 1st, 2nd, ..., 11th, 0th | 5 |
152 * | | | KK | 01, 02, ..., 11, 00 | |
153 * | Hour [1-24] | 70 | k | 24, 1, 2, ..., 23 | |
154 * | | | ko | 24th, 1st, 2nd, ..., 23rd | 5 |
155 * | | | kk | 24, 01, 02, ..., 23 | |
156 * | Minute | 60 | m | 0, 1, ..., 59 | |
157 * | | | mo | 0th, 1st, ..., 59th | 5 |
158 * | | | mm | 00, 01, ..., 59 | |
159 * | Second | 50 | s | 0, 1, ..., 59 | |
160 * | | | so | 0th, 1st, ..., 59th | 5 |
161 * | | | ss | 00, 01, ..., 59 | |
162 * | Seconds timestamp | 40 | t | 512969520 | |
163 * | | | tt | ... | 2 |
164 * | Fraction of second | 30 | S | 0, 1, ..., 9 | |
165 * | | | SS | 00, 01, ..., 99 | |
166 * | | | SSS | 000, 001, ..., 999 | |
167 * | | | SSSS | ... | 2 |
168 * | Milliseconds timestamp | 20 | T | 512969520900 | |
169 * | | | TT | ... | 2 |
170 * | Timezone (ISO-8601 w/ Z) | 10 | X | -08, +0530, Z | |
171 * | | | XX | -0800, +0530, Z | |
172 * | | | XXX | -08:00, +05:30, Z | |
173 * | | | XXXX | -0800, +0530, Z, +123456 | 2 |
174 * | | | XXXXX | -08:00, +05:30, Z, +12:34:56 | |
175 * | Timezone (ISO-8601 w/o Z) | 10 | x | -08, +0530, +00 | |
176 * | | | xx | -0800, +0530, +0000 | |
177 * | | | xxx | -08:00, +05:30, +00:00 | 2 |
178 * | | | xxxx | -0800, +0530, +0000, +123456 | |
179 * | | | xxxxx | -08:00, +05:30, +00:00, +12:34:56 | |
180 * | Long localized date | NA | P | 05/29/1453 | 5,8 |
181 * | | | PP | May 29, 1453 | |
182 * | | | PPP | May 29th, 1453 | |
183 * | | | PPPP | Sunday, May 29th, 1453 | 2,5,8 |
184 * | Long localized time | NA | p | 12:00 AM | 5,8 |
185 * | | | pp | 12:00:00 AM | |
186 * | Combination of date and time | NA | Pp | 05/29/1453, 12:00 AM | |
187 * | | | PPpp | May 29, 1453, 12:00:00 AM | |
188 * | | | PPPpp | May 29th, 1453 at ... | |
189 * | | | PPPPpp | Sunday, May 29th, 1453 at ... | 2,5,8 |
190 * Notes:
191 * 1. "Formatting" units (e.g. formatting quarter) in the default en-US locale
192 * are the same as "stand-alone" units, but are different in some languages.
193 * "Formatting" units are declined according to the rules of the language
194 * in the context of a date. "Stand-alone" units are always nominative singular.
195 * In `format` function, they will produce different result:
196 *
197 * `format(new Date(2017, 10, 6), 'do LLLL', {locale: cs}) //=> '6. listopad'`
198 *
199 * `format(new Date(2017, 10, 6), 'do MMMM', {locale: cs}) //=> '6. listopadu'`
200 *
201 * `isMatch` will try to match both formatting and stand-alone units interchangably.
202 *
203 * 2. Any sequence of the identical letters is a pattern, unless it is escaped by
204 * the single quote characters (see below).
205 * If the sequence is longer than listed in table:
206 * - for numerical units (`yyyyyyyy`) `isMatch` will try to match a number
207 * as wide as the sequence
208 * - for text units (`MMMMMMMM`) `isMatch` will try to match the widest variation of the unit.
209 * These variations are marked with "2" in the last column of the table.
210 *
211 * 3. `QQQQQ` and `qqqqq` could be not strictly numerical in some locales.
212 * These tokens represent the shortest form of the quarter.
213 *
214 * 4. The main difference between `y` and `u` patterns are B.C. years:
215 *
216 * | Year | `y` | `u` |
217 * |------|-----|-----|
218 * | AC 1 | 1 | 1 |
219 * | BC 1 | 1 | 0 |
220 * | BC 2 | 2 | -1 |
221 *
222 * Also `yy` will try to guess the century of two digit year by proximity with `referenceDate`:
223 *
224 * `isMatch('50', 'yy') //=> true`
225 *
226 * `isMatch('75', 'yy') //=> true`
227 *
228 * while `uu` will use the year as is:
229 *
230 * `isMatch('50', 'uu') //=> true`
231 *
232 * `isMatch('75', 'uu') //=> true`
233 *
234 * The same difference is true for local and ISO week-numbering years (`Y` and `R`),
235 * except local week-numbering years are dependent on `options.weekStartsOn`
236 * and `options.firstWeekContainsDate` (compare [setISOWeekYear](https://date-fns.org/docs/setISOWeekYear)
237 * and [setWeekYear](https://date-fns.org/docs/setWeekYear)).
238 *
239 * 5. These patterns are not in the Unicode Technical Standard #35:
240 * - `i`: ISO day of week
241 * - `I`: ISO week of year
242 * - `R`: ISO week-numbering year
243 * - `o`: ordinal number modifier
244 * - `P`: long localized date
245 * - `p`: long localized time
246 *
247 * 6. `YY` and `YYYY` tokens represent week-numbering years but they are often confused with years.
248 * You should enable `options.useAdditionalWeekYearTokens` to use them. See: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md
249 *
250 * 7. `D` and `DD` tokens represent days of the year but they are ofthen confused with days of the month.
251 * You should enable `options.useAdditionalDayOfYearTokens` to use them. See: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md
252 *
253 * 8. `P+` tokens do not have a defined priority since they are merely aliases to other tokens based
254 * on the given locale.
255 *
256 * using `en-US` locale: `P` => `MM/dd/yyyy`
257 * using `en-US` locale: `p` => `hh:mm a`
258 * using `pt-BR` locale: `P` => `dd/MM/yyyy`
259 * using `pt-BR` locale: `p` => `HH:mm`
260 *
261 * Values will be checked in the descending order of its unit's priority.
262 * Units of an equal priority overwrite each other in the order of appearance.
263 *
264 * If no values of higher priority are matched (e.g. when matching string 'January 1st' without a year),
265 * the values will be taken from today's using `new Date()` date which works as a context of parsing.
266 *
267 * The result may vary by locale.
268 *
269 * If `formatString` matches with `dateString` but does not provides tokens, `referenceDate` will be returned.
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 dateStr - The date string to verify
274 * @param format - The string of tokens
275 * @param options - An object with options.
276 * see: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md
277 * see: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md
278 *
279 * @returns Is format string a match for date string?
280 *
281 * @throws `options.locale` must contain `match` property
282 * @throws use `yyyy` instead of `YYYY` for formatting years; see: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md
283 * @throws use `yy` instead of `YY` for formatting years; 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; 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; 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 * // Match 11 February 2014 from middle-endian format:
290 * const result = isMatch('02/11/2014', 'MM/dd/yyyy')
291 * //=> true
292 *
293 * @example
294 * // Match 28th of February in Esperanto locale in the context of 2010 year:
295 * import eo from 'date-fns/locale/eo'
296 * const result = isMatch('28-a de februaro', "do 'de' MMMM", {
297 * locale: eo
298 * })
299 * //=> true
300 */
301export declare function isMatch(
302 dateStr: string,
303 formatStr: string,
304 options?: IsMatchOptions,
305): boolean;