@naturalcycles/js-lib 14.232.0 → 14.233.0

package/dist/datetime/localDate.js

@@ -1,13 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.todayString = exports.localDateOrToday = exports.localDateOrUndefined = exports.localDateToday = exports.localDate = exports.localDateRangeIterable = exports.localDateRange = exports.LocalDate = void 0;
+exports.todayString = exports.localDate = exports.LocalDate = void 0;
 const assert_1 = require("../error/assert");
 const iterable2_1 = require("../iter/iterable2");
 const localTime_1 = require("./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)$/;
 /**
- * @experimental
+ * LocalDate represents a date without time.
+ * It is timezone-independent.
  */
 class LocalDate {
     constructor($year, $month, $day) {
@@ -15,90 +16,6 @@ class LocalDate {
         this.$month = $month;
         this.$day = $day;
     }
-    static create(year, month, day) {
-        return new LocalDate(year, month, day);
-    }
-    /**
-     * Parses input into LocalDate.
-     * Input can already be a LocalDate - it is returned as-is in that case.
-     */
-    static of(d) {
-        const t = this.parseOrNull(d);
-        (0, assert_1._assert)(t !== null, `Cannot parse "${d}" into LocalDate`, {
-            input: d,
-        });
-        return t;
-    }
-    static parseCompact(d) {
-        const [year, month, day] = [d.slice(0, 4), d.slice(4, 2), d.slice(6, 2)].map(Number);
-        (0, assert_1._assert)(day && month && year, `Cannot parse "${d}" into LocalDate`);
-        return new LocalDate(year, month, day);
-    }
-    static fromDate(d) {
-        return new LocalDate(d.getFullYear(), d.getMonth() + 1, d.getDate());
-    }
-    static fromDateUTC(d) {
-        return new LocalDate(d.getUTCFullYear(), d.getUTCMonth() + 1, d.getUTCDate());
-    }
-    /**
-     * Returns null if invalid.
-     */
-    static parseOrNull(d) {
-        if (!d)
-            return null;
-        if (d instanceof LocalDate)
-            return d;
-        if (d instanceof Date) {
-            return this.fromDate(d);
-        }
-        const matches = typeof d === 'string' && DATE_REGEX.exec(d.slice(0, 10));
-        if (!matches)
-            return null;
-        const year = Number(matches[1]);
-        const month = Number(matches[2]);
-        const day = Number(matches[3]);
-        if (!year ||
-            !month ||
-            month < 1 ||
-            month > 12 ||
-            !day ||
-            day < 1 ||
-            day > this.getMonthLength(year, month)) {
-            return null;
-        }
-        return new LocalDate(year, month, day);
-    }
-    static isValid(iso) {
-        return this.parseOrNull(iso) !== null;
-    }
-    static today() {
-        return this.fromDate(new Date());
-    }
-    static todayUTC() {
-        return this.fromDateUTC(new Date());
-    }
-    static sort(items, mutate = false, dir = 'asc') {
-        const mod = dir === 'desc' ? -1 : 1;
-        return (mutate ? items : [...items]).sort((a, b) => a.cmp(b) * mod);
-    }
-    static earliestOrUndefined(items) {
-        return items.length ? LocalDate.earliest(items) : undefined;
-    }
-    static earliest(items) {
-        (0, assert_1._assert)(items.length, 'LocalDate.earliest called on empty array');
-        return items
-            .map(i => LocalDate.of(i))
-            .reduce((min, item) => (min.isSameOrBefore(item) ? min : item));
-    }
-    static latestOrUndefined(items) {
-        return items.length ? LocalDate.latest(items) : undefined;
-    }
-    static latest(items) {
-        (0, assert_1._assert)(items.length, 'LocalDate.latest called on empty array');
-        return items
-            .map(i => LocalDate.of(i))
-            .reduce((max, item) => (max.isSameOrAfter(item) ? max : item));
-    }
     get(unit) {
         return unit === 'year' ? this.$year : unit === 'month' ? this.$month : this.$day;
     }
@@ -128,7 +45,7 @@ class LocalDate {
         return (this.toDate().getDay() || 7);
     }
     isSame(d) {
-        d = LocalDate.of(d);
+        d = exports.localDate.of(d);
         return this.$day === d.$day && this.$month === d.$month && this.$year === d.$year;
     }
     isBefore(d, inclusive = false) {
@@ -165,13 +82,13 @@ 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(exports.localDate.of(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(exports.localDate.of(today || new Date()).plus(-n, unit));
     }
     /**
      * Checks if this localDate is younger (>) than "today" by X units.
@@ -183,13 +100,13 @@ 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(exports.localDate.of(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(exports.localDate.of(today || new Date()).plus(-n, unit));
     }
     /**
      * Returns 1 if this > d
@@ -197,7 +114,7 @@ class LocalDate {
      * returns -1 if this < d
      */
     cmp(d) {
-        d = LocalDate.of(d);
+        d = exports.localDate.of(d);
         if (this.$year < d.$year)
             return -1;
         if (this.$year > d.$year)
@@ -224,7 +141,7 @@ class LocalDate {
      * a.diff(b) means "a minus b"
      */
     diff(d, unit) {
-        d = LocalDate.of(d);
+        d = exports.localDate.of(d);
         const sign = this.cmp(d);
         if (!sign)
             return 0;
@@ -235,8 +152,8 @@ class LocalDate {
             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)))) {
+                    !(big.$day === exports.localDate.getMonthLength(big.$year, big.$month) &&
+                        small.$day === exports.localDate.getMonthLength(small.$year, small.$month)))) {
                 years--;
             }
             return years * sign || 0;
@@ -244,7 +161,7 @@ class LocalDate {
         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);
+                const bigMonthLen = exports.localDate.getMonthLength(big.$year, big.$month);
                 if (big.$day !== bigMonthLen || small.$day < bigMonthLen) {
                     months--;
                 }
@@ -256,16 +173,16 @@ class LocalDate {
         // 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++) {
-            days += LocalDate.getYearLength(year + offsetYear);
+            days += exports.localDate.getYearLength(year + offsetYear);
         }
         if (small.$month < big.$month) {
             for (let month = small.$month; month < big.$month; month++) {
-                days += LocalDate.getMonthLength(big.$year, month);
+                days += exports.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);
+                days -= exports.localDate.getMonthLength(big.$year, month);
             }
         }
         if (unit === 'week') {
@@ -306,11 +223,11 @@ class LocalDate {
                     $year -= 1;
                     $month += 12;
                 }
-                $day += LocalDate.getMonthLength($year, $month);
+                $day += exports.localDate.getMonthLength($year, $month);
             }
         }
         else {
-            let monLen = LocalDate.getMonthLength($year, $month);
+            let monLen = exports.localDate.getMonthLength($year, $month);
             if (unit !== 'day') {
                 if ($day > monLen) {
                     // Case of 2022-05-31 plus 1 month should be 2022-06-30, not 31
@@ -325,7 +242,7 @@ class LocalDate {
                         $year += 1;
                         $month -= 12;
                     }
-                    monLen = LocalDate.getMonthLength($year, $month);
+                    monLen = exports.localDate.getMonthLength($year, $month);
                 }
             }
         }
@@ -344,35 +261,24 @@ class LocalDate {
         if (unit === 'day')
             return this;
         if (unit === 'month')
-            return LocalDate.create(this.$year, this.$month, 1);
+            return new LocalDate(this.$year, this.$month, 1);
         // year
-        return LocalDate.create(this.$year, 1, 1);
+        return new LocalDate(this.$year, 1, 1);
     }
     endOf(unit) {
         if (unit === 'day')
             return this;
         if (unit === 'month')
-            return LocalDate.create(this.$year, this.$month, LocalDate.getMonthLength(this.$year, this.$month));
+            return new LocalDate(this.$year, this.$month, exports.localDate.getMonthLength(this.$year, this.$month));
         // year
-        return LocalDate.create(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);
-    }
-    static getYearLength(year) {
-        return this.isLeapYear(year) ? 366 : 365;
-    }
-    static getMonthLength(year, month) {
-        if (month === 2)
-            return this.isLeapYear(year) ? 29 : 28;
-        return MDAYS[month];
-    }
-    static isLeapYear(year) {
-        return year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+        return exports.localDate.getMonthLength(this.$year, this.$month);
     }
     clone() {
         return new LocalDate(this.$year, this.$month, this.$day);
@@ -391,33 +297,45 @@ class LocalDate {
      * Unlike normal `.toDate` that uses browser's timezone by default.
      */
     toDateInUTC() {
-        return new Date(this.toISODateTimeUTC());
+        return new Date(this.toISODateTimeInUTC());
     }
+    /**
+     * Converts LocalDate to LocalTime with 0 hours, 0 minutes, 0 seconds.
+     * LocalTime's Date will be in local timezone.
+     */
     toLocalTime() {
-        return localTime_1.LocalTime.of(this.toDate());
+        return localTime_1.localTime.of(this.toDate());
     }
+    /**
+     * Returns e.g: `1984-06-21`
+     */
     toISODate() {
-        return this.toString();
+        return [
+            String(this.$year).padStart(4, '0'),
+            String(this.$month).padStart(2, '0'),
+            String(this.$day).padStart(2, '0'),
+        ].join('-');
     }
     /**
-     * Returns e.g: `1984-06-21T17:56:21`
+     * Returns e.g: `1984-06-21T00:00:00`
+     * Hours, minutes and seconds are 0.
      */
     toISODateTime() {
-        return this.toString() + 'T00:00:00';
+        return this.toISODate() + 'T00:00:00';
     }
     /**
-     * Returns e.g: `1984-06-21T17:56:21Z` (notice the Z at the end, which indicates UTC)
+     * Returns e.g: `1984-06-21T00:00:00Z` (notice the Z at the end, which indicates UTC).
+     * Hours, minutes and seconds are 0.
      */
-    toISODateTimeUTC() {
+    toISODateTimeInUTC() {
         return this.toISODateTime() + 'Z';
     }
     toString() {
-        return [
-            String(this.$year).padStart(4, '0'),
-            String(this.$month).padStart(2, '0'),
-            String(this.$day).padStart(2, '0'),
-        ].join('-');
+        return this.toISODate();
     }
+    /**
+     * Returns e.g: `19840621`
+     */
     toStringCompact() {
         return [
             String(this.$year).padStart(4, '0'),
@@ -425,18 +343,26 @@ class LocalDate {
             String(this.$day).padStart(2, '0'),
         ].join('');
     }
+    /**
+     * Returns e.g: `1984-06`
+     */
     toMonthId() {
-        return this.toString().slice(0, 7);
+        return this.toISODate().slice(0, 7);
     }
-    // May be not optimal, as LocalTime better suits it
+    /**
+     * Returns unix timestamp of 00:00:00 of that date (in UTC, because unix timestamp always reflects UTC).
+     */
     unix() {
         return Math.floor(this.toDate().valueOf() / 1000);
     }
+    /**
+     * Same as .unix(), but in milliseconds.
+     */
     unixMillis() {
         return this.toDate().valueOf();
     }
     toJSON() {
-        return this.toString();
+        return this.toISODate();
     }
     format(fmt) {
         if (fmt instanceof Intl.DateTimeFormat) {
@@ -446,78 +372,210 @@ class LocalDate {
     }
 }
 exports.LocalDate = LocalDate;
-function localDateRange(min, max, incl = '[)', step = 1, stepUnit = 'day') {
-    return localDateRangeIterable(min, max, incl, step, stepUnit).toArray();
-}
-exports.localDateRange = localDateRange;
-/**
- * Experimental, returns the range as Iterable2.
- */
-function localDateRangeIterable(min, max, incl = '[)', step = 1, stepUnit = 'day') {
-    if (stepUnit === 'week') {
-        step *= 7;
-        stepUnit = 'day';
-    }
-    const $min = LocalDate.of(min).startOf(stepUnit);
-    const $max = LocalDate.of(max).startOf(stepUnit);
-    let value = $min;
-    // eslint-disable-next-line @typescript-eslint/prefer-string-starts-ends-with
-    if (value.isAfter($min, incl[0] === '[')) {
-        // ok
-    }
-    else {
-        value.plus(1, stepUnit, true);
-    }
-    const rightInclusive = incl[1] === ']';
-    return iterable2_1.Iterable2.of({
-        *[Symbol.iterator]() {
-            while (value.isBefore($max, rightInclusive)) {
-                yield value;
-                // We don't mutate, because we already returned `current`
-                // in the previous iteration
-                value = value.plus(step, stepUnit);
-            }
-        },
-    });
-}
-exports.localDateRangeIterable = localDateRangeIterable;
-/**
- * Convenience wrapper around `LocalDate.of`
- */
-function localDate(d) {
-    return LocalDate.of(d);
-}
-exports.localDate = localDate;
-/**
- * Convenience wrapper around `LocalDate.today`
- */
-function localDateToday() {
-    return LocalDate.today();
-}
-exports.localDateToday = localDateToday;
-/**
- * Creates a LocalDate from the input, unless it's falsy - then returns undefined.
- *
- * `localDate` function will instead return LocalDate of today for falsy input.
- */
-function localDateOrUndefined(d) {
-    return d ? LocalDate.of(d) : undefined;
-}
-exports.localDateOrUndefined = localDateOrUndefined;
-/**
- * Creates a LocalDate from the input, unless it's falsy - then returns LocalDate.today.
- */
-function localDateOrToday(d) {
-    return d ? LocalDate.of(d) : LocalDate.today();
+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.
+     * String - will be parsed as yyyy-mm-dd.
+     * Date - will be converted to LocalDate (as-is, in whatever timezone it is - local or UTC).
+     * No other formats are supported.
+     *
+     * Will throw if it fails to parse/construct LocalDate.
+     */
+    of(d) {
+        const t = this.parseOrNull(d);
+        (0, assert_1._assert)(t !== null, `Cannot parse "${d}" into LocalDate`, {
+            input: d,
+        });
+        return t;
+    }
+    /**
+     * Tries to construct LocalDate from LocalDateInput, returns null otherwise.
+     * Does not throw (returns null instead).
+     */
+    parseOrNull(d) {
+        if (!d)
+            return null;
+        if (d instanceof LocalDate)
+            return d;
+        if (d instanceof Date) {
+            return this.fromDate(d);
+        }
+        const matches = typeof d === 'string' && DATE_REGEX.exec(d.slice(0, 10));
+        if (!matches)
+            return null;
+        const year = Number(matches[1]);
+        const month = Number(matches[2]);
+        const day = Number(matches[3]);
+        if (!year ||
+            !month ||
+            month < 1 ||
+            month > 12 ||
+            !day ||
+            day < 1 ||
+            day > this.getMonthLength(year, month)) {
+            return null;
+        }
+        return new LocalDate(year, month, day);
+    }
+    /**
+     * 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);
+        (0, assert_1._assert)(day && month && year, `Cannot parse "${d}" 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.
+     */
+    fromDate(d) {
+        return new LocalDate(d.getFullYear(), d.getMonth() + 1, d.getDate());
+    }
+    /**
+     * Constructs LocalDate from Date.
+     * Takes Date's year/month/day components in UTC, using getUTCFullYear, getUTCMonth, getUTCDate.
+     */
+    fromDateInUTC(d) {
+        return new LocalDate(d.getUTCFullYear(), d.getUTCMonth() + 1, d.getUTCDate());
+    }
+    /**
+     * Returns true if isoString is a valid iso8601 string like `yyyy-mm-dd`.
+     */
+    isValid(isoString) {
+        return this.parseOrNull(isoString) !== null;
+    }
+    /**
+     * Creates LocalDate that represents `today` (in local timezone).
+     */
+    today() {
+        return this.fromDate(new Date());
+    }
+    /**
+     * Creates LocalDate that represents `today` in UTC.
+     */
+    todayInUTC() {
+        return this.fromDateInUTC(new Date());
+    }
+    /**
+     * Sorts an array of LocalDates in `dir` order (ascending by default).
+     */
+    sort(items, dir = 'asc', mutate = false) {
+        const mod = dir === 'desc' ? -1 : 1;
+        return (mutate ? items : [...items]).sort((a, b) => a.cmp(b) * mod);
+    }
+    /**
+     * Returns the earliest (min) LocalDate from the array, or undefined if the array is empty.
+     */
+    minOrUndefined(items) {
+        return items.length ? this.min(items) : undefined;
+    }
+    /**
+     * Returns the earliest LocalDate from the array.
+     * Throws if the array is empty.
+     */
+    min(items) {
+        (0, assert_1._assert)(items.length, 'localDate.min called on empty array');
+        return items.map(i => this.of(i)).reduce((min, item) => (min.isSameOrBefore(item) ? min : item));
+    }
+    /**
+     * Returns the latest (max) LocalDate from the array, or undefined if the array is empty.
+     */
+    maxOrUndefined(items) {
+        return items.length ? this.max(items) : undefined;
+    }
+    /**
+     * Returns the latest LocalDate from the array.
+     * Throws if the array is empty.
+     */
+    max(items) {
+        (0, assert_1._assert)(items.length, 'localDate.max called on empty array');
+        return items.map(i => this.of(i)).reduce((max, item) => (max.isSameOrAfter(item) ? max : item));
+    }
+    /**
+     * Returns the range (array) of LocalDates between min and max.
+     * By default, min is included, max is excluded.
+     */
+    range(min, max, incl = '[)', step = 1, stepUnit = 'day') {
+        return this.rangeIterable(min, max, incl, step, stepUnit).toArray();
+    }
+    /**
+     * Returns the Iterable2 of LocalDates between min and max.
+     * By default, min is included, max is excluded.
+     */
+    rangeIterable(min, max, incl = '[)', step = 1, stepUnit = 'day') {
+        if (stepUnit === 'week') {
+            step *= 7;
+            stepUnit = 'day';
+        }
+        const $min = this.of(min).startOf(stepUnit);
+        const $max = this.of(max).startOf(stepUnit);
+        let value = $min;
+        // eslint-disable-next-line @typescript-eslint/prefer-string-starts-ends-with
+        if (value.isAfter($min, incl[0] === '[')) {
+            // ok
+        }
+        else {
+            value.plus(1, stepUnit, true);
+        }
+        const rightInclusive = incl[1] === ']';
+        return iterable2_1.Iterable2.of({
+            *[Symbol.iterator]() {
+                while (value.isBefore($max, rightInclusive)) {
+                    yield value;
+                    // We don't mutate, because we already returned `current`
+                    // in the previous iteration
+                    value = value.plus(step, stepUnit);
+                }
+            },
+        });
+    }
+    /**
+     * Creates a LocalDate from the input, unless it's falsy - then returns undefined.
+     *
+     * Similar to `localDate.orToday`, but that will instead return Today on falsy input.
+     */
+    orUndefined(d) {
+        return d ? this.of(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();
+    }
 }
-exports.localDateOrToday = localDateOrToday;
+const localDateFactory = new LocalDateFactory();
+// export const localDate = Object.assign((d: LocalDateInput) => {
+//   return localDateFactory.of(d)
+// }, localDateFactory) as LocalDateFn
+exports.localDate = localDateFactory.of.bind(localDateFactory);
+// The line below is the blackest of black magic I have ever written in 2024.
+// And probably 2023 as well.
+Object.setPrototypeOf(exports.localDate, localDateFactory);
 /**
  Convenience function to return current today's IsoDateString representation, e.g `2024-06-21`
  */
 function todayString() {
-    // It was benchmarked to be faster than by concatenating individual Date components
-    // return new Date().toISOString().slice(0, 10)
-    // But, toISOString always returns the date in UTC, so in the Browser it would give unexpected result!
-    return LocalDate.fromDate(new Date()).toString();
+    return exports.localDate.fromDate(new Date()).toISODate();
 }
 exports.todayString = todayString;