@mll-lab/js-utils 2.31.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 (7) hide show
  1. package/dist/array.d.ts +2 -0
  2. package/dist/date.d.ts +5 -0
  3. package/dist/index.common.js +312 -0
  4. package/dist/index.common.js.map +1 -1
  5. package/dist/index.js +312 -0
  6. package/dist/index.js.map +1 -1
  7. package/package.json +1 -1
package/dist/array.d.ts CHANGED
@@ -56,3 +56,5 @@ export declare function makeStringCompareFn<TSortable>(map: (sortable: TSortable
56
56
  * The empty string is first in sort order.
57
57
  */
58
58
  export declare function localeCompareStrings(a: string, b: string): number;
59
+ /** If the given array contains exactly one item, return that, otherwise null. */
60
+ export declare function soleItem<T>(array: Maybe<Array<T>>): T | null;
package/dist/date.d.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import { Maybe } from './types';
1
2
  export declare function isToday(date: Date | string | number): boolean;
2
3
  export declare function isFuture(date: Date | string | number): boolean;
3
4
  export declare function isValidGermanDate(date: string): boolean;
@@ -27,3 +28,7 @@ export declare function parseDotlessDate(value: string): Date | null;
27
28
  export declare function formatDotlessDate(date: Date | string | number): string;
28
29
  export declare function formatGermanTimeHourMinute(date: string): string;
29
30
  export declare function formatGermanFullDateTime(date: Date | string | number): string;
31
+ /** Does the given date match the given dateFormat? */
32
+ export declare function dateMatchesFormat(date: Maybe<string>,
33
+ /** @see https://date-fns.org/v3.6.0/docs/isMatch for allowed formats. */
34
+ dateFormat: string): boolean;
package/dist/index.common.js CHANGED
@@ -9527,6 +9527,13 @@ function makeStringCompareFn(map) {
9527
9527
  function localeCompareStrings(a, b) {
9528
9528
  return a.localeCompare(b);
9529
9529
  }
9530
+ /** If the given array contains exactly one item, return that, otherwise null. */
9531
+ function soleItem(array) {
9532
+ if (!array || array.length !== 1) {
9533
+ return null;
9534
+ }
9535
+ return array[0];
9536
+ }
9530
9537
 
9531
9538
  /**
9532
9539
  * @name toDate
@@ -14996,6 +15003,300 @@ function cleanEscapedString(input) {
14996
15003
  return input.match(escapedStringRegExp)[1].replace(doubleQuoteRegExp, "'");
14997
15004
  }
14998
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
+
14999
15300
  var formatDistanceLocale = {
15000
15301
  lessThanXSeconds: {
15001
15302
  standalone: {
@@ -15549,6 +15850,15 @@ function formatGermanTimeHourMinute(date) {
15549
15850
  function formatGermanFullDateTime(date) {
15550
15851
  return format(date, 'dd.MM.yyyy HH:mm:ss');
15551
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
+ }
15552
15862
 
15553
15863
  /**
15554
15864
  * Detects if a mobile device is used
@@ -15870,6 +16180,7 @@ exports.SECONDLESS_DATE_TIME_FORMAT = SECONDLESS_DATE_TIME_FORMAT;
15870
16180
  exports.callSequentially = callSequentially;
15871
16181
  exports.ceil = ceil;
15872
16182
  exports.containSameValues = containSameValues;
16183
+ exports.dateMatchesFormat = dateMatchesFormat;
15873
16184
  exports.downloadBlob = downloadBlob;
15874
16185
  exports.errorMessage = errorMessage;
15875
16186
  exports.firstDecimalDigit = firstDecimalDigit;
@@ -15928,6 +16239,7 @@ exports.pick = pick;
15928
16239
  exports.pluralize = pluralize;
15929
16240
  exports.pxToNumber = pxToNumber;
15930
16241
  exports.round = round;
16242
+ exports.soleItem = soleItem;
15931
16243
  exports.sortByArray = sortByArray;
15932
16244
  exports.toggleElement = toggleElement;
15933
16245
  exports.withoutIndex = withoutIndex;