@mll-lab/js-utils 2.32.0 → 2.33.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/dist/date.d.ts +5 -0
  2. package/dist/index.common.js +304 -0
  3. package/dist/index.common.js.map +1 -1
  4. package/dist/index.js +304 -0
  5. package/dist/index.js.map +1 -1
  6. package/package.json +1 -1
package/dist/index.js CHANGED
@@ -15003,6 +15003,300 @@ function cleanEscapedString(input) {
15003
15003
  return input.match(escapedStringRegExp)[1].replace(doubleQuoteRegExp, "'");
15004
15004
  }
15005
15005
 
15006
+ /**
15007
+ * The {@link isMatch} function options.
15008
+ */
15009
+
15010
+ /**
15011
+ * @name isMatch
15012
+ * @category Common Helpers
15013
+ * @summary validates the date string against given formats
15014
+ *
15015
+ * @description
15016
+ * Return the true if given date is string correct against the given format else
15017
+ * will return false.
15018
+ *
15019
+ * > ⚠️ Please note that the `format` tokens differ from Moment.js and other libraries.
15020
+ * > See: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md
15021
+ *
15022
+ * The characters in the format string wrapped between two single quotes characters (') are escaped.
15023
+ * Two single quotes in a row, whether inside or outside a quoted sequence, represent a 'real' single quote.
15024
+ *
15025
+ * Format of the format string is based on Unicode Technical Standard #35:
15026
+ * https://www.unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table
15027
+ * with a few additions (see note 5 below the table).
15028
+ *
15029
+ * Not all tokens are compatible. Combinations that don't make sense or could lead to bugs are prohibited
15030
+ * and will throw `RangeError`. For example usage of 24-hour format token with AM/PM token will throw an exception:
15031
+ *
15032
+ * ```javascript
15033
+ * isMatch('23 AM', 'HH a')
15034
+ * //=> RangeError: The format string mustn't contain `HH` and `a` at the same time
15035
+ * ```
15036
+ *
15037
+ * See the compatibility table: https://docs.google.com/spreadsheets/d/e/2PACX-1vQOPU3xUhplll6dyoMmVUXHKl_8CRDs6_ueLmex3SoqwhuolkuN3O05l4rqx5h1dKX8eb46Ul-CCSrq/pubhtml?gid=0&single=true
15038
+ *
15039
+ * Accepted format string patterns:
15040
+ * | Unit |Prior| Pattern | Result examples | Notes |
15041
+ * |---------------------------------|-----|---------|-----------------------------------|-------|
15042
+ * | Era | 140 | G..GGG | AD, BC | |
15043
+ * | | | GGGG | Anno Domini, Before Christ | 2 |
15044
+ * | | | GGGGG | A, B | |
15045
+ * | Calendar year | 130 | y | 44, 1, 1900, 2017, 9999 | 4 |
15046
+ * | | | yo | 44th, 1st, 1900th, 9999999th | 4,5 |
15047
+ * | | | yy | 44, 01, 00, 17 | 4 |
15048
+ * | | | yyy | 044, 001, 123, 999 | 4 |
15049
+ * | | | yyyy | 0044, 0001, 1900, 2017 | 4 |
15050
+ * | | | yyyyy | ... | 2,4 |
15051
+ * | Local week-numbering year | 130 | Y | 44, 1, 1900, 2017, 9000 | 4 |
15052
+ * | | | Yo | 44th, 1st, 1900th, 9999999th | 4,5 |
15053
+ * | | | YY | 44, 01, 00, 17 | 4,6 |
15054
+ * | | | YYY | 044, 001, 123, 999 | 4 |
15055
+ * | | | YYYY | 0044, 0001, 1900, 2017 | 4,6 |
15056
+ * | | | YYYYY | ... | 2,4 |
15057
+ * | ISO week-numbering year | 130 | R | -43, 1, 1900, 2017, 9999, -9999 | 4,5 |
15058
+ * | | | RR | -43, 01, 00, 17 | 4,5 |
15059
+ * | | | RRR | -043, 001, 123, 999, -999 | 4,5 |
15060
+ * | | | RRRR | -0043, 0001, 2017, 9999, -9999 | 4,5 |
15061
+ * | | | RRRRR | ... | 2,4,5 |
15062
+ * | Extended year | 130 | u | -43, 1, 1900, 2017, 9999, -999 | 4 |
15063
+ * | | | uu | -43, 01, 99, -99 | 4 |
15064
+ * | | | uuu | -043, 001, 123, 999, -999 | 4 |
15065
+ * | | | uuuu | -0043, 0001, 2017, 9999, -9999 | 4 |
15066
+ * | | | uuuuu | ... | 2,4 |
15067
+ * | Quarter (formatting) | 120 | Q | 1, 2, 3, 4 | |
15068
+ * | | | Qo | 1st, 2nd, 3rd, 4th | 5 |
15069
+ * | | | QQ | 01, 02, 03, 04 | |
15070
+ * | | | QQQ | Q1, Q2, Q3, Q4 | |
15071
+ * | | | QQQQ | 1st quarter, 2nd quarter, ... | 2 |
15072
+ * | | | QQQQQ | 1, 2, 3, 4 | 4 |
15073
+ * | Quarter (stand-alone) | 120 | q | 1, 2, 3, 4 | |
15074
+ * | | | qo | 1st, 2nd, 3rd, 4th | 5 |
15075
+ * | | | qq | 01, 02, 03, 04 | |
15076
+ * | | | qqq | Q1, Q2, Q3, Q4 | |
15077
+ * | | | qqqq | 1st quarter, 2nd quarter, ... | 2 |
15078
+ * | | | qqqqq | 1, 2, 3, 4 | 3 |
15079
+ * | Month (formatting) | 110 | M | 1, 2, ..., 12 | |
15080
+ * | | | Mo | 1st, 2nd, ..., 12th | 5 |
15081
+ * | | | MM | 01, 02, ..., 12 | |
15082
+ * | | | MMM | Jan, Feb, ..., Dec | |
15083
+ * | | | MMMM | January, February, ..., December | 2 |
15084
+ * | | | MMMMM | J, F, ..., D | |
15085
+ * | Month (stand-alone) | 110 | L | 1, 2, ..., 12 | |
15086
+ * | | | Lo | 1st, 2nd, ..., 12th | 5 |
15087
+ * | | | LL | 01, 02, ..., 12 | |
15088
+ * | | | LLL | Jan, Feb, ..., Dec | |
15089
+ * | | | LLLL | January, February, ..., December | 2 |
15090
+ * | | | LLLLL | J, F, ..., D | |
15091
+ * | Local week of year | 100 | w | 1, 2, ..., 53 | |
15092
+ * | | | wo | 1st, 2nd, ..., 53th | 5 |
15093
+ * | | | ww | 01, 02, ..., 53 | |
15094
+ * | ISO week of year | 100 | I | 1, 2, ..., 53 | 5 |
15095
+ * | | | Io | 1st, 2nd, ..., 53th | 5 |
15096
+ * | | | II | 01, 02, ..., 53 | 5 |
15097
+ * | Day of month | 90 | d | 1, 2, ..., 31 | |
15098
+ * | | | do | 1st, 2nd, ..., 31st | 5 |
15099
+ * | | | dd | 01, 02, ..., 31 | |
15100
+ * | Day of year | 90 | D | 1, 2, ..., 365, 366 | 7 |
15101
+ * | | | Do | 1st, 2nd, ..., 365th, 366th | 5 |
15102
+ * | | | DD | 01, 02, ..., 365, 366 | 7 |
15103
+ * | | | DDD | 001, 002, ..., 365, 366 | |
15104
+ * | | | DDDD | ... | 2 |
15105
+ * | Day of week (formatting) | 90 | E..EEE | Mon, Tue, Wed, ..., Su | |
15106
+ * | | | EEEE | Monday, Tuesday, ..., Sunday | 2 |
15107
+ * | | | EEEEE | M, T, W, T, F, S, S | |
15108
+ * | | | EEEEEE | Mo, Tu, We, Th, Fr, Sa, Su | |
15109
+ * | ISO day of week (formatting) | 90 | i | 1, 2, 3, ..., 7 | 5 |
15110
+ * | | | io | 1st, 2nd, ..., 7th | 5 |
15111
+ * | | | ii | 01, 02, ..., 07 | 5 |
15112
+ * | | | iii | Mon, Tue, Wed, ..., Su | 5 |
15113
+ * | | | iiii | Monday, Tuesday, ..., Sunday | 2,5 |
15114
+ * | | | iiiii | M, T, W, T, F, S, S | 5 |
15115
+ * | | | iiiiii | Mo, Tu, We, Th, Fr, Sa, Su | 5 |
15116
+ * | Local day of week (formatting) | 90 | e | 2, 3, 4, ..., 1 | |
15117
+ * | | | eo | 2nd, 3rd, ..., 1st | 5 |
15118
+ * | | | ee | 02, 03, ..., 01 | |
15119
+ * | | | eee | Mon, Tue, Wed, ..., Su | |
15120
+ * | | | eeee | Monday, Tuesday, ..., Sunday | 2 |
15121
+ * | | | eeeee | M, T, W, T, F, S, S | |
15122
+ * | | | eeeeee | Mo, Tu, We, Th, Fr, Sa, Su | |
15123
+ * | Local day of week (stand-alone) | 90 | c | 2, 3, 4, ..., 1 | |
15124
+ * | | | co | 2nd, 3rd, ..., 1st | 5 |
15125
+ * | | | cc | 02, 03, ..., 01 | |
15126
+ * | | | ccc | Mon, Tue, Wed, ..., Su | |
15127
+ * | | | cccc | Monday, Tuesday, ..., Sunday | 2 |
15128
+ * | | | ccccc | M, T, W, T, F, S, S | |
15129
+ * | | | cccccc | Mo, Tu, We, Th, Fr, Sa, Su | |
15130
+ * | AM, PM | 80 | a..aaa | AM, PM | |
15131
+ * | | | aaaa | a.m., p.m. | 2 |
15132
+ * | | | aaaaa | a, p | |
15133
+ * | AM, PM, noon, midnight | 80 | b..bbb | AM, PM, noon, midnight | |
15134
+ * | | | bbbb | a.m., p.m., noon, midnight | 2 |
15135
+ * | | | bbbbb | a, p, n, mi | |
15136
+ * | Flexible day period | 80 | B..BBB | at night, in the morning, ... | |
15137
+ * | | | BBBB | at night, in the morning, ... | 2 |
15138
+ * | | | BBBBB | at night, in the morning, ... | |
15139
+ * | Hour [1-12] | 70 | h | 1, 2, ..., 11, 12 | |
15140
+ * | | | ho | 1st, 2nd, ..., 11th, 12th | 5 |
15141
+ * | | | hh | 01, 02, ..., 11, 12 | |
15142
+ * | Hour [0-23] | 70 | H | 0, 1, 2, ..., 23 | |
15143
+ * | | | Ho | 0th, 1st, 2nd, ..., 23rd | 5 |
15144
+ * | | | HH | 00, 01, 02, ..., 23 | |
15145
+ * | Hour [0-11] | 70 | K | 1, 2, ..., 11, 0 | |
15146
+ * | | | Ko | 1st, 2nd, ..., 11th, 0th | 5 |
15147
+ * | | | KK | 01, 02, ..., 11, 00 | |
15148
+ * | Hour [1-24] | 70 | k | 24, 1, 2, ..., 23 | |
15149
+ * | | | ko | 24th, 1st, 2nd, ..., 23rd | 5 |
15150
+ * | | | kk | 24, 01, 02, ..., 23 | |
15151
+ * | Minute | 60 | m | 0, 1, ..., 59 | |
15152
+ * | | | mo | 0th, 1st, ..., 59th | 5 |
15153
+ * | | | mm | 00, 01, ..., 59 | |
15154
+ * | Second | 50 | s | 0, 1, ..., 59 | |
15155
+ * | | | so | 0th, 1st, ..., 59th | 5 |
15156
+ * | | | ss | 00, 01, ..., 59 | |
15157
+ * | Seconds timestamp | 40 | t | 512969520 | |
15158
+ * | | | tt | ... | 2 |
15159
+ * | Fraction of second | 30 | S | 0, 1, ..., 9 | |
15160
+ * | | | SS | 00, 01, ..., 99 | |
15161
+ * | | | SSS | 000, 001, ..., 999 | |
15162
+ * | | | SSSS | ... | 2 |
15163
+ * | Milliseconds timestamp | 20 | T | 512969520900 | |
15164
+ * | | | TT | ... | 2 |
15165
+ * | Timezone (ISO-8601 w/ Z) | 10 | X | -08, +0530, Z | |
15166
+ * | | | XX | -0800, +0530, Z | |
15167
+ * | | | XXX | -08:00, +05:30, Z | |
15168
+ * | | | XXXX | -0800, +0530, Z, +123456 | 2 |
15169
+ * | | | XXXXX | -08:00, +05:30, Z, +12:34:56 | |
15170
+ * | Timezone (ISO-8601 w/o Z) | 10 | x | -08, +0530, +00 | |
15171
+ * | | | xx | -0800, +0530, +0000 | |
15172
+ * | | | xxx | -08:00, +05:30, +00:00 | 2 |
15173
+ * | | | xxxx | -0800, +0530, +0000, +123456 | |
15174
+ * | | | xxxxx | -08:00, +05:30, +00:00, +12:34:56 | |
15175
+ * | Long localized date | NA | P | 05/29/1453 | 5,8 |
15176
+ * | | | PP | May 29, 1453 | |
15177
+ * | | | PPP | May 29th, 1453 | |
15178
+ * | | | PPPP | Sunday, May 29th, 1453 | 2,5,8 |
15179
+ * | Long localized time | NA | p | 12:00 AM | 5,8 |
15180
+ * | | | pp | 12:00:00 AM | |
15181
+ * | Combination of date and time | NA | Pp | 05/29/1453, 12:00 AM | |
15182
+ * | | | PPpp | May 29, 1453, 12:00:00 AM | |
15183
+ * | | | PPPpp | May 29th, 1453 at ... | |
15184
+ * | | | PPPPpp | Sunday, May 29th, 1453 at ... | 2,5,8 |
15185
+ * Notes:
15186
+ * 1. "Formatting" units (e.g. formatting quarter) in the default en-US locale
15187
+ * are the same as "stand-alone" units, but are different in some languages.
15188
+ * "Formatting" units are declined according to the rules of the language
15189
+ * in the context of a date. "Stand-alone" units are always nominative singular.
15190
+ * In `format` function, they will produce different result:
15191
+ *
15192
+ * `format(new Date(2017, 10, 6), 'do LLLL', {locale: cs}) //=> '6. listopad'`
15193
+ *
15194
+ * `format(new Date(2017, 10, 6), 'do MMMM', {locale: cs}) //=> '6. listopadu'`
15195
+ *
15196
+ * `isMatch` will try to match both formatting and stand-alone units interchangably.
15197
+ *
15198
+ * 2. Any sequence of the identical letters is a pattern, unless it is escaped by
15199
+ * the single quote characters (see below).
15200
+ * If the sequence is longer than listed in table:
15201
+ * - for numerical units (`yyyyyyyy`) `isMatch` will try to match a number
15202
+ * as wide as the sequence
15203
+ * - for text units (`MMMMMMMM`) `isMatch` will try to match the widest variation of the unit.
15204
+ * These variations are marked with "2" in the last column of the table.
15205
+ *
15206
+ * 3. `QQQQQ` and `qqqqq` could be not strictly numerical in some locales.
15207
+ * These tokens represent the shortest form of the quarter.
15208
+ *
15209
+ * 4. The main difference between `y` and `u` patterns are B.C. years:
15210
+ *
15211
+ * | Year | `y` | `u` |
15212
+ * |------|-----|-----|
15213
+ * | AC 1 | 1 | 1 |
15214
+ * | BC 1 | 1 | 0 |
15215
+ * | BC 2 | 2 | -1 |
15216
+ *
15217
+ * Also `yy` will try to guess the century of two digit year by proximity with `referenceDate`:
15218
+ *
15219
+ * `isMatch('50', 'yy') //=> true`
15220
+ *
15221
+ * `isMatch('75', 'yy') //=> true`
15222
+ *
15223
+ * while `uu` will use the year as is:
15224
+ *
15225
+ * `isMatch('50', 'uu') //=> true`
15226
+ *
15227
+ * `isMatch('75', 'uu') //=> true`
15228
+ *
15229
+ * The same difference is true for local and ISO week-numbering years (`Y` and `R`),
15230
+ * except local week-numbering years are dependent on `options.weekStartsOn`
15231
+ * and `options.firstWeekContainsDate` (compare [setISOWeekYear](https://date-fns.org/docs/setISOWeekYear)
15232
+ * and [setWeekYear](https://date-fns.org/docs/setWeekYear)).
15233
+ *
15234
+ * 5. These patterns are not in the Unicode Technical Standard #35:
15235
+ * - `i`: ISO day of week
15236
+ * - `I`: ISO week of year
15237
+ * - `R`: ISO week-numbering year
15238
+ * - `o`: ordinal number modifier
15239
+ * - `P`: long localized date
15240
+ * - `p`: long localized time
15241
+ *
15242
+ * 6. `YY` and `YYYY` tokens represent week-numbering years but they are often confused with years.
15243
+ * You should enable `options.useAdditionalWeekYearTokens` to use them. See: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md
15244
+ *
15245
+ * 7. `D` and `DD` tokens represent days of the year but they are ofthen confused with days of the month.
15246
+ * You should enable `options.useAdditionalDayOfYearTokens` to use them. See: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md
15247
+ *
15248
+ * 8. `P+` tokens do not have a defined priority since they are merely aliases to other tokens based
15249
+ * on the given locale.
15250
+ *
15251
+ * using `en-US` locale: `P` => `MM/dd/yyyy`
15252
+ * using `en-US` locale: `p` => `hh:mm a`
15253
+ * using `pt-BR` locale: `P` => `dd/MM/yyyy`
15254
+ * using `pt-BR` locale: `p` => `HH:mm`
15255
+ *
15256
+ * Values will be checked in the descending order of its unit's priority.
15257
+ * Units of an equal priority overwrite each other in the order of appearance.
15258
+ *
15259
+ * If no values of higher priority are matched (e.g. when matching string 'January 1st' without a year),
15260
+ * the values will be taken from today's using `new Date()` date which works as a context of parsing.
15261
+ *
15262
+ * The result may vary by locale.
15263
+ *
15264
+ * If `formatString` matches with `dateString` but does not provides tokens, `referenceDate` will be returned.
15265
+ *
15266
+ * @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).
15267
+ *
15268
+ * @param dateStr - The date string to verify
15269
+ * @param format - The string of tokens
15270
+ * @param options - An object with options.
15271
+ * see: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md
15272
+ * see: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md
15273
+ *
15274
+ * @returns Is format string a match for date string?
15275
+ *
15276
+ * @throws `options.locale` must contain `match` property
15277
+ * @throws use `yyyy` instead of `YYYY` for formatting years; see: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md
15278
+ * @throws use `yy` instead of `YY` for formatting years; see: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md
15279
+ * @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
15280
+ * @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
15281
+ * @throws format string contains an unescaped latin alphabet character
15282
+ *
15283
+ * @example
15284
+ * // Match 11 February 2014 from middle-endian format:
15285
+ * const result = isMatch('02/11/2014', 'MM/dd/yyyy')
15286
+ * //=> true
15287
+ *
15288
+ * @example
15289
+ * // Match 28th of February in Esperanto locale in the context of 2010 year:
15290
+ * import eo from 'date-fns/locale/eo'
15291
+ * const result = isMatch('28-a de februaro', "do 'de' MMMM", {
15292
+ * locale: eo
15293
+ * })
15294
+ * //=> true
15295
+ */
15296
+ function isMatch(dateStr, formatStr, options) {
15297
+ return isValid(parse(dateStr, formatStr, new Date(), options));
15298
+ }
15299
+
15006
15300
  var formatDistanceLocale = {
15007
15301
  lessThanXSeconds: {
15008
15302
  standalone: {
@@ -15556,6 +15850,15 @@ function formatGermanTimeHourMinute(date) {
15556
15850
  function formatGermanFullDateTime(date) {
15557
15851
  return format(date, 'dd.MM.yyyy HH:mm:ss');
15558
15852
  }
15853
+ /** Does the given date match the given dateFormat? */
15854
+ function dateMatchesFormat(date,
15855
+ /** @see https://date-fns.org/v3.6.0/docs/isMatch for allowed formats. */
15856
+ dateFormat) {
15857
+ if (!date) {
15858
+ return false;
15859
+ }
15860
+ return isMatch(date, dateFormat);
15861
+ }
15559
15862
 
15560
15863
  /**
15561
15864
  * Detects if a mobile device is used
@@ -15877,6 +16180,7 @@ exports.SECONDLESS_DATE_TIME_FORMAT = SECONDLESS_DATE_TIME_FORMAT;
15877
16180
  exports.callSequentially = callSequentially;
15878
16181
  exports.ceil = ceil;
15879
16182
  exports.containSameValues = containSameValues;
16183
+ exports.dateMatchesFormat = dateMatchesFormat;
15880
16184
  exports.downloadBlob = downloadBlob;
15881
16185
  exports.errorMessage = errorMessage;
15882
16186
  exports.firstDecimalDigit = firstDecimalDigit;