@naturalcycles/js-lib 14.98.2 → 14.99.1

package/src/datetime/localDate.ts

@@ -1,14 +1,16 @@
 import { _assert } from '../error/assert'
-import { IsoDateString, UnixTimestampNumber } from '../types'
+import { IsoDateString, IsoDateTimeString, UnixTimestampNumber } from '../types'
 import { LocalTime } from './localTime'
 
-export type LocalDateUnit = 'year' | 'month' | 'day'
+export type LocalDateUnit = LocalDateUnitStrict | 'week'
+export type LocalDateUnitStrict = 'year' | 'month' | 'day'
 export type Inclusiveness = '()' | '[]' | '[)' | '(]'
 
 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)$/
 
 export type LocalDateConfig = LocalDate | IsoDateString
+export type LocalDateFormatter = (ld: LocalDate) => string
 
 /* eslint-disable no-dupe-class-members */
 
@@ -106,24 +108,28 @@ export class LocalDate {
     return (mutate ? items : [...items]).sort((a, b) => a.cmp(b) * mod)
   }
 
-  static earliestOrUndefined(items: LocalDate[]): LocalDate | undefined {
+  static earliestOrUndefined(items: LocalDateConfig[]): LocalDate | undefined {
     return items.length ? LocalDate.earliest(items) : undefined
   }
 
-  static earliest(items: LocalDate[]): LocalDate {
+  static earliest(items: LocalDateConfig[]): LocalDate {
     _assert(items.length, 'LocalDate.earliest called on empty array')
 
-    return items.reduce((min, item) => (min.isSameOrBefore(item) ? min : item))
+    return items
+      .map(i => LocalDate.of(i))
+      .reduce((min, item) => (min.isSameOrBefore(item) ? min : item))
   }
 
-  static latestOrUndefined(items: LocalDate[]): LocalDate | undefined {
+  static latestOrUndefined(items: LocalDateConfig[]): LocalDate | undefined {
     return items.length ? LocalDate.latest(items) : undefined
   }
 
-  static latest(items: LocalDate[]): LocalDate {
+  static latest(items: LocalDateConfig[]): LocalDate {
     _assert(items.length, 'LocalDate.latest called on empty array')
 
-    return items.reduce((max, item) => (max.isSameOrAfter(item) ? max : item))
+    return items
+      .map(i => LocalDate.of(i))
+      .reduce((max, item) => (max.isSameOrAfter(item) ? max : item))
   }
 
   static range(
@@ -133,6 +139,11 @@ export class LocalDate {
     step = 1,
     stepUnit: LocalDateUnit = 'day',
   ): LocalDate[] {
+    if (stepUnit === 'week') {
+      step *= 7
+      stepUnit = 'day'
+    }
+
     const dates: LocalDate[] = []
     const $min = LocalDate.of(min)
     const $max = LocalDate.of(max).startOf(stepUnit)
@@ -153,11 +164,11 @@ export class LocalDate {
     return dates
   }
 
-  get(unit: LocalDateUnit): number {
+  get(unit: LocalDateUnitStrict): number {
     return unit === 'year' ? this.$year : unit === 'month' ? this.$month : this.$day
   }
 
-  set(unit: LocalDateUnit, v: number, mutate = false): LocalDate {
+  set(unit: LocalDateUnitStrict, v: number, mutate = false): LocalDate {
     const t = mutate ? this : this.clone()
 
     if (unit === 'year') {
@@ -242,50 +253,69 @@ export class LocalDate {
   }
 
   /**
-   * Returns the number of **full** units difference (aka `Math.ceil`).
+   * Returns the number of **full** units difference (aka `Math.floor`).
    *
    * a.diff(b) means "a minus b"
    */
   diff(d: LocalDateConfig, unit: LocalDateUnit): number {
     d = LocalDate.of(d)
 
+    const sign = this.cmp(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') {
-      return this.$year - d.$year
+      let years = big.$year - small.$year
+
+      if (big.$month < small.$month || (big.$month === small.$month && big.$day < small.$day)) {
+        years--
+      }
+
+      return years * sign || 0
     }
 
     if (unit === 'month') {
-      return (this.$year - d.$year) * 12 + (this.$month - d.$month)
+      let months = (big.$year - small.$year) * 12 + (big.$month - small.$month)
+      if (big.$day < small.$day) months--
+      return months * sign || 0
     }
 
-    // unit is 'day'
-    let days = this.$day - d.$day
+    // unit is 'day' or 'week'
+    let days = big.$day - small.$day
 
-    if (d.$year < this.$year) {
-      for (let year = d.$year; year < this.$year; year++) {
-        days += LocalDate.getYearLength(year)
-      }
-    } else if (this.$year < d.$year) {
-      for (let year = this.$year; year < d.$year; year++) {
-        days -= LocalDate.getYearLength(year)
-      }
+    // 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)
     }
 
-    if (d.$month < this.$month) {
-      for (let month = d.$month; month < this.$month; month++) {
-        days += LocalDate.getMonthLength(this.$year, month)
+    if (small.$month < big.$month) {
+      for (let month = small.$month; month < big.$month; month++) {
+        days += LocalDate.getMonthLength(big.$year, month)
       }
-    } else if (this.$month < d.$month) {
-      for (let month = this.$month; month < d.$month; month++) {
-        days -= LocalDate.getMonthLength(d.$year, month)
+    } else if (big.$month < small.$month) {
+      for (let month = big.$month; month < small.$month; month++) {
+        days -= LocalDate.getMonthLength(big.$year, month)
       }
     }
 
-    return days
+    if (unit === 'week') {
+      return Math.trunc(days / 7) * sign || 0
+    }
+
+    return days * sign || 0
   }
 
   add(num: number, unit: LocalDateUnit, mutate = false): LocalDate {
     let { $day, $month, $year } = this
 
+    if (unit === 'week') {
+      num *= 7
+      unit = 'day'
+    }
+
     if (unit === 'day') {
       $day += num
     } else if (unit === 'month') {
@@ -346,14 +376,14 @@ export class LocalDate {
     return this.add(-num, unit, mutate)
   }
 
-  startOf(unit: LocalDateUnit): LocalDate {
+  startOf(unit: LocalDateUnitStrict): LocalDate {
     if (unit === 'day') return this
     if (unit === 'month') return LocalDate.create(this.$year, this.$month, 1)
     // year
     return LocalDate.create(this.$year, 1, 1)
   }
 
-  endOf(unit: LocalDateUnit): LocalDate {
+  endOf(unit: LocalDateUnitStrict): LocalDate {
     if (unit === 'day') return this
     if (unit === 'month')
       return LocalDate.create(
@@ -400,6 +430,13 @@ export class LocalDate {
     return this.toString()
   }
 
+  /**
+   * Returns e.g: `1984-06-21T17:56:21`
+   */
+  toISODateTime(): IsoDateTimeString {
+    return this.toString() + 'T00:00:00'
+  }
+
   toString(): IsoDateString {
     return [
       String(this.$year).padStart(4, '0'),
@@ -428,6 +465,10 @@ export class LocalDate {
   toJSON(): IsoDateString {
     return this.toString()
   }
+
+  format(fmt: LocalDateFormatter): string {
+    return fmt(this)
+  }
 }
 
 /**

package/src/datetime/localTime.ts

@@ -3,9 +3,20 @@ import { _ms } from '../time/time.util'
 import { IsoDateString, IsoDateTimeString, UnixTimestampNumber } from '../types'
 import { Inclusiveness, LocalDate } from './localDate'
 
-export type LocalTimeUnit = 'year' | 'month' | 'day' | 'hour' | 'minute' | 'second'
+export type LocalTimeUnit = 'year' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second'
+
+export enum ISODayOfWeek {
+  MONDAY = 1,
+  TUESDAY = 2,
+  WEDNESDAY = 3,
+  THURSDAY = 4,
+  FRIDAY = 5,
+  SATURDAY = 6,
+  SUNDAY = 7,
+}
 
 export type LocalTimeConfig = LocalTime | Date | IsoDateTimeString | UnixTimestampNumber
+export type LocalTimeFormatter = (ld: LocalTime) => string
 
 export interface LocalTimeComponents {
   year: number
@@ -16,6 +27,13 @@ export interface LocalTimeComponents {
   second: number
 }
 
+const weekStartsOn = 1 // mon, as per ISO
+const MILLISECONDS_IN_WEEK = 604800000
+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])
+
 /* eslint-disable no-dupe-class-members */
 
 /**
@@ -134,6 +152,9 @@ export class LocalTime {
     if (unit === 'minute') {
       return this.utcMode ? this.$date.getUTCMinutes() : this.$date.getMinutes()
     }
+    if (unit === 'week') {
+      return getWeek(this.$date)
+    }
     // second
     return this.utcMode ? this.$date.getUTCSeconds() : this.$date.getSeconds()
   }
@@ -154,6 +175,8 @@ export class LocalTime {
       this.utcMode ? t.$date.setUTCMinutes(v) : t.$date.setMinutes(v)
     } else if (unit === 'second') {
       this.utcMode ? t.$date.setUTCSeconds(v) : t.$date.setSeconds(v)
+    } else if (unit === 'week') {
+      setWeek(t.$date, v, true)
     }
     /* eslint-enable @typescript-eslint/no-unused-expressions */
 
@@ -170,11 +193,33 @@ export class LocalTime {
   month(v?: number): number | LocalTime {
     return v === undefined ? this.get('month') : this.set('month', v)
   }
+  week(): number
+  week(v: number): LocalTime
+  week(v?: number): number | LocalTime {
+    return v === undefined ? getWeek(this.$date) : this.set('week', v)
+  }
   day(): number
   day(v: number): LocalTime
   day(v?: number): number | LocalTime {
     return v === undefined ? this.get('day') : this.set('day', 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
+    }
+
+    if (!VALID_DAYS_OF_WEEK.has(v)) throw new Error(`Invalid dayOfWeek: ${v}`)
+
+    return this.add(v - dow, 'day')
+  }
   hour(): number
   hour(v: number): LocalTime
   hour(v?: number): number | LocalTime {
@@ -219,6 +264,10 @@ export class LocalTime {
   }
 
   add(num: number, unit: LocalTimeUnit, mutate = false): LocalTime {
+    if (unit === 'week') {
+      num *= 7
+      unit = 'day'
+    }
     return this.set(unit, this.get(unit) + num, mutate)
   }
 
@@ -233,24 +282,45 @@ export class LocalTime {
   diff(other: LocalTimeConfig, unit: LocalTimeUnit): number {
     const date2 = LocalTime.parseToDate(other)
 
-    if (unit === 'year') {
-      return this.$date.getFullYear() - date2.getFullYear()
-    }
-    if (unit === 'month') {
-      return (
-        (this.$date.getFullYear() - date2.getFullYear()) * 12 +
-        this.$date.getMonth() -
-        date2.getMonth()
-      )
+    const secDiff = (this.$date.valueOf() - date2.valueOf()) / 1000
+    if (!secDiff) return 0
+
+    if (unit === 'year' || unit === 'month') {
+      const sign = secDiff > 0 ? 1 : -1
+
+      // Put items in descending order: "big minus small"
+      const [big, small] = sign === 1 ? [this.$date, date2] : [date2, this.$date]
+
+      if (unit === 'year') {
+        let years = big.getFullYear() - small.getFullYear()
+        const big2 = new Date(big)
+        const small2 = new Date(small)
+        big2.setFullYear(1584)
+        small2.setFullYear(1584)
+        if (big2 < small2) years--
+        return years * sign || 0
+      }
+
+      if (unit === 'month') {
+        let months =
+          (big.getFullYear() - small.getFullYear()) * 12 + big.getMonth() - small.getMonth()
+        const big2 = new Date(big)
+        const small2 = new Date(small)
+        big2.setFullYear(1584, 0)
+        small2.setFullYear(1584, 0)
+        if (big2 < small2) months--
+        return months * sign || 0
+      }
     }
 
-    const secDiff = (this.$date.valueOf() - date2.valueOf()) / 1000
     let r
 
     if (unit === 'day') {
-      r = secDiff / (24 * 60 * 60)
+      r = secDiff / SECONDS_IN_DAY
+    } else if (unit === 'week') {
+      r = secDiff / (7 * 24 * 60 * 60)
     } else if (unit === 'hour') {
-      r = secDiff / (60 * 60)
+      r = secDiff / 3600
     } else if (unit === 'minute') {
       r = secDiff / 60
     } else {
@@ -258,26 +328,63 @@ export class LocalTime {
       r = secDiff
     }
 
-    r = r < 0 ? -Math.floor(-r) : Math.floor(r)
-    if (Object.is(r, -0)) return 0
-    return r
+    // `|| 0` is to avoid returning -0
+    return Math.trunc(r) || 0
   }
 
   startOf(unit: LocalTimeUnit, mutate = false): LocalTime {
     if (unit === 'second') return this
-
     const d = mutate ? this.$date : new Date(this.$date)
+    d.setSeconds(0, 0)
 
     /* eslint-disable @typescript-eslint/no-unused-expressions */
-    this.utcMode ? d.setUTCSeconds(0) : d.setSeconds(0)
     if (unit !== 'minute') {
       this.utcMode ? d.setUTCMinutes(0) : d.setMinutes(0)
       if (unit !== 'hour') {
         this.utcMode ? d.setUTCHours(0) : d.setHours(0)
         if (unit !== 'day') {
-          this.utcMode ? d.setUTCDate(0) : d.setDate(0)
-          if (unit !== 'month') {
+          // year, month or week
+
+          if (unit === 'year') {
             this.utcMode ? d.setUTCMonth(0) : d.setMonth(0)
+            this.utcMode ? d.setUTCDate(1) : d.setDate(1)
+          } else if (unit === 'month') {
+            this.utcMode ? d.setUTCDate(1) : d.setDate(1)
+          } else {
+            // week
+            startOfWeek(d, true)
+          }
+        }
+      }
+    }
+    /* eslint-enable @typescript-eslint/no-unused-expressions */
+
+    return mutate ? this : new LocalTime(d, this.utcMode)
+  }
+
+  endOf(unit: LocalTimeUnit, mutate = false): LocalTime {
+    if (unit === 'second') return this
+    const d = mutate ? this.$date : new Date(this.$date)
+    d.setSeconds(59, 0)
+
+    /* eslint-disable @typescript-eslint/no-unused-expressions */
+    if (unit !== 'minute') {
+      this.utcMode ? d.setUTCMinutes(59) : d.setMinutes(59)
+      if (unit !== 'hour') {
+        this.utcMode ? d.setUTCHours(23) : d.setHours(23)
+        if (unit !== 'day') {
+          // year, month or week
+
+          if (unit === 'year') {
+            this.utcMode ? d.setUTCMonth(11) : d.setMonth(11)
+          }
+
+          if (unit === 'week') {
+            endOfWeek(d, true)
+          } else {
+            // year or month
+            const lastDay = LocalDate.getMonthLength(d.getFullYear(), d.getMonth() + 1)
+            this.utcMode ? d.setUTCDate(lastDay) : d.setDate(lastDay)
           }
         }
       }
@@ -297,24 +404,28 @@ export class LocalTime {
     })
   }
 
-  static earliestOrUndefined(items: LocalTime[]): LocalTime | undefined {
+  static earliestOrUndefined(items: LocalTimeConfig[]): LocalTime | undefined {
     return items.length ? LocalTime.earliest(items) : undefined
   }
 
-  static earliest(items: LocalTime[]): LocalTime {
+  static earliest(items: LocalTimeConfig[]): LocalTime {
     _assert(items.length, 'LocalTime.earliest called on empty array')
 
-    return items.reduce((min, item) => (min.isSameOrBefore(item) ? min : item))
+    return items
+      .map(i => LocalTime.of(i))
+      .reduce((min, item) => (min.isSameOrBefore(item) ? min : item))
   }
 
-  static latestOrUndefined(items: LocalTime[]): LocalTime | undefined {
+  static latestOrUndefined(items: LocalTimeConfig[]): LocalTime | undefined {
     return items.length ? LocalTime.latest(items) : undefined
   }
 
-  static latest(items: LocalTime[]): LocalTime {
+  static latest(items: LocalTimeConfig[]): LocalTime {
     _assert(items.length, 'LocalTime.latest called on empty array')
 
-    return items.reduce((max, item) => (max.isSameOrAfter(item) ? max : item))
+    return items
+      .map(i => LocalTime.of(i))
+      .reduce((max, item) => (max.isSameOrAfter(item) ? max : item))
   }
 
   isSame(d: LocalTimeConfig): boolean {
@@ -359,8 +470,6 @@ export class LocalTime {
     return t1 < t2 ? -1 : 1
   }
 
-  // todo: endOf
-
   components(): LocalTimeComponents {
     if (this.utcMode) {
       return {
@@ -458,7 +567,7 @@ export class LocalTime {
   }
 
   /**
-   * Returns e.g: `1984-06-21T17:56:21`, only the date part of DateTime
+   * Returns e.g: `1984-06-21T17:56:21`
    */
   toISODateTime(): IsoDateTimeString {
     return this.$date.toISOString().slice(0, 19)
@@ -519,6 +628,10 @@ export class LocalTime {
   toJSON(): UnixTimestampNumber {
     return this.unix()
   }
+
+  format(fmt: LocalTimeFormatter): string {
+    return fmt(this)
+  }
 }
 
 /**
@@ -527,3 +640,97 @@ export class LocalTime {
 export function localTime(d?: LocalTimeConfig): LocalTime {
   return d ? LocalTime.of(d) : LocalTime.now()
 }
+
+// based on: https://github.com/date-fns/date-fns/blob/master/src/getISOWeek/index.ts
+function getWeek(date: Date): number {
+  const diff = startOfWeek(date).getTime() - startOfWeekYear(date).getTime()
+  return Math.round(diff / MILLISECONDS_IN_WEEK) + 1
+}
+
+function setWeek(date: Date, week: number, mutate = false): Date {
+  const d = mutate ? date : new Date(date)
+  const diff = getWeek(d) - week
+  d.setDate(d.getDate() - diff * 7)
+  return d
+}
+
+// based on: https://github.com/date-fns/date-fns/blob/master/src/startOfISOWeekYear/index.ts
+function startOfWeekYear(date: Date): Date {
+  const year = getWeekYear(date)
+  const fourthOfJanuary = new Date(0)
+  fourthOfJanuary.setFullYear(year, 0, 4)
+  fourthOfJanuary.setHours(0, 0, 0, 0)
+  return startOfWeek(fourthOfJanuary, true)
+}
+
+// based on: https://github.com/date-fns/date-fns/blob/fd6bb1a0bab143f2da068c05a9c562b9bee1357d/src/getISOWeekYear/index.ts
+function getWeekYear(date: Date): number {
+  const year = date.getFullYear()
+
+  const fourthOfJanuaryOfNextYear = new Date(0)
+  fourthOfJanuaryOfNextYear.setFullYear(year + 1, 0, 4)
+  fourthOfJanuaryOfNextYear.setHours(0, 0, 0, 0)
+  const startOfNextYear = startOfWeek(fourthOfJanuaryOfNextYear, true)
+
+  const fourthOfJanuaryOfThisYear = new Date(0)
+  fourthOfJanuaryOfThisYear.setFullYear(year, 0, 4)
+  fourthOfJanuaryOfThisYear.setHours(0, 0, 0, 0)
+  const startOfThisYear = startOfWeek(fourthOfJanuaryOfThisYear, true)
+
+  if (date.getTime() >= startOfNextYear.getTime()) {
+    return year + 1
+  } else if (date.getTime() >= startOfThisYear.getTime()) {
+    return year
+  } else {
+    return year - 1
+  }
+}
+
+// function setWeekYear(
+//   date: Date,
+//   year: number,
+// ): Date {
+//   const diff = differenceInCalendarDays(date, startOfWeekYear(date))
+//   const fourthOfJanuary = new Date(0)
+//   fourthOfJanuary.setFullYear(year, 0, 4)
+//   fourthOfJanuary.setHours(0, 0, 0, 0)
+//   date = startOfWeekYear(fourthOfJanuary)
+//   date.setDate(date.getDate() + diff)
+//   return date
+// }
+
+// function differenceInCalendarDays(
+//   dateLeft: Date,
+//   dateRight: Date,
+// ): number {
+//   return Math.round((startOfDay(dateLeft).getTime() - startOfDay(dateRight).getTime()) / MILLISECONDS_IN_DAY)
+// }
+
+// function startOfDay(date: Date, mutate = false): Date {
+//   const d = mutate ? date : new Date(date)
+//   d.setHours(0, 0, 0, 0)
+//   return d
+// }
+
+// based on: https://github.com/date-fns/date-fns/blob/fd6bb1a0bab143f2da068c05a9c562b9bee1357d/src/startOfWeek/index.ts
+function startOfWeek(date: Date, mutate = false): Date {
+  const d = mutate ? date : new Date(date)
+
+  const day = d.getDay()
+  const diff = (day < weekStartsOn ? 7 : 0) + day - weekStartsOn
+
+  d.setDate(d.getDate() - diff)
+  d.setHours(0, 0, 0, 0)
+  return d
+}
+
+// based on: https://github.com/date-fns/date-fns/blob/master/src/endOfWeek/index.ts
+function endOfWeek(date: Date, mutate = false): Date {
+  const d = mutate ? date : new Date(date)
+
+  const day = d.getDay()
+  const diff = (day < weekStartsOn ? -7 : 0) + 6 - (day - weekStartsOn)
+
+  d.setDate(d.getDate() + diff)
+  return d
+}

package/src/index.ts

@@ -162,8 +162,20 @@ export * from './datetime/localDate'
 export * from './datetime/localTime'
 export * from './datetime/dateInterval'
 export * from './datetime/timeInterval'
-import { LocalDateConfig, LocalDateUnit, Inclusiveness } from './datetime/localDate'
-import { LocalTimeConfig, LocalTimeUnit, LocalTimeComponents } from './datetime/localTime'
+import {
+  LocalDateConfig,
+  LocalDateFormatter,
+  LocalDateUnit,
+  LocalDateUnitStrict,
+  Inclusiveness,
+} from './datetime/localDate'
+import {
+  LocalTimeConfig,
+  LocalTimeFormatter,
+  LocalTimeUnit,
+  LocalTimeComponents,
+  ISODayOfWeek,
+} from './datetime/localTime'
 import { DateIntervalConfig, DateIntervalString } from './datetime/dateInterval'
 import { TimeIntervalConfig, TimeIntervalString } from './datetime/timeInterval'
 
@@ -173,10 +185,14 @@ export type {
   TimeIntervalConfig,
   TimeIntervalString,
   LocalDateConfig,
+  LocalDateFormatter,
   LocalDateUnit,
+  LocalDateUnitStrict,
   Inclusiveness,
   LocalTimeConfig,
+  LocalTimeFormatter,
   LocalTimeUnit,
+  ISODayOfWeek,
   LocalTimeComponents,
   AbortableMapper,
   AbortablePredicate,

package/src/promise/pRetry.ts

@@ -169,7 +169,7 @@ export async function pRetry<T>(
 
         const r = await fn(attempt)
 
-        clearTimeout(timer!)
+        clearTimeout(timer)
 
         if (logSuccess) {
           logger.log(`${fname} attempt #${attempt} succeeded in ${_since(started)}`)
@@ -177,7 +177,7 @@ export async function pRetry<T>(
 
         resolve(r)
       } catch (err) {
-        clearTimeout(timer!)
+        clearTimeout(timer)
 
         if (logFailures) {
           logger.warn(