@naturalcycles/js-lib 14.244.0 → 14.245.0

package/dist/datetime/dateInterval.d.ts

@@ -1,5 +1,5 @@
 import { Inclusiveness } from '../types';
-import { LocalDateInput, LocalDateUnit, LocalDate } from './localDate';
+import { LocalDate, LocalDateInput, LocalDateUnit } from './localDate';
 export type DateIntervalConfig = DateInterval | DateIntervalString;
 export type DateIntervalString = string;
 /**

package/dist/datetime/localDate.d.ts

@@ -146,6 +146,28 @@ export declare class LocalDate {
     format(fmt: Intl.DateTimeFormat | LocalDateFormatter): string;
 }
 declare class LocalDateFactory {
+    /**
+     * 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: LocalDateInputNullable): LocalDate | undefined;
+    /**
+     * Creates a LocalDate from the input, unless it's falsy - then returns localDate.today.
+     */
+    orToday(d: LocalDateInputNullable): LocalDate;
+    /**
+     * Creates LocalDate that represents `today` (in local timezone).
+     */
+    today(): LocalDate;
+    /**
+     * Creates LocalDate that represents `today` in UTC.
+     */
+    todayInUTC(): LocalDate;
+    /**
+     Convenience function to return current today's IsoDateString representation, e.g `2024-06-21`
+     */
+    todayString(): IsoDateString;
     /**
      * Create LocalDate from LocalDateInput.
      * Input can already be a LocalDate - it is returned as-is in that case.
@@ -155,54 +177,62 @@ declare class LocalDateFactory {
      *
      * Will throw if it fails to parse/construct LocalDate.
      */
-    from(input: LocalDateInput): LocalDate;
+    fromInput(input: LocalDateInput): LocalDate;
+    /**
+     * Returns true if input is valid to create LocalDate.
+     */
+    isValid(input: LocalDateInputNullable): boolean;
+    /**
+     * Returns true if isoString is a valid iso8601 string like `yyyy-mm-dd`.
+     */
+    isValidString(isoString: string | undefined | null): boolean;
+    /**
+     * Tries to convert/parse the input into LocalDate.
+     * Uses LOOSE parsing.
+     * If invalid - doesn't throw, but returns undefined instead.
+     */
+    try(input: LocalDateInputNullable): LocalDate | undefined;
     /**
-     * Tries to construct LocalDate from LocalDateInput, returns null otherwise.
-     * Does not throw (returns null instead).
+     * Performs STRICT parsing.
+     * Only allows IsoDateString input, nothing else.
      */
-    fromOrNull(d: LocalDateInputNullable): LocalDate | null;
-    fromString(s: string): LocalDate;
-    fromStringOrNull(s: string | undefined | null): LocalDate | null;
+    fromIsoDateString(s: IsoDateString): LocalDate;
     /**
      * Parses "compact iso8601 format", e.g `19840621` into LocalDate.
      * Throws if it fails to do so.
      */
     fromCompactString(s: string): LocalDate;
     /**
-     * Constructs LocalDate from Date.
-     * Takes Date as-is, in its timezone - local or UTC.
-     */
-    fromDate(d: Date): LocalDate;
-    /**
-     * Constructs LocalDate from Date.
-     * Takes Date's year/month/day components in UTC, using getUTCFullYear, getUTCMonth, getUTCDate.
+     * Performs LOOSE parsing.
+     * Tries to coerce imprefect/incorrect string input into IsoDateString.
+     * Use with caution.
+     * Allows to input IsoDateTimeString, will drop the Time part of it.
      */
-    fromDateInUTC(d: Date): LocalDate;
+    parse(s: string): LocalDate;
     /**
-     * Create LocalDate from year, month and day components.
+     * Throws if it fails to parse the input string via Regex and YMD validation.
      */
-    fromComponents(year: number, month: number, day: number): LocalDate;
-    fromDateObject(o: DateObject): LocalDate;
-    private assertNotNull;
-    getYearLength(year: number): number;
-    getMonthLength(year: number, month: number): number;
-    isLeapYear(year: number): boolean;
+    private parseToLocalDate;
     /**
-     * Returns true if input is valid to create LocalDate.
+     * Tries to parse the input string, returns undefined if input is invalid.
      */
-    isValid(input: LocalDateInputNullable): boolean;
+    private parseToLocalDateOrUndefined;
     /**
-     * Returns true if isoString is a valid iso8601 string like `yyyy-mm-dd`.
+     * Throws on invalid value.
      */
-    isValidString(isoString: string | undefined | null): boolean;
+    private validateDateObject;
+    isDateObjectValid({ year, month, day }: DateObject): boolean;
     /**
-     * Creates LocalDate that represents `today` (in local timezone).
+     * Constructs LocalDate from Date.
+     * Takes Date as-is, in its timezone - local or UTC.
      */
-    today(): LocalDate;
+    fromDate(d: Date): LocalDate;
     /**
-     * Creates LocalDate that represents `today` in UTC.
+     * Constructs LocalDate from Date.
+     * Takes Date's year/month/day components in UTC, using getUTCFullYear, getUTCMonth, getUTCDate.
      */
-    todayInUTC(): LocalDate;
+    fromDateInUTC(d: Date): LocalDate;
+    fromDateObject(o: DateObject): LocalDate;
     /**
      * Sorts an array of LocalDates in `dir` order (ascending by default).
      */
@@ -235,23 +265,12 @@ declare class LocalDateFactory {
      * By default, min is included, max is excluded.
      */
     rangeIterable(min: LocalDateInput, max: LocalDateInput, incl?: Inclusiveness, step?: number, stepUnit?: LocalDateUnit): Iterable2<LocalDate>;
-    /**
-     * 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: LocalDateInputNullable): LocalDate | undefined;
-    /**
-     * Creates a LocalDate from the input, unless it's falsy - then returns localDate.today.
-     */
-    orToday(d: LocalDateInputNullable): LocalDate;
+    getYearLength(year: number): number;
+    getMonthLength(year: number, month: number): number;
+    isLeapYear(year: number): boolean;
 }
 interface LocalDateFn extends LocalDateFactory {
     (d: LocalDateInput): LocalDate;
 }
 export declare const localDate: LocalDateFn;
-/**
- Convenience function to return current today's IsoDateString representation, e.g `2024-06-21`
- */
-export declare function todayString(): IsoDateString;
 export {};

package/dist/datetime/localDate.js

@@ -1,14 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.localDate = exports.LocalDate = void 0;
-exports.todayString = todayString;
 const assert_1 = require("../error/assert");
 const is_util_1 = require("../is.util");
 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];
-// 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)/;
+/**
+ * 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_LOOSE = /^(\d\d\d\d)-(\d\d)-(\d\d)/;
+/**
+ * Strict version.
+ */
+const DATE_REGEX_STRICT = /^(\d\d\d\d)-(\d\d)-(\d\d)$/;
+const COMPACT_DATE_REGEX = /^(\d\d\d\d)(\d\d)(\d\d)$/;
 /**
  * LocalDate represents a date without time.
  * It is timezone-independent.
@@ -48,7 +54,7 @@ class LocalDate {
         return (this.toDate().getDay() || 7);
     }
     isSame(d) {
-        d = exports.localDate.from(d);
+        d = exports.localDate.fromInput(d);
         return this.day === d.day && this.month === d.month && this.year === d.year;
     }
     isBefore(d, inclusive = false) {
@@ -85,13 +91,13 @@ class LocalDate {
      * Third argument allows to override "today".
      */
     isOlderThan(n, unit, today) {
-        return this.isBefore(exports.localDate.from(today || new Date()).plus(-n, unit));
+        return this.isBefore(exports.localDate.fromInput(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(exports.localDate.from(today || new Date()).plus(-n, unit));
+        return this.isSameOrBefore(exports.localDate.fromInput(today || new Date()).plus(-n, unit));
     }
     /**
      * Checks if this localDate is younger (>) than "today" by X units.
@@ -103,13 +109,13 @@ class LocalDate {
      * Third argument allows to override "today".
      */
     isYoungerThan(n, unit, today) {
-        return this.isAfter(exports.localDate.from(today || new Date()).plus(-n, unit));
+        return this.isAfter(exports.localDate.fromInput(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(exports.localDate.from(today || new Date()).plus(-n, unit));
+        return this.isSameOrAfter(exports.localDate.fromInput(today || new Date()).plus(-n, unit));
     }
     getAgeInYears(today) {
         return this.getAgeIn('year', today);
@@ -121,7 +127,7 @@ class LocalDate {
         return this.getAgeIn('day', today);
     }
     getAgeIn(unit, today) {
-        return exports.localDate.from(today || new Date()).diff(this, unit);
+        return exports.localDate.fromInput(today || new Date()).diff(this, unit);
     }
     /**
      * Returns 1 if this > d
@@ -129,7 +135,7 @@ class LocalDate {
      * returns -1 if this < d
      */
     compare(d) {
-        d = exports.localDate.from(d);
+        d = exports.localDate.fromInput(d);
         if (this.year < d.year)
             return -1;
         if (this.year > d.year)
@@ -156,7 +162,7 @@ class LocalDate {
      * a.diff(b) means "a minus b"
      */
     diff(d, unit) {
-        d = exports.localDate.from(d);
+        d = exports.localDate.fromInput(d);
         const sign = this.compare(d);
         if (!sign)
             return 0;
@@ -307,8 +313,9 @@ class LocalDate {
     endOf(unit) {
         if (unit === 'day')
             return this;
-        if (unit === 'month')
+        if (unit === 'month') {
             return new LocalDate(this.year, this.month, exports.localDate.getMonthLength(this.year, this.month));
+        }
         // year
         return new LocalDate(this.year, 12, 31);
     }
@@ -419,6 +426,38 @@ class LocalDate {
 }
 exports.LocalDate = LocalDate;
 class LocalDateFactory {
+    /**
+     * 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.fromInput(d) : undefined;
+    }
+    /**
+     * Creates a LocalDate from the input, unless it's falsy - then returns localDate.today.
+     */
+    orToday(d) {
+        return d ? this.fromInput(d) : this.today();
+    }
+    /**
+     * 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());
+    }
+    /**
+     Convenience function to return current today's IsoDateString representation, e.g `2024-06-21`
+     */
+    todayString() {
+        return this.fromDate(new Date()).toISODate();
+    }
     /**
      * Create LocalDate from LocalDateInput.
      * Input can already be a LocalDate - it is returned as-is in that case.
@@ -428,125 +467,125 @@ class LocalDateFactory {
      *
      * Will throw if it fails to parse/construct LocalDate.
      */
-    from(input) {
-        const ld = this.fromOrNull(input);
-        this.assertNotNull(ld, input);
-        return ld;
+    fromInput(input) {
+        if (input instanceof LocalDate)
+            return input;
+        if (input instanceof Date) {
+            return this.fromDate(input);
+        }
+        // It means it's a string
+        return this.fromIsoDateString(input);
     }
     /**
-     * Tries to construct LocalDate from LocalDateInput, returns null otherwise.
-     * Does not throw (returns null instead).
+     * Returns true if input is valid to create LocalDate.
      */
-    fromOrNull(d) {
-        if (!d)
-            return null;
-        if (d instanceof LocalDate)
-            return d;
-        if (d instanceof Date) {
-            return this.fromDate(d);
-        }
-        if (typeof d === 'string') {
-            return this.fromStringOrNull(d);
-        }
-        return null;
-    }
-    fromString(s) {
-        const ld = this.fromStringOrNull(s);
-        this.assertNotNull(ld, s);
-        return ld;
+    isValid(input) {
+        if (!input)
+            return false;
+        if (input instanceof LocalDate)
+            return true;
+        if (input instanceof Date)
+            return !isNaN(input.getDate());
+        return this.isValidString(input);
     }
-    fromStringOrNull(s) {
-        if (!s)
-            return null;
-        const m = DATE_REGEX.exec(s);
-        if (!m)
-            return null;
-        const year = Number(m[1]);
-        const month = Number(m[2]);
-        const day = Number(m[3]);
-        if (!year ||
-            !month ||
-            month < 1 ||
-            month > 12 ||
-            !day ||
-            day < 1 ||
-            day > this.getMonthLength(year, month)) {
-            return null;
+    /**
+     * Returns true if isoString is a valid iso8601 string like `yyyy-mm-dd`.
+     */
+    isValidString(isoString) {
+        return !!this.parseToLocalDateOrUndefined(DATE_REGEX_STRICT, isoString);
+    }
+    /**
+     * Tries to convert/parse the input into LocalDate.
+     * Uses LOOSE parsing.
+     * If invalid - doesn't throw, but returns undefined instead.
+     */
+    try(input) {
+        if (!input)
+            return;
+        if (input instanceof LocalDate)
+            return input;
+        if (input instanceof Date) {
+            if (isNaN(input.getDate()))
+                return;
+            return new LocalDate(input.getFullYear(), input.getMonth() + 1, input.getDate());
         }
-        return new LocalDate(year, month, day);
+        return this.parseToLocalDateOrUndefined(DATE_REGEX_LOOSE, input);
+    }
+    /**
+     * Performs STRICT parsing.
+     * Only allows IsoDateString input, nothing else.
+     */
+    fromIsoDateString(s) {
+        return this.parseToLocalDate(DATE_REGEX_STRICT, s);
     }
     /**
      * Parses "compact iso8601 format", e.g `19840621` into LocalDate.
      * Throws if it fails to do so.
      */
     fromCompactString(s) {
-        const [year, month, day] = [s.slice(0, 4), s.slice(4, 6), s.slice(6, 8)].map(Number);
-        (0, assert_1._assert)(day && month && year, `Cannot parse compact string "${s}" into LocalDate`);
-        return new LocalDate(year, month, day);
+        return this.parseToLocalDate(COMPACT_DATE_REGEX, s);
     }
     /**
-     * Constructs LocalDate from Date.
-     * Takes Date as-is, in its timezone - local or UTC.
+     * Performs LOOSE parsing.
+     * Tries to coerce imprefect/incorrect string input into IsoDateString.
+     * Use with caution.
+     * Allows to input IsoDateTimeString, will drop the Time part of it.
      */
-    fromDate(d) {
-        return new LocalDate(d.getFullYear(), d.getMonth() + 1, d.getDate());
+    parse(s) {
+        return this.parseToLocalDate(DATE_REGEX_LOOSE, String(s));
     }
     /**
-     * Constructs LocalDate from Date.
-     * Takes Date's year/month/day components in UTC, using getUTCFullYear, getUTCMonth, getUTCDate.
+     * Throws if it fails to parse the input string via Regex and YMD validation.
      */
-    fromDateInUTC(d) {
-        return new LocalDate(d.getUTCFullYear(), d.getUTCMonth() + 1, d.getUTCDate());
+    parseToLocalDate(regex, s) {
+        const ld = this.parseToLocalDateOrUndefined(regex, s);
+        (0, assert_1._assert)(ld, `Cannot parse "${s}" into LocalDate`);
+        return ld;
     }
     /**
-     * Create LocalDate from year, month and day components.
+     * Tries to parse the input string, returns undefined if input is invalid.
      */
-    fromComponents(year, month, day) {
-        return new LocalDate(year, month, day);
-    }
-    fromDateObject(o) {
-        const { year, month, day } = o;
+    parseToLocalDateOrUndefined(regex, s) {
+        if (!s || typeof s !== 'string')
+            return;
+        const m = regex.exec(s);
+        if (!m)
+            return;
+        const year = Number(m[1]);
+        const month = Number(m[2]);
+        const day = Number(m[3]);
+        if (!this.isDateObjectValid({ year, month, day }))
+            return;
         return new LocalDate(year, month, day);
     }
-    assertNotNull(ld, input) {
-        (0, assert_1._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.
+     * Throws on invalid value.
      */
-    isValid(input) {
-        return this.fromOrNull(input) !== null;
+    validateDateObject(o) {
+        (0, assert_1._assert)(this.isDateObjectValid(o), `Cannot construct LocalDate from: ${o.year}-${o.month}-${o.day}`);
     }
-    /**
-     * Returns true if isoString is a valid iso8601 string like `yyyy-mm-dd`.
-     */
-    isValidString(isoString) {
-        return this.fromStringOrNull(isoString) !== null;
+    isDateObjectValid({ year, month, day }) {
+        return (!!year && month >= 1 && month <= 12 && day >= 1 && day <= this.getMonthLength(year, month));
     }
     /**
-     * Creates LocalDate that represents `today` (in local timezone).
+     * Constructs LocalDate from Date.
+     * Takes Date as-is, in its timezone - local or UTC.
      */
-    today() {
-        return this.fromDate(new Date());
+    fromDate(d) {
+        (0, assert_1._assert)(!isNaN(d.getDate()), `localDate.fromDate is called on Date object that is invalid`);
+        return new LocalDate(d.getFullYear(), d.getMonth() + 1, d.getDate());
     }
     /**
-     * Creates LocalDate that represents `today` in UTC.
+     * Constructs LocalDate from Date.
+     * Takes Date's year/month/day components in UTC, using getUTCFullYear, getUTCMonth, getUTCDate.
      */
-    todayInUTC() {
-        return this.fromDateInUTC(new Date());
+    fromDateInUTC(d) {
+        (0, assert_1._assert)(!isNaN(d.getDate()), `localDate.fromDateInUTC is called on Date object that is invalid`);
+        return new LocalDate(d.getUTCFullYear(), d.getUTCMonth() + 1, d.getUTCDate());
+    }
+    fromDateObject(o) {
+        this.validateDateObject(o);
+        return new LocalDate(o.year, o.month, o.day);
     }
     /**
      * Sorts an array of LocalDates in `dir` order (ascending by default).
@@ -569,7 +608,7 @@ class LocalDateFactory {
         const items2 = items.filter(is_util_1._isTruthy);
         (0, assert_1._assert)(items2.length, 'localDate.min called on empty array');
         return items2
-            .map(i => this.from(i))
+            .map(i => this.fromInput(i))
             .reduce((min, item) => (min.isSameOrBefore(item) ? min : item));
     }
     /**
@@ -586,7 +625,7 @@ class LocalDateFactory {
         const items2 = items.filter(is_util_1._isTruthy);
         (0, assert_1._assert)(items2.length, 'localDate.max called on empty array');
         return items2
-            .map(i => this.from(i))
+            .map(i => this.fromInput(i))
             .reduce((max, item) => (max.isSameOrAfter(item) ? max : item));
     }
     /**
@@ -605,8 +644,8 @@ class LocalDateFactory {
             step *= 7;
             stepUnit = 'day';
         }
-        const $min = this.from(min).startOf(stepUnit);
-        const $max = this.from(max).startOf(stepUnit);
+        const $min = this.fromInput(min).startOf(stepUnit);
+        const $max = this.fromInput(max).startOf(stepUnit);
         let value = $min;
         // eslint-disable-next-line @typescript-eslint/prefer-string-starts-ends-with
         if (value.isAfter($min, incl[0] === '[')) {
@@ -627,29 +666,20 @@ class LocalDateFactory {
             },
         });
     }
-    /**
-     * 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.from(d) : undefined;
+    getYearLength(year) {
+        return this.isLeapYear(year) ? 366 : 365;
     }
-    /**
-     * Creates a LocalDate from the input, unless it's falsy - then returns localDate.today.
-     */
-    orToday(d) {
-        return d ? this.from(d) : this.today();
+    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);
     }
 }
 const localDateFactory = new LocalDateFactory();
-exports.localDate = localDateFactory.from.bind(localDateFactory);
+exports.localDate = localDateFactory.fromInput.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() {
-    return exports.localDate.fromDate(new Date()).toISODate();
-}