@naturalcycles/js-lib 14.243.0 → 14.244.0

package/dist-esm/datetime/localDate.js

@@ -3,69 +3,70 @@ import { _isTruthy } from '../is.util';
 import { Iterable2 } from '../iter/iterable2';
 import { localTime } from './localTime';
 const MDAYS = [0, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
-const DATE_REGEX = /^(\d\d\d\d)-(\d\d)-(\d\d)$/;
+// Regex is open-ended (no $ at the end) to support e.g Date+Time string to be parsed (time part will be dropped)
+const DATE_REGEX = /^(\d\d\d\d)-(\d\d)-(\d\d)/;
 /**
  * LocalDate represents a date without time.
  * It is timezone-independent.
  */
 export class LocalDate {
-    constructor($year, $month, $day) {
-        this.$year = $year;
-        this.$month = $month;
-        this.$day = $day;
+    constructor(year, month, day) {
+        this.year = year;
+        this.month = month;
+        this.day = day;
     }
     get(unit) {
-        return unit === 'year' ? this.$year : unit === 'month' ? this.$month : this.$day;
+        return unit === 'year' ? this.year : unit === 'month' ? this.month : this.day;
     }
     set(unit, v, mutate = false) {
         const t = mutate ? this : this.clone();
         if (unit === 'year') {
-            t.$year = v;
+            t.year = v;
         }
         else if (unit === 'month') {
-            t.$month = v;
+            t.month = v;
         }
         else {
-            t.$day = v;
+            t.day = v;
         }
         return t;
     }
-    year(v) {
-        return v === undefined ? this.$year : this.set('year', v);
+    setYear(v) {
+        return this.set('year', v);
     }
-    month(v) {
-        return v === undefined ? this.$month : this.set('month', v);
+    setMonth(v) {
+        return this.set('month', v);
     }
-    day(v) {
-        return v === undefined ? this.$day : this.set('day', v);
+    setDay(v) {
+        return this.set('day', v);
     }
-    dayOfWeek() {
+    get dayOfWeek() {
         return (this.toDate().getDay() || 7);
     }
     isSame(d) {
-        d = localDate.of(d);
-        return this.$day === d.$day && this.$month === d.$month && this.$year === d.$year;
+        d = localDate.from(d);
+        return this.day === d.day && this.month === d.month && this.year === d.year;
     }
     isBefore(d, inclusive = false) {
-        const r = this.cmp(d);
+        const r = this.compare(d);
         return r === -1 || (r === 0 && inclusive);
     }
     isSameOrBefore(d) {
-        return this.cmp(d) <= 0;
+        return this.compare(d) <= 0;
     }
     isAfter(d, inclusive = false) {
-        const r = this.cmp(d);
+        const r = this.compare(d);
         return r === 1 || (r === 0 && inclusive);
     }
     isSameOrAfter(d) {
-        return this.cmp(d) >= 0;
+        return this.compare(d) >= 0;
     }
     isBetween(min, max, incl = '[)') {
-        let r = this.cmp(min);
+        let r = this.compare(min);
         // eslint-disable-next-line @typescript-eslint/prefer-string-starts-ends-with
         if (r < 0 || (r === 0 && incl[0] === '('))
             return false;
-        r = this.cmp(max);
+        r = this.compare(max);
         if (r > 0 || (r === 0 && incl[1] === ')'))
             return false;
         return true;
@@ -80,13 +81,13 @@ export class LocalDate {
      * Third argument allows to override "today".
      */
     isOlderThan(n, unit, today) {
-        return this.isBefore(localDate.of(today || new Date()).plus(-n, unit));
+        return this.isBefore(localDate.from(today || new Date()).plus(-n, unit));
     }
     /**
      * Checks if this localDate is same or older (<=) than "today" by X units.
      */
     isSameOrOlderThan(n, unit, today) {
-        return this.isSameOrBefore(localDate.of(today || new Date()).plus(-n, unit));
+        return this.isSameOrBefore(localDate.from(today || new Date()).plus(-n, unit));
     }
     /**
      * Checks if this localDate is younger (>) than "today" by X units.
@@ -98,13 +99,13 @@ export class LocalDate {
      * Third argument allows to override "today".
      */
     isYoungerThan(n, unit, today) {
-        return this.isAfter(localDate.of(today || new Date()).plus(-n, unit));
+        return this.isAfter(localDate.from(today || new Date()).plus(-n, unit));
     }
     /**
      * Checks if this localDate is same or younger (>=) than "today" by X units.
      */
     isSameOrYoungerThan(n, unit, today) {
-        return this.isSameOrAfter(localDate.of(today || new Date()).plus(-n, unit));
+        return this.isSameOrAfter(localDate.from(today || new Date()).plus(-n, unit));
     }
     getAgeInYears(today) {
         return this.getAgeIn('year', today);
@@ -116,26 +117,26 @@ export class LocalDate {
         return this.getAgeIn('day', today);
     }
     getAgeIn(unit, today) {
-        return localDate.of(today || new Date()).diff(this, unit);
+        return localDate.from(today || new Date()).diff(this, unit);
     }
     /**
      * Returns 1 if this > d
      * returns 0 if they are equal
      * returns -1 if this < d
      */
-    cmp(d) {
-        d = localDate.of(d);
-        if (this.$year < d.$year)
+    compare(d) {
+        d = localDate.from(d);
+        if (this.year < d.year)
             return -1;
-        if (this.$year > d.$year)
+        if (this.year > d.year)
             return 1;
-        if (this.$month < d.$month)
+        if (this.month < d.month)
             return -1;
-        if (this.$month > d.$month)
+        if (this.month > d.month)
             return 1;
-        if (this.$day < d.$day)
+        if (this.day < d.day)
             return -1;
-        if (this.$day > d.$day)
+        if (this.day > d.day)
             return 1;
         return 0;
     }
@@ -151,48 +152,48 @@ export class LocalDate {
      * a.diff(b) means "a minus b"
      */
     diff(d, unit) {
-        d = localDate.of(d);
-        const sign = this.cmp(d);
+        d = localDate.from(d);
+        const sign = this.compare(d);
         if (!sign)
             return 0;
         // Put items in descending order: "big minus small"
         const [big, small] = sign === 1 ? [this, d] : [d, this];
         if (unit === 'year') {
-            let years = big.$year - small.$year;
-            if (big.$month < small.$month ||
-                (big.$month === small.$month &&
-                    big.$day < small.$day &&
-                    !(big.$day === localDate.getMonthLength(big.$year, big.$month) &&
-                        small.$day === localDate.getMonthLength(small.$year, small.$month)))) {
+            let years = big.year - small.year;
+            if (big.month < small.month ||
+                (big.month === small.month &&
+                    big.day < small.day &&
+                    !(big.day === localDate.getMonthLength(big.year, big.month) &&
+                        small.day === localDate.getMonthLength(small.year, small.month)))) {
                 years--;
             }
             return years * sign || 0;
         }
         if (unit === 'month') {
-            let months = (big.$year - small.$year) * 12 + (big.$month - small.$month);
-            if (big.$day < small.$day) {
-                const bigMonthLen = localDate.getMonthLength(big.$year, big.$month);
-                if (big.$day !== bigMonthLen || small.$day < bigMonthLen) {
+            let months = (big.year - small.year) * 12 + (big.month - small.month);
+            if (big.day < small.day) {
+                const bigMonthLen = localDate.getMonthLength(big.year, big.month);
+                if (big.day !== bigMonthLen || small.day < bigMonthLen) {
                     months--;
                 }
             }
             return months * sign || 0;
         }
         // unit is 'day' or 'week'
-        let days = big.$day - small.$day;
+        let days = big.day - small.day;
         // If small date is after 1st of March - next year's "leapness" should be used
-        const offsetYear = small.$month >= 3 ? 1 : 0;
-        for (let year = small.$year; year < big.$year; year++) {
+        const offsetYear = small.month >= 3 ? 1 : 0;
+        for (let year = small.year; year < big.year; year++) {
             days += localDate.getYearLength(year + offsetYear);
         }
-        if (small.$month < big.$month) {
-            for (let month = small.$month; month < big.$month; month++) {
-                days += localDate.getMonthLength(big.$year, month);
+        if (small.month < big.month) {
+            for (let month = small.month; month < big.month; month++) {
+                days += localDate.getMonthLength(big.year, month);
             }
         }
-        else if (big.$month < small.$month) {
-            for (let month = big.$month; month < small.$month; month++) {
-                days -= localDate.getMonthLength(big.$year, month);
+        else if (big.month < small.month) {
+            for (let month = big.month; month < small.month; month++) {
+                days -= localDate.getMonthLength(big.year, month);
             }
         }
         if (unit === 'week') {
@@ -225,68 +226,68 @@ export class LocalDate {
         return this.plus(-num, 'year');
     }
     plus(num, unit, mutate = false) {
-        let { $day, $month, $year } = this;
+        let { day, month, year } = this;
         if (unit === 'week') {
             num *= 7;
             unit = 'day';
         }
         if (unit === 'day') {
-            $day += num;
+            day += num;
         }
         else if (unit === 'month') {
-            $month += num;
+            month += num;
         }
         else if (unit === 'year') {
-            $year += num;
+            year += num;
         }
         // check month overflow
-        while ($month > 12) {
-            $year += 1;
-            $month -= 12;
+        while (month > 12) {
+            year += 1;
+            month -= 12;
         }
-        while ($month < 1) {
-            $year -= 1;
-            $month += 12;
+        while (month < 1) {
+            year -= 1;
+            month += 12;
         }
         // check day overflow
         // Applies not only for 'day' unit, but also e.g 2022-05-31 plus 1 month should be 2022-06-30 (not 31!)
-        if ($day < 1) {
-            while ($day < 1) {
-                $month -= 1;
-                if ($month < 1) {
-                    $year -= 1;
-                    $month += 12;
+        if (day < 1) {
+            while (day < 1) {
+                month -= 1;
+                if (month < 1) {
+                    year -= 1;
+                    month += 12;
                 }
-                $day += localDate.getMonthLength($year, $month);
+                day += localDate.getMonthLength(year, month);
             }
         }
         else {
-            let monLen = localDate.getMonthLength($year, $month);
+            let monLen = localDate.getMonthLength(year, month);
             if (unit !== 'day') {
-                if ($day > monLen) {
+                if (day > monLen) {
                     // Case of 2022-05-31 plus 1 month should be 2022-06-30, not 31
-                    $day = monLen;
+                    day = monLen;
                 }
             }
             else {
-                while ($day > monLen) {
-                    $day -= monLen;
-                    $month += 1;
-                    if ($month > 12) {
-                        $year += 1;
-                        $month -= 12;
+                while (day > monLen) {
+                    day -= monLen;
+                    month += 1;
+                    if (month > 12) {
+                        year += 1;
+                        month -= 12;
                     }
-                    monLen = localDate.getMonthLength($year, $month);
+                    monLen = localDate.getMonthLength(year, month);
                 }
             }
         }
         if (mutate) {
-            this.$year = $year;
-            this.$month = $month;
-            this.$day = $day;
+            this.year = year;
+            this.month = month;
+            this.day = day;
             return this;
         }
-        return new LocalDate($year, $month, $day);
+        return new LocalDate(year, month, day);
     }
     minus(num, unit, mutate = false) {
         return this.plus(-num, unit, mutate);
@@ -295,27 +296,27 @@ export class LocalDate {
         if (unit === 'day')
             return this;
         if (unit === 'month')
-            return new LocalDate(this.$year, this.$month, 1);
+            return new LocalDate(this.year, this.month, 1);
         // year
-        return new LocalDate(this.$year, 1, 1);
+        return new LocalDate(this.year, 1, 1);
     }
     endOf(unit) {
         if (unit === 'day')
             return this;
         if (unit === 'month')
-            return new LocalDate(this.$year, this.$month, localDate.getMonthLength(this.$year, this.$month));
+            return new LocalDate(this.year, this.month, localDate.getMonthLength(this.year, this.month));
         // year
-        return new LocalDate(this.$year, 12, 31);
+        return new LocalDate(this.year, 12, 31);
     }
     /**
      * Returns how many days are in the current month.
      * E.g 31 for January.
      */
-    daysInMonth() {
-        return localDate.getMonthLength(this.$year, this.$month);
+    get daysInMonth() {
+        return localDate.getMonthLength(this.year, this.month);
     }
     clone() {
-        return new LocalDate(this.$year, this.$month, this.$day);
+        return new LocalDate(this.year, this.month, this.day);
     }
     /**
      * Converts LocalDate into instance of Date.
@@ -324,7 +325,7 @@ export class LocalDate {
      * Timezone will match local timezone.
      */
     toDate() {
-        return new Date(this.$year, this.$month - 1, this.$day);
+        return new Date(this.year, this.month - 1, this.day);
     }
     /**
      * Converts LocalDate to Date in UTC timezone.
@@ -335,9 +336,9 @@ export class LocalDate {
     }
     toDateObject() {
         return {
-            year: this.$year,
-            month: this.$month,
-            day: this.$day,
+            year: this.year,
+            month: this.month,
+            day: this.day,
         };
     }
     /**
@@ -345,16 +346,16 @@ export class LocalDate {
      * LocalTime's Date will be in local timezone.
      */
     toLocalTime() {
-        return localTime.of(this.toDate());
+        return localTime.fromDate(this.toDate());
     }
     /**
      * Returns e.g: `1984-06-21`
      */
     toISODate() {
         return [
-            String(this.$year).padStart(4, '0'),
-            String(this.$month).padStart(2, '0'),
-            String(this.$day).padStart(2, '0'),
+            String(this.year).padStart(4, '0'),
+            String(this.month).padStart(2, '0'),
+            String(this.day).padStart(2, '0'),
         ].join('-');
     }
     /**
@@ -379,9 +380,9 @@ export class LocalDate {
      */
     toStringCompact() {
         return [
-            String(this.$year).padStart(4, '0'),
-            String(this.$month).padStart(2, '0'),
-            String(this.$day).padStart(2, '0'),
+            String(this.year).padStart(4, '0'),
+            String(this.month).padStart(2, '0'),
+            String(this.day).padStart(2, '0'),
         ].join('');
     }
     /**
@@ -393,13 +394,13 @@ export class LocalDate {
     /**
      * Returns unix timestamp of 00:00:00 of that date (in UTC, because unix timestamp always reflects UTC).
      */
-    unix() {
+    get unix() {
         return Math.floor(this.toDate().valueOf() / 1000);
     }
     /**
      * Same as .unix(), but in milliseconds.
      */
-    unixMillis() {
+    get unixMillis() {
         return this.toDate().valueOf();
     }
     toJSON() {
@@ -413,12 +414,6 @@ export class LocalDate {
     }
 }
 class LocalDateFactory {
-    /**
-     * Create LocalDate from year, month and day components.
-     */
-    create(year, month, day) {
-        return new LocalDate(year, month, day);
-    }
     /**
      * Create LocalDate from LocalDateInput.
      * Input can already be a LocalDate - it is returned as-is in that case.
@@ -428,18 +423,16 @@ class LocalDateFactory {
      *
      * Will throw if it fails to parse/construct LocalDate.
      */
-    of(d) {
-        const t = this.parseOrNull(d);
-        _assert(t !== null, `Cannot parse "${d}" into LocalDate`, {
-            input: d,
-        });
-        return t;
+    from(input) {
+        const ld = this.fromOrNull(input);
+        this.assertNotNull(ld, input);
+        return ld;
     }
     /**
      * Tries to construct LocalDate from LocalDateInput, returns null otherwise.
      * Does not throw (returns null instead).
      */
-    parseOrNull(d) {
+    fromOrNull(d) {
         if (!d)
             return null;
         if (d instanceof LocalDate)
@@ -447,12 +440,25 @@ class LocalDateFactory {
         if (d instanceof Date) {
             return this.fromDate(d);
         }
-        const matches = typeof d === 'string' && DATE_REGEX.exec(d.slice(0, 10));
-        if (!matches)
+        if (typeof d === 'string') {
+            return this.fromStringOrNull(d);
+        }
+        return null;
+    }
+    fromString(s) {
+        const ld = this.fromStringOrNull(s);
+        this.assertNotNull(ld, s);
+        return ld;
+    }
+    fromStringOrNull(s) {
+        if (!s)
+            return null;
+        const m = DATE_REGEX.exec(s);
+        if (!m)
             return null;
-        const year = Number(matches[1]);
-        const month = Number(matches[2]);
-        const day = Number(matches[3]);
+        const year = Number(m[1]);
+        const month = Number(m[2]);
+        const day = Number(m[3]);
         if (!year ||
             !month ||
             month < 1 ||
@@ -468,22 +474,11 @@ class LocalDateFactory {
      * Parses "compact iso8601 format", e.g `19840621` into LocalDate.
      * Throws if it fails to do so.
      */
-    parseCompact(d) {
-        const [year, month, day] = [d.slice(0, 4), d.slice(4, 2), d.slice(6, 2)].map(Number);
-        _assert(day && month && year, `Cannot parse "${d}" into LocalDate`);
+    fromCompactString(s) {
+        const [year, month, day] = [s.slice(0, 4), s.slice(4, 6), s.slice(6, 8)].map(Number);
+        _assert(day && month && year, `Cannot parse compact string "${s}" into LocalDate`);
         return new LocalDate(year, month, day);
     }
-    getYearLength(year) {
-        return this.isLeapYear(year) ? 366 : 365;
-    }
-    getMonthLength(year, month) {
-        if (month === 2)
-            return this.isLeapYear(year) ? 29 : 28;
-        return MDAYS[month];
-    }
-    isLeapYear(year) {
-        return year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
-    }
     /**
      * Constructs LocalDate from Date.
      * Takes Date as-is, in its timezone - local or UTC.
@@ -498,11 +493,43 @@ class LocalDateFactory {
     fromDateInUTC(d) {
         return new LocalDate(d.getUTCFullYear(), d.getUTCMonth() + 1, d.getUTCDate());
     }
+    /**
+     * Create LocalDate from year, month and day components.
+     */
+    fromComponents(year, month, day) {
+        return new LocalDate(year, month, day);
+    }
+    fromDateObject(o) {
+        const { year, month, day } = o;
+        return new LocalDate(year, month, day);
+    }
+    assertNotNull(ld, input) {
+        _assert(ld !== null, `Cannot parse "${input}" into LocalDate`, {
+            input,
+        });
+    }
+    getYearLength(year) {
+        return this.isLeapYear(year) ? 366 : 365;
+    }
+    getMonthLength(year, month) {
+        if (month === 2)
+            return this.isLeapYear(year) ? 29 : 28;
+        return MDAYS[month];
+    }
+    isLeapYear(year) {
+        return year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+    }
+    /**
+     * Returns true if input is valid to create LocalDate.
+     */
+    isValid(input) {
+        return this.fromOrNull(input) !== null;
+    }
     /**
      * Returns true if isoString is a valid iso8601 string like `yyyy-mm-dd`.
      */
-    isValid(isoString) {
-        return this.parseOrNull(isoString) !== null;
+    isValidString(isoString) {
+        return this.fromStringOrNull(isoString) !== null;
     }
     /**
      * Creates LocalDate that represents `today` (in local timezone).
@@ -521,7 +548,7 @@ class LocalDateFactory {
      */
     sort(items, dir = 'asc', mutate = false) {
         const mod = dir === 'desc' ? -1 : 1;
-        return (mutate ? items : [...items]).sort((a, b) => a.cmp(b) * mod);
+        return (mutate ? items : [...items]).sort((a, b) => a.compare(b) * mod);
     }
     /**
      * Returns the earliest (min) LocalDate from the array, or undefined if the array is empty.
@@ -537,7 +564,7 @@ class LocalDateFactory {
         const items2 = items.filter(_isTruthy);
         _assert(items2.length, 'localDate.min called on empty array');
         return items2
-            .map(i => this.of(i))
+            .map(i => this.from(i))
             .reduce((min, item) => (min.isSameOrBefore(item) ? min : item));
     }
     /**
@@ -553,7 +580,9 @@ class LocalDateFactory {
     max(items) {
         const items2 = items.filter(_isTruthy);
         _assert(items2.length, 'localDate.max called on empty array');
-        return items2.map(i => this.of(i)).reduce((max, item) => (max.isSameOrAfter(item) ? max : item));
+        return items2
+            .map(i => this.from(i))
+            .reduce((max, item) => (max.isSameOrAfter(item) ? max : item));
     }
     /**
      * Returns the range (array) of LocalDates between min and max.
@@ -571,8 +600,8 @@ class LocalDateFactory {
             step *= 7;
             stepUnit = 'day';
         }
-        const $min = this.of(min).startOf(stepUnit);
-        const $max = this.of(max).startOf(stepUnit);
+        const $min = this.from(min).startOf(stepUnit);
+        const $max = this.from(max).startOf(stepUnit);
         let value = $min;
         // eslint-disable-next-line @typescript-eslint/prefer-string-starts-ends-with
         if (value.isAfter($min, incl[0] === '[')) {
@@ -599,20 +628,17 @@ class LocalDateFactory {
      * Similar to `localDate.orToday`, but that will instead return Today on falsy input.
      */
     orUndefined(d) {
-        return d ? this.of(d) : undefined;
+        return d ? this.from(d) : undefined;
     }
     /**
      * Creates a LocalDate from the input, unless it's falsy - then returns localDate.today.
      */
     orToday(d) {
-        return d ? this.of(d) : this.today();
+        return d ? this.from(d) : this.today();
     }
 }
 const localDateFactory = new LocalDateFactory();
-// export const localDate = Object.assign((d: LocalDateInput) => {
-//   return localDateFactory.of(d)
-// }, localDateFactory) as LocalDateFn
-export const localDate = localDateFactory.of.bind(localDateFactory);
+export const localDate = localDateFactory.from.bind(localDateFactory);
 // The line below is the blackest of black magic I have ever written in 2024.
 // And probably 2023 as well.
 Object.setPrototypeOf(localDate, localDateFactory);