@naturalcycles/js-lib 14.243.0 → 14.244.0

package/src/datetime/localDate.ts

@@ -16,7 +16,8 @@ export type LocalDateUnit = LocalDateUnitStrict | 'week'
 export type LocalDateUnitStrict = 'year' | 'month' | 'day'
 
 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)/
 
 export type LocalDateInput = LocalDate | Date | IsoDateString
 export type LocalDateInputNullable = LocalDateInput | null | undefined
@@ -28,77 +29,71 @@ export type LocalDateFormatter = (ld: LocalDate) => string
  */
 export class LocalDate {
   constructor(
-    private $year: number,
-    private $month: number,
-    private $day: number,
+    public year: number,
+    public month: number,
+    public day: number,
   ) {}
 
   get(unit: LocalDateUnitStrict): number {
-    return unit === 'year' ? this.$year : unit === 'month' ? this.$month : this.$day
+    return unit === 'year' ? this.year : unit === 'month' ? this.month : this.day
   }
 
   set(unit: LocalDateUnitStrict, v: number, mutate = false): LocalDate {
     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(): number
-  year(v: number): LocalDate
-  year(v?: number): number | LocalDate {
-    return v === undefined ? this.$year : this.set('year', v)
+  setYear(v: number): LocalDate {
+    return this.set('year', v)
   }
-  month(): number
-  month(v: number): LocalDate
-  month(v?: number): number | LocalDate {
-    return v === undefined ? this.$month : this.set('month', v)
+  setMonth(v: number): LocalDate {
+    return this.set('month', v)
   }
-  day(): number
-  day(v: number): LocalDate
-  day(v?: number): number | LocalDate {
-    return v === undefined ? this.$day : this.set('day', v)
+  setDay(v: number): LocalDate {
+    return this.set('day', v)
   }
 
-  dayOfWeek(): ISODayOfWeek {
+  get dayOfWeek(): ISODayOfWeek {
     return (this.toDate().getDay() || 7) as ISODayOfWeek
   }
 
   isSame(d: LocalDateInput): boolean {
-    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: LocalDateInput, inclusive = false): boolean {
-    const r = this.cmp(d)
+    const r = this.compare(d)
     return r === -1 || (r === 0 && inclusive)
   }
 
   isSameOrBefore(d: LocalDateInput): boolean {
-    return this.cmp(d) <= 0
+    return this.compare(d) <= 0
   }
 
   isAfter(d: LocalDateInput, inclusive = false): boolean {
-    const r = this.cmp(d)
+    const r = this.compare(d)
     return r === 1 || (r === 0 && inclusive)
   }
 
   isSameOrAfter(d: LocalDateInput): boolean {
-    return this.cmp(d) >= 0
+    return this.compare(d) >= 0
   }
 
   isBetween(min: LocalDateInput, max: LocalDateInput, incl: Inclusiveness = '[)'): boolean {
-    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
   }
@@ -113,14 +108,14 @@ export class LocalDate {
    * Third argument allows to override "today".
    */
   isOlderThan(n: number, unit: LocalDateUnit, today?: LocalDateInput): boolean {
-    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: number, unit: LocalDateUnit, today?: LocalDateInput): boolean {
-    return this.isSameOrBefore(localDate.of(today || new Date()).plus(-n, unit))
+    return this.isSameOrBefore(localDate.from(today || new Date()).plus(-n, unit))
   }
 
   /**
@@ -133,14 +128,14 @@ export class LocalDate {
    * Third argument allows to override "today".
    */
   isYoungerThan(n: number, unit: LocalDateUnit, today?: LocalDateInput): boolean {
-    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: number, unit: LocalDateUnit, today?: LocalDateInput): boolean {
-    return this.isSameOrAfter(localDate.of(today || new Date()).plus(-n, unit))
+    return this.isSameOrAfter(localDate.from(today || new Date()).plus(-n, unit))
   }
 
   getAgeInYears(today?: LocalDateInput): number {
@@ -153,7 +148,7 @@ export class LocalDate {
     return this.getAgeIn('day', today)
   }
   getAgeIn(unit: LocalDateUnit, today?: LocalDateInput): number {
-    return localDate.of(today || new Date()).diff(this, unit)
+    return localDate.from(today || new Date()).diff(this, unit)
   }
 
   /**
@@ -161,14 +156,14 @@ export class LocalDate {
    * returns 0 if they are equal
    * returns -1 if this < d
    */
-  cmp(d: LocalDateInput): -1 | 0 | 1 {
-    d = localDate.of(d)
-    if (this.$year < d.$year) return -1
-    if (this.$year > d.$year) return 1
-    if (this.$month < d.$month) return -1
-    if (this.$month > d.$month) return 1
-    if (this.$day < d.$day) return -1
-    if (this.$day > d.$day) return 1
+  compare(d: LocalDateInput): -1 | 0 | 1 {
+    d = localDate.from(d)
+    if (this.year < d.year) return -1
+    if (this.year > d.year) return 1
+    if (this.month < d.month) return -1
+    if (this.month > d.month) return 1
+    if (this.day < d.day) return -1
+    if (this.day > d.day) return 1
     return 0
   }
 
@@ -185,24 +180,24 @@ export class LocalDate {
    * a.diff(b) means "a minus b"
    */
   diff(d: LocalDateInput, unit: LocalDateUnit): number {
-    d = localDate.of(d)
+    d = localDate.from(d)
 
-    const sign = this.cmp(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
+      let years = big.year - small.year
 
       if (
-        big.$month < small.$month ||
-        (big.$month === small.$month &&
-          big.$day < small.$day &&
+        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 === localDate.getMonthLength(big.year, big.month) &&
+            small.day === localDate.getMonthLength(small.year, small.month)
           ))
       ) {
         years--
@@ -212,10 +207,10 @@ export 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)
-        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--
         }
       }
@@ -223,21 +218,21 @@ export class LocalDate {
     }
 
     // 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)
       }
     }
 
@@ -274,7 +269,7 @@ export class LocalDate {
   }
 
   plus(num: number, unit: LocalDateUnit, mutate = false): LocalDate {
-    let { $day, $month, $year } = this
+    let { day, month, year } = this
 
     if (unit === 'week') {
       num *= 7
@@ -282,65 +277,65 @@ export class LocalDate {
     }
 
     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: number, unit: LocalDateUnit, mutate = false): LocalDate {
@@ -349,33 +344,29 @@ export class LocalDate {
 
   startOf(unit: LocalDateUnitStrict): LocalDate {
     if (unit === 'day') return this
-    if (unit === 'month') return new LocalDate(this.$year, this.$month, 1)
+    if (unit === 'month') 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: LocalDateUnitStrict): LocalDate {
     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(): number {
-    return localDate.getMonthLength(this.$year, this.$month)
+  get daysInMonth(): number {
+    return localDate.getMonthLength(this.year, this.month)
   }
 
   clone(): LocalDate {
-    return new LocalDate(this.$year, this.$month, this.$day)
+    return new LocalDate(this.year, this.month, this.day)
   }
 
   /**
@@ -385,7 +376,7 @@ export class LocalDate {
    * Timezone will match local timezone.
    */
   toDate(): Date {
-    return new Date(this.$year, this.$month - 1, this.$day)
+    return new Date(this.year, this.month - 1, this.day)
   }
 
   /**
@@ -398,9 +389,9 @@ export class LocalDate {
 
   toDateObject(): DateObject {
     return {
-      year: this.$year,
-      month: this.$month,
-      day: this.$day,
+      year: this.year,
+      month: this.month,
+      day: this.day,
     }
   }
 
@@ -409,7 +400,7 @@ export class LocalDate {
    * LocalTime's Date will be in local timezone.
    */
   toLocalTime(): LocalTime {
-    return localTime.of(this.toDate())
+    return localTime.fromDate(this.toDate())
   }
 
   /**
@@ -417,9 +408,9 @@ export class LocalDate {
    */
   toISODate(): IsoDateString {
     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('-')
   }
 
@@ -448,9 +439,9 @@ export class LocalDate {
    */
   toStringCompact(): string {
     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('')
   }
 
@@ -464,14 +455,14 @@ export class LocalDate {
   /**
    * Returns unix timestamp of 00:00:00 of that date (in UTC, because unix timestamp always reflects UTC).
    */
-  unix(): UnixTimestampNumber {
+  get unix(): UnixTimestampNumber {
     return Math.floor(this.toDate().valueOf() / 1000)
   }
 
   /**
    * Same as .unix(), but in milliseconds.
    */
-  unixMillis(): UnixTimestampMillisNumber {
+  get unixMillis(): UnixTimestampMillisNumber {
     return this.toDate().valueOf()
   }
 
@@ -489,13 +480,6 @@ export class LocalDate {
 }
 
 class LocalDateFactory {
-  /**
-   * Create LocalDate from year, month and day components.
-   */
-  create(year: number, month: number, day: number): LocalDate {
-    return new LocalDate(year, month, day)
-  }
-
   /**
    * Create LocalDate from LocalDateInput.
    * Input can already be a LocalDate - it is returned as-is in that case.
@@ -505,33 +489,43 @@ class LocalDateFactory {
    *
    * Will throw if it fails to parse/construct LocalDate.
    */
-  of(d: LocalDateInput): LocalDate {
-    const t = this.parseOrNull(d)
-
-    _assert(t !== null, `Cannot parse "${d}" into LocalDate`, {
-      input: d,
-    })
-
-    return t
+  from(input: LocalDateInput): LocalDate {
+    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: LocalDateInputNullable): LocalDate | null {
+  fromOrNull(d: LocalDateInputNullable): LocalDate | null {
     if (!d) return null
     if (d instanceof LocalDate) return d
     if (d instanceof Date) {
       return this.fromDate(d)
     }
+    if (typeof (d as any) === 'string') {
+      return this.fromStringOrNull(d)
+    }
 
-    const matches = typeof (d as any) === 'string' && DATE_REGEX.exec(d.slice(0, 10))
-    if (!matches) return null
+    return null
+  }
+
+  fromString(s: string): LocalDate {
+    const ld = this.fromStringOrNull(s)
+    this.assertNotNull(ld, s)
+    return ld
+  }
 
-    const year = Number(matches[1])
-    const month = Number(matches[2])
-    const day = Number(matches[3])
+  fromStringOrNull(s: string | undefined | null): LocalDate | null {
+    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 ||
@@ -552,14 +546,51 @@ class LocalDateFactory {
    * Parses "compact iso8601 format", e.g `19840621` into LocalDate.
    * Throws if it fails to do so.
    */
-  parseCompact(d: string): LocalDate {
-    const [year, month, day] = [d.slice(0, 4), d.slice(4, 2), d.slice(6, 2)].map(Number)
+  fromCompactString(s: string): LocalDate {
+    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)
+  }
+
+  /**
+   * Constructs LocalDate from Date.
+   * Takes Date as-is, in its timezone - local or UTC.
+   */
+  fromDate(d: Date): LocalDate {
+    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: Date): LocalDate {
+    return new LocalDate(d.getUTCFullYear(), d.getUTCMonth() + 1, d.getUTCDate())
+  }
 
-    _assert(day && month && year, `Cannot parse "${d}" into LocalDate`)
+  /**
+   * Create LocalDate from year, month and day components.
+   */
+  fromComponents(year: number, month: number, day: number): LocalDate {
+    return new LocalDate(year, month, day)
+  }
 
+  fromDateObject(o: DateObject): LocalDate {
+    const { year, month, day } = o
     return new LocalDate(year, month, day)
   }
 
+  private assertNotNull(
+    ld: LocalDate | null,
+    input: LocalDateInputNullable,
+  ): asserts ld is LocalDate {
+    _assert(ld !== null, `Cannot parse "${input}" into LocalDate`, {
+      input,
+    })
+  }
+
   getYearLength(year: number): number {
     return this.isLeapYear(year) ? 366 : 365
   }
@@ -574,26 +605,17 @@ class LocalDateFactory {
   }
 
   /**
-   * Constructs LocalDate from Date.
-   * Takes Date as-is, in its timezone - local or UTC.
-   */
-  fromDate(d: Date): LocalDate {
-    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.
+   * Returns true if input is valid to create LocalDate.
    */
-  fromDateInUTC(d: Date): LocalDate {
-    return new LocalDate(d.getUTCFullYear(), d.getUTCMonth() + 1, d.getUTCDate())
+  isValid(input: LocalDateInputNullable): boolean {
+    return this.fromOrNull(input) !== null
   }
 
   /**
    * Returns true if isoString is a valid iso8601 string like `yyyy-mm-dd`.
    */
-  isValid(isoString: string | undefined | null): boolean {
-    return this.parseOrNull(isoString) !== null
+  isValidString(isoString: string | undefined | null): boolean {
+    return this.fromStringOrNull(isoString) !== null
   }
 
   /**
@@ -615,7 +637,7 @@ class LocalDateFactory {
    */
   sort(items: LocalDate[], dir: SortDirection = 'asc', mutate = false): LocalDate[] {
     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)
   }
 
   /**
@@ -634,7 +656,7 @@ class LocalDateFactory {
     _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))
   }
 
@@ -653,7 +675,9 @@ class LocalDateFactory {
     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))
   }
 
   /**
@@ -686,8 +710,8 @@ class LocalDateFactory {
       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
@@ -718,14 +742,14 @@ class LocalDateFactory {
    * Similar to `localDate.orToday`, but that will instead return Today on falsy input.
    */
   orUndefined(d: LocalDateInputNullable): LocalDate | undefined {
-    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: LocalDateInputNullable): LocalDate {
-    return d ? this.of(d) : this.today()
+    return d ? this.from(d) : this.today()
   }
 }
 
@@ -735,11 +759,7 @@ interface LocalDateFn extends LocalDateFactory {
 
 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) as LocalDateFn
+export const localDate = localDateFactory.from.bind(localDateFactory) as LocalDateFn
 
 // The line below is the blackest of black magic I have ever written in 2024.
 // And probably 2023 as well.