@naturalcycles/js-lib 14.243.0 → 14.244.0

package/src/datetime/localTime.ts

@@ -32,6 +32,7 @@ export type LocalTimeInputNullable = LocalTimeInput | null | undefined
 export type LocalTimeFormatter = (ld: LocalTime) => string
 
 export type DateTimeObject = DateObject & TimeObject
+export type DateTimeObjectInput = DateObject & Partial<TimeObject>
 
 export interface DateObject {
   year: number
@@ -51,6 +52,10 @@ const SECONDS_IN_DAY = 86400
 // const MILLISECONDS_IN_DAY = 86400000
 // const MILLISECONDS_IN_MINUTE = 60000
 const VALID_DAYS_OF_WEEK = new Set([1, 2, 3, 4, 5, 6, 7])
+// It supports 2 forms:
+// 1. 2023-03-03
+// 2. 2023-03-03T05:10:02
+const DATE_TIME_REGEX = /^(\d{4})-(\d{2})-(\d{2})([T\s](\d{2}):(\d{2}):(\d{2}))?/
 
 export class LocalTime {
   constructor(public $date: Date) {}
@@ -59,7 +64,7 @@ export class LocalTime {
    * Returns [cloned] LocalTime that is based on the same unixtimestamp, but in UTC timezone.
    * Opposite of `.local()` method.
    */
-  utc(): LocalTime {
+  toUTC(): LocalTime {
     return new LocalTime(new Date(this.$date.toISOString()))
   }
 
@@ -67,7 +72,7 @@ export class LocalTime {
    * Returns [cloned] LocalTime that is based on the same unixtimestamp, but in local timezone.
    * Opposite of `.utc()` method.
    */
-  local(): LocalTime {
+  toLocal(): LocalTime {
     return new LocalTime(new Date(this.$date.getTime()))
   }
 
@@ -193,58 +198,60 @@ export class LocalTime {
     return t
   }
 
-  year(): number
-  year(v: number): LocalTime
-  year(v?: number): number | LocalTime {
-    return v === undefined ? this.get('year') : this.set('year', v)
+  get year(): number {
+    return this.$date.getFullYear()
   }
-  month(): number
-  month(v: number): LocalTime
-  month(v?: number): number | LocalTime {
-    return v === undefined ? this.get('month') : this.set('month', v)
+  setYear(v: number): LocalTime {
+    return this.set('year', v)
   }
-  week(): number
-  week(v: number): LocalTime
-  week(v?: number): number | LocalTime {
-    return v === undefined ? getWeek(this.$date) : this.set('week', v)
+  get month(): number {
+    return this.$date.getMonth() + 1
   }
-  day(): number
-  day(v: number): LocalTime
-  day(v?: number): number | LocalTime {
-    return v === undefined ? this.get('day') : this.set('day', v)
+  setMonth(v: number): LocalTime {
+    return this.set('month', v)
+  }
+  get week(): number {
+    return getWeek(this.$date)
+  }
+  setWeek(v: number): LocalTime {
+    return this.set('week', v)
+  }
+  get day(): number {
+    return this.$date.getDate()
+  }
+  setDay(v: number): LocalTime {
+    return this.set('day', v)
+  }
+  get hour(): number {
+    return this.$date.getHours()
+  }
+  setHour(v: number): LocalTime {
+    return this.set('hour', v)
+  }
+  get minute(): number {
+    return this.$date.getMinutes()
+  }
+  setMinute(v: number): LocalTime {
+    return this.set('minute', v)
+  }
+  get second(): number {
+    return this.$date.getSeconds()
+  }
+  setSecond(v: number): LocalTime {
+    return this.set('second', v)
   }
 
   /**
    * Based on ISO: 1-7 is Mon-Sun.
    */
-  dayOfWeek(): ISODayOfWeek
-  dayOfWeek(v: ISODayOfWeek): LocalTime
-  dayOfWeek(v?: ISODayOfWeek): ISODayOfWeek | LocalTime {
-    const dow = (this.$date.getDay() || 7) as ISODayOfWeek
-
-    if (v === undefined) {
-      return dow
-    }
-
+  get dayOfWeek(): ISODayOfWeek {
+    return (this.$date.getDay() || 7) as ISODayOfWeek
+  }
+  setDayOfWeek(v: ISODayOfWeek): LocalTime {
     _assert(VALID_DAYS_OF_WEEK.has(v), `Invalid dayOfWeek: ${v}`)
-
+    const dow = this.$date.getDay() || 7
     return this.plus(v - dow, 'day')
   }
-  hour(): number
-  hour(v: number): LocalTime
-  hour(v?: number): number | LocalTime {
-    return v === undefined ? this.get('hour') : this.set('hour', v)
-  }
-  minute(): number
-  minute(v: number): LocalTime
-  minute(v?: number): number | LocalTime {
-    return v === undefined ? this.get('minute') : this.set('minute', v)
-  }
-  second(): number
-  second(v: number): LocalTime
-  second(v?: number): number | LocalTime {
-    return v === undefined ? this.get('second') : this.set('second', v)
-  }
 
   setComponents(c: Partial<DateTimeObject>, mutate = false): LocalTime {
     const d = mutate ? this.$date : new Date(this.$date)
@@ -322,7 +329,7 @@ export class LocalTime {
 
     if (unit === 'year' || unit === 'month') {
       const d = addMonths(this.$date, unit === 'month' ? num : num * 12, mutate)
-      return mutate ? this : localTime.of(d)
+      return mutate ? this : localTime.from(d)
     }
 
     return this.set(unit, this.get(unit) + num, mutate)
@@ -337,7 +344,7 @@ export class LocalTime {
   }
 
   diff(other: LocalTimeInput, unit: LocalTimeUnit): number {
-    const date2 = localTime.parseToDate(other)
+    const date2 = localTime.from(other).$date
 
     const secDiff = (this.$date.valueOf() - date2.valueOf()) / 1000
     if (!secDiff) return 0
@@ -427,37 +434,32 @@ export class LocalTime {
    * Returns how many days are in the current month.
    * E.g 31 for January.
    */
-  daysInMonth(): number {
+  get daysInMonth(): number {
     return localDate.getMonthLength(this.$date.getFullYear(), this.$date.getMonth() + 1)
   }
 
   isSame(d: LocalTimeInput): boolean {
-    return this.cmp(d) === 0
+    return this.compare(d) === 0
   }
-
   isBefore(d: LocalTimeInput, inclusive = false): boolean {
-    const r = this.cmp(d)
+    const r = this.compare(d)
     return r === -1 || (r === 0 && inclusive)
   }
-
   isSameOrBefore(d: LocalTimeInput): boolean {
-    return this.cmp(d) <= 0
+    return this.compare(d) <= 0
   }
-
   isAfter(d: LocalTimeInput, inclusive = false): boolean {
-    const r = this.cmp(d)
+    const r = this.compare(d)
     return r === 1 || (r === 0 && inclusive)
   }
-
   isSameOrAfter(d: LocalTimeInput): boolean {
-    return this.cmp(d) >= 0
+    return this.compare(d) >= 0
   }
-
   isBetween(min: LocalTimeInput, max: LocalTimeInput, 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
   }
@@ -472,14 +474,14 @@ export class LocalTime {
    * Third argument allows to override "now".
    */
   isOlderThan(n: number, unit: LocalTimeUnit, now?: LocalTimeInput): boolean {
-    return this.isBefore(localTime.of(now ?? new Date()).plus(-n, unit))
+    return this.isBefore(localTime.from(now ?? new Date()).plus(-n, unit))
   }
 
   /**
    * Checks if this localTime is same or older (<=) than "now" by X units.
    */
   isSameOrOlderThan(n: number, unit: LocalTimeUnit, now?: LocalTimeInput): boolean {
-    return this.isSameOrBefore(localTime.of(now ?? new Date()).plus(-n, unit))
+    return this.isSameOrBefore(localTime.from(now ?? new Date()).plus(-n, unit))
   }
 
   /**
@@ -492,14 +494,14 @@ export class LocalTime {
    * Third argument allows to override "now".
    */
   isYoungerThan(n: number, unit: LocalTimeUnit, now?: LocalTimeInput): boolean {
-    return this.isAfter(localTime.of(now ?? new Date()).plus(-n, unit))
+    return this.isAfter(localTime.from(now ?? new Date()).plus(-n, unit))
   }
 
   /**
    * Checks if this localTime is same or younger (>=) than "now" by X units.
    */
   isSameOrYoungerThan(n: number, unit: LocalTimeUnit, now?: LocalTimeInput): boolean {
-    return this.isSameOrAfter(localTime.of(now ?? new Date()).plus(-n, unit))
+    return this.isSameOrAfter(localTime.from(now ?? new Date()).plus(-n, unit))
   }
 
   getAgeInYears(now?: LocalTimeInput): number {
@@ -521,7 +523,7 @@ export class LocalTime {
     return this.getAgeIn('second', now)
   }
   getAgeIn(unit: LocalTimeUnit, now?: LocalTimeInput): number {
-    return localTime.of(now ?? new Date()).diff(this, unit)
+    return localTime.from(now ?? new Date()).diff(this, unit)
   }
 
   /**
@@ -529,21 +531,21 @@ export class LocalTime {
    * returns 0 if they are equal
    * returns -1 if this < d
    */
-  cmp(d: LocalTimeInput): -1 | 0 | 1 {
+  compare(d: LocalTimeInput): -1 | 0 | 1 {
     const t1 = this.$date.valueOf()
-    const t2 = localTime.parseToDate(d).valueOf()
+    const t2 = localTime.from(d).$date.valueOf()
     if (t1 === t2) return 0
     return t1 < t2 ? -1 : 1
   }
 
-  getDateTimeObject(): DateTimeObject {
+  toDateTimeObject(): DateTimeObject {
     return {
-      ...this.getDateObject(),
-      ...this.getTimeObject(),
+      ...this.toDateObject(),
+      ...this.toTimeObject(),
     }
   }
 
-  getDateObject(): DateObject {
+  toDateObject(): DateObject {
     return {
       year: this.$date.getFullYear(),
       month: this.$date.getMonth() + 1,
@@ -551,7 +553,7 @@ export class LocalTime {
     }
   }
 
-  getTimeObject(): TimeObject {
+  toTimeObject(): TimeObject {
     return {
       hour: this.$date.getHours(),
       minute: this.$date.getMinutes(),
@@ -559,8 +561,8 @@ export class LocalTime {
     }
   }
 
-  fromNow(now: LocalTimeInput = new Date()): string {
-    const msDiff = localTime.parseToDate(now).valueOf() - this.$date.valueOf()
+  toFromNowString(now: LocalTimeInput = new Date()): string {
+    const msDiff = localTime.from(now).$date.valueOf() - this.$date.valueOf()
 
     if (msDiff === 0) return 'now'
 
@@ -571,7 +573,7 @@ export class LocalTime {
     return `in ${_ms(msDiff * -1)}`
   }
 
-  getDate(): Date {
+  toDate(): Date {
     return this.$date
   }
 
@@ -579,11 +581,11 @@ export class LocalTime {
     return new LocalTime(new Date(this.$date))
   }
 
-  unix(): UnixTimestampNumber {
+  get unix(): UnixTimestampNumber {
     return Math.floor(this.$date.valueOf() / 1000)
   }
 
-  unixMillis(): UnixTimestampMillisNumber {
+  get unixMillis(): UnixTimestampMillisNumber {
     return this.$date.valueOf()
   }
 
@@ -620,7 +622,7 @@ export class LocalTime {
    * Returns e.g: `1984-06-21`, only the date part of DateTime
    */
   toISODate(): IsoDateString {
-    const { year, month, day } = this.getDateObject()
+    const { year, month, day } = this.toDateObject()
 
     return [
       String(year).padStart(4, '0'),
@@ -636,7 +638,7 @@ export class LocalTime {
    * Returns e.g: `17:03:15` (or `17:03` with seconds=false)
    */
   toISOTime(seconds = true): string {
-    const { hour, minute, second } = this.getTimeObject()
+    const { hour, minute, second } = this.toTimeObject()
 
     return [
       String(hour).padStart(2, '0'),
@@ -654,7 +656,7 @@ export class LocalTime {
    * Returns e.g: `19840621_1705`
    */
   toStringCompact(seconds = false): string {
-    const { year, month, day, hour, minute, second } = this.getDateTimeObject()
+    const { year, month, day, hour, minute, second } = this.toDateTimeObject()
 
     return [
       String(year).padStart(4, '0'),
@@ -672,7 +674,7 @@ export class LocalTime {
   }
 
   toJSON(): UnixTimestampNumber {
-    return this.unix()
+    return this.unix
   }
 
   toMonthId(): MonthId {
@@ -690,90 +692,136 @@ export class LocalTime {
 
 class LocalTimeFactory {
   /**
-   * Parses input String into LocalDate.
-   * Input can already be a LocalDate - it is returned as-is in that case.
+   * Parses input String into LocalTime.
+   * Input can already be a LocalTime - it is returned as-is in that case.
    */
-  of(d: LocalTimeInput): LocalTime {
-    const t = this.parseOrNull(d)
+  from(input: LocalTimeInput): LocalTime {
+    const lt = this.fromOrNull(input)
+    this.assertNotNull(lt, input)
+    return lt
+  }
 
-    _assert(t !== null, `Cannot parse "${d}" into LocalTime`, {
-      input: d,
-    })
+  fromDate(date: Date): LocalTime {
+    return new LocalTime(date)
+  }
 
-    return t
+  fromUnix(ts: UnixTimestampNumber): LocalTime {
+    return new LocalTime(new Date(ts * 1000))
   }
 
   /**
    * Create LocalTime from unixTimestamp in milliseconds (not in seconds).
    */
-  ofMillis(millis: UnixTimestampMillisNumber): LocalTime {
-    return this.of(new Date(millis))
+  fromMillis(millis: UnixTimestampMillisNumber): LocalTime {
+    return new LocalTime(new Date(millis))
   }
 
   /**
    * Returns null if invalid
    */
-  parseOrNull(d: LocalTimeInputNullable): LocalTime | null {
+  fromOrNull(d: LocalTimeInputNullable): LocalTime | null {
     if (d instanceof LocalTime) return d
-
-    let date
-
     if (d instanceof Date) {
-      date = d
-    } else if (typeof d === 'number') {
-      date = new Date(d * 1000)
-    } else if (!d) {
-      // This check is after checking the number, to support `0`
-      return null
-    } else if (typeof (d as any) !== 'string') {
-      // unexpected type, e.g Function or something
+      return new LocalTime(d)
+    }
+    if (typeof d === 'number') {
+      return new LocalTime(new Date(d * 1000))
+    }
+    if (typeof d === 'string') {
+      return this.fromStringOrNull(d)
+    }
+    // This check is after checking the number, to support `0`
+    // unexpected type, e.g Function or something
+    return null
+  }
+
+  fromStringOrNull(s: string | undefined | null): LocalTime | null {
+    const date = this.parseStringToDateOrNull(s)
+    return date ? new LocalTime(date) : null
+  }
+
+  fromDateTimeObject(input: DateTimeObjectInput): LocalTime {
+    const { year, month, day = 1, hour = 0, minute = 0, second = 0 } = input
+    return new LocalTime(new Date(year, month - 1, day, hour, minute, second))
+  }
+
+  private parseStringToDateOrNull(s: string | undefined | null): Date | null {
+    if (!s) return null
+    // Slicing removes the "timezone component", and makes the date "local"
+    // e.g 2022-04-06T23:15:00+09:00
+    // becomes 2022-04-06T23:15:00
+    // date = new Date(d.slice(0, 19))
+
+    // Parsing is inspired by how Day.js does it
+    // Specifically, it ensures that `localTime('2023-03-03')` returns the expected Date, and not a day before
+    // Because `new Date('2023-03-03')` in NewYork gives you '2023-03-02 19:00:00 GMT-0500'
+
+    const m = s.match(DATE_TIME_REGEX)
+    // Validate in 3 ways:
+    // 1. Should match Regex.
+    // In some ways it's stricter than Date constructor, e.g it doesn't allow 2023/05/05
+    // In other ways it's looser, e.g it allows `2023-05-05T`, while Date constructor doesn't.
+    // 2. Date constructor (of Node/v8 implementation, which we know is different from e.g WebKit/Safari)
+    // should not return `Invalid Date`.
+    // 3. Year, month and day should be valid, e.g 2023-01-32 should not be allowed.
+    // UPD: Actually, 3 can be skipped, because 2 is catching it already
+    // UPD: 2 is skipped, 1 and 3 are kept
+    // if (!m || isNaN(new Date(s).getDate())) return null
+    if (!m) return null
+    const year = Number(m[1])
+    const month = Number(m[2])
+    const day = Number(m[3])
+    const hour = Number(m[5])
+    const minute = Number(m[6])
+    const second = Number(m[7])
+
+    // Validation for just the Date part
+    if (
+      !year ||
+      !month ||
+      month < 1 ||
+      month > 12 ||
+      !day ||
+      day < 1 ||
+      day > localDate.getMonthLength(year, month)
+    ) {
       return null
-    } else {
-      // Slicing removes the "timezone component", and makes the date "local"
-      // e.g 2022-04-06T23:15:00+09:00
-      // becomes 2022-04-06T23:15:00
-      date = new Date(d.slice(0, 19))
-      // We used to slice to remove the timezone information, now we don't
-      // date = new Date(d)
     }
 
-    // validation
-    if (isNaN(date.getDate())) {
-      // throw new TypeError(`Cannot parse "${d}" into LocalTime`)
+    // Validation for Date+Time string, since the string is longer than YYYY-MM-DD
+    if (
+      s.length > 10 &&
+      (isNaN(hour) ||
+        isNaN(minute) ||
+        isNaN(second) ||
+        hour < 0 ||
+        hour > 23 ||
+        minute < 0 ||
+        minute > 59 ||
+        second < 0 ||
+        second > 59)
+    ) {
       return null
     }
 
-    return new LocalTime(date)
+    return new Date(year, month - 1, day, hour || 0, minute || 0, second || 0, 0)
   }
 
-  parseToDate(d: LocalTimeInput): Date {
-    if (d instanceof LocalTime) return d.$date
-    if (d instanceof Date) return d
-
-    const date = typeof d === 'number' ? new Date(d * 1000) : new Date(d)
-
-    _assert(!isNaN(date.getDate()), `Cannot parse "${d}" to Date`, {
-      input: d,
-    })
-
-    return date
+  isValid(input: LocalTimeInputNullable): boolean {
+    return this.fromOrNull(input) !== null
   }
 
-  parseToUnixTimestamp(d: LocalTimeInput): UnixTimestampNumber {
-    if (typeof d === 'number') return d
-    if (d instanceof LocalTime) return d.unix()
-
-    const date = d instanceof Date ? d : new Date(d)
-
-    _assert(!isNaN(date.getDate()), `Cannot parse "${d}" to UnixTimestamp`, {
-      input: d,
-    })
-
-    return date.valueOf() / 1000
+  isValidString(isoString: string | undefined | null): boolean {
+    return this.fromStringOrNull(isoString) !== null
   }
 
-  isValid(d: LocalTimeInputNullable): boolean {
-    return this.parseOrNull(d) !== null
+  private assertNotNull(
+    lt: LocalTime | null,
+    input: LocalTimeInputNullable,
+  ): asserts lt is LocalTime {
+    _assert(lt !== null, `Cannot parse "${input}" into LocalTime`, {
+      input,
+    })
   }
 
   /**
@@ -804,21 +852,15 @@ class LocalTimeFactory {
    *
    * `localTime` function will instead return LocalTime of `now` for falsy input.
    */
-  orUndefined(d: LocalTimeInputNullable): LocalTime | undefined {
-    return d ? this.of(d) : undefined
+  orUndefined(input: LocalTimeInputNullable): LocalTime | undefined {
+    return input || input === 0 ? this.from(input) : undefined
   }
 
   /**
    * Creates a LocalTime from the input, unless it's falsy - then returns LocalTime.now
    */
-  orNow(d: LocalTimeInputNullable): LocalTime {
-    return d ? this.of(d) : this.now()
-  }
-
-  fromComponents(c: { year: number; month: number } & Partial<DateTimeObject>): LocalTime {
-    return new LocalTime(
-      new Date(c.year, c.month - 1, c.day || 1, c.hour || 0, c.minute || 0, c.second || 0),
-    )
+  orNow(input: LocalTimeInputNullable): LocalTime {
+    return input || input === 0 ? this.from(input) : this.now()
   }
 
   sort(items: LocalTime[], dir: SortDirection = 'asc', mutate = false): LocalTime[] {
@@ -840,7 +882,7 @@ class LocalTimeFactory {
     _assert(items2.length, 'localTime.min called on empty array')
 
     return items2
-      .map(i => this.of(i))
+      .map(i => this.from(i))
       .reduce((min, item) => (min.$date.valueOf() <= item.$date.valueOf() ? min : item))
   }
 
@@ -853,7 +895,7 @@ class LocalTimeFactory {
     _assert(items2.length, 'localTime.max called on empty array')
 
     return items2
-      .map(i => this.of(i))
+      .map(i => this.from(i))
       .reduce((max, item) => (max.$date.valueOf() >= item.$date.valueOf() ? max : item))
   }
 }
@@ -969,7 +1011,7 @@ interface LocalTimeFn extends LocalTimeFactory {
 
 const localTimeFactory = new LocalTimeFactory()
 
-export const localTime = localTimeFactory.of.bind(localTimeFactory) as LocalTimeFn
+export const localTime = localTimeFactory.from.bind(localTimeFactory) as LocalTimeFn
 
 // The line below is the blackest of black magic I have ever written in 2024.
 // And probably 2023 as well.

package/src/datetime/timeInterval.ts

@@ -17,10 +17,7 @@ export class TimeInterval {
   ) {}
 
   static of(start: LocalTimeInput, end: LocalTimeInput): TimeInterval {
-    return new TimeInterval(
-      localTime.parseToUnixTimestamp(start),
-      localTime.parseToUnixTimestamp(end),
-    )
+    return new TimeInterval(localTime.from(start).unix, localTime.from(end).unix)
   }
 
   get start(): UnixTimestampNumber {
@@ -77,7 +74,7 @@ export class TimeInterval {
   }
 
   includes(d: LocalTimeInput, incl: Inclusiveness = '[)'): boolean {
-    d = localTime.parseToUnixTimestamp(d)
+    d = localTime.from(d).unix
     // eslint-disable-next-line @typescript-eslint/prefer-string-starts-ends-with
     if (d < this.$start || (d === this.$start && incl[0] === '(')) return false
     if (d > this.$end || (d === this.$end && incl[1] === ')')) return false

package/src/env/buildInfo.ts

@@ -44,11 +44,11 @@ export interface BuildInfo {
 
 export function generateBuildInfoDev(): BuildInfo {
   const now = localTime.now()
-  const ts = now.unix()
+  const ts = now.unix
   const rev = 'devRev'
   const branchName = 'devBranch'
   const repoName = 'devRepo'
-  const tsCommit = now.unix()
+  const tsCommit = now.unix
 
   const ver = [now.toStringCompact(), repoName, branchName, rev].join('_')