@naturalcycles/js-lib 14.88.0 → 14.89.0

package/src/datetime/localDate.ts

@@ -0,0 +1,355 @@
+import { _assert } from '../error/assert'
+import { Sequence } from '../seq/seq'
+import { END, IsoDate } from '../types'
+
+export type LocalDateUnit = 'year' | 'month' | 'day'
+
+const m31 = new Set<number>([1, 3, 5, 7, 8, 10, 12])
+
+export type LocalDateConfig = LocalDate | string
+
+/**
+ * @experimental
+ */
+export class LocalDate {
+  private constructor(public year: number, public month: number, public day: number) {}
+
+  static create(year: number, month: number, day: number): LocalDate {
+    return new LocalDate(year, month, day)
+  }
+
+  /**
+   * Parses input String into LocalDate.
+   * Input can already be a LocalDate - it is returned as-is in that case.
+   */
+  static of(d: LocalDateConfig): LocalDate {
+    if (d instanceof LocalDate) return d
+
+    const [year, month, day] = d.slice(0, 10).split('-').map(Number)
+
+    if (!day || !month || (!year && year !== 0)) {
+      throw new Error(`Cannot parse "${d}" into LocalDate`)
+    }
+
+    return new LocalDate(year, month, day)
+  }
+
+  static parseCompact(d: string): LocalDate {
+    const [year, month, day] = [d.slice(0, 4), d.slice(4, 2), d.slice(6, 2)].map(Number)
+
+    if (!day || !month || (!year && year !== 0)) {
+      throw new Error(`Cannot parse "${d}" into LocalDate`)
+    }
+
+    return new LocalDate(year, month, day)
+  }
+
+  static fromDate(d: Date): LocalDate {
+    return new LocalDate(d.getFullYear(), d.getMonth() + 1, d.getDate())
+  }
+
+  static today(): LocalDate {
+    return this.fromDate(new Date())
+  }
+
+  static sort(items: LocalDate[], mutate = false, descending = false): LocalDate[] {
+    const mod = descending ? -1 : 1
+    return (mutate ? items : [...items]).sort((a, b) => a.cmp(b) * mod)
+  }
+
+  static earliestOrUndefined(items: LocalDate[]): LocalDate | undefined {
+    return items.length ? LocalDate.earliest(items) : undefined
+  }
+
+  static earliest(items: LocalDate[]): LocalDate {
+    _assert(items.length, 'LocalDate.earliest called on empty array')
+
+    return items.reduce((min, item) => (min.isSameOrBefore(item) ? min : item))
+  }
+
+  static latestOrUndefined(items: LocalDate[]): LocalDate | undefined {
+    return items.length ? LocalDate.latest(items) : undefined
+  }
+
+  static latest(items: LocalDate[]): LocalDate {
+    _assert(items.length, 'LocalDate.latest called on empty array')
+
+    return items.reduce((max, item) => (max.isSameOrAfter(item) ? max : item))
+  }
+
+  static range(
+    minIncl: LocalDateConfig,
+    maxExcl: LocalDateConfig,
+    step = 1,
+    stepUnit: LocalDateUnit = 'day',
+  ): LocalDate[] {
+    const days: LocalDate[] = []
+    let current = LocalDate.of(minIncl).startOf(stepUnit)
+    const max = LocalDate.of(maxExcl).startOf(stepUnit)
+
+    do {
+      days.push(current)
+      current = current.add(step, stepUnit)
+    } while (current.isBefore(max))
+
+    return days
+  }
+
+  static rangeSeq(
+    minIncl: LocalDateConfig,
+    maxExcl: LocalDateConfig,
+    step = 1,
+    stepUnit: LocalDateUnit = 'day',
+  ): Sequence<LocalDate> {
+    const min = LocalDate.of(minIncl).startOf(stepUnit)
+    const max = LocalDate.of(maxExcl).startOf(stepUnit)
+    return Sequence.create(min, d => {
+      const next = d.add(step, stepUnit)
+      return next.isAfter(max) ? END : next
+    })
+  }
+
+  static rangeString(
+    minIncl: LocalDateConfig,
+    maxExcl: LocalDateConfig,
+    step = 1,
+    stepUnit: LocalDateUnit = 'day',
+  ): IsoDate[] {
+    return LocalDate.range(minIncl, maxExcl, step, stepUnit).map(ld => ld.toString())
+  }
+
+  static rangeIncl(
+    minIncl: LocalDateConfig,
+    maxIncl: LocalDateConfig,
+    step = 1,
+    stepUnit: LocalDateUnit = 'day',
+  ): LocalDate[] {
+    return LocalDate.range(minIncl, LocalDate.of(maxIncl).add(1, stepUnit), step, stepUnit)
+  }
+
+  static rangeInclString(
+    minIncl: LocalDateConfig,
+    maxIncl: LocalDateConfig,
+    step = 1,
+    stepUnit: LocalDateUnit = 'day',
+  ): IsoDate[] {
+    return LocalDate.range(minIncl, LocalDate.of(maxIncl).add(1, stepUnit), step, stepUnit).map(
+      ld => ld.toString(),
+    )
+  }
+
+  isSame(d: LocalDateConfig): boolean {
+    d = LocalDate.of(d)
+    return this.day === d.day && this.month === d.month && this.year === d.year
+  }
+
+  isBefore(d: LocalDateConfig): boolean {
+    return this.cmp(d) === -1
+  }
+
+  isSameOrBefore(d: LocalDateConfig): boolean {
+    return this.cmp(d) <= 0
+  }
+
+  isAfter(d: LocalDateConfig): boolean {
+    return this.cmp(d) === 1
+  }
+
+  isSameOrAfter(d: LocalDateConfig): boolean {
+    return this.cmp(d) >= 0
+  }
+
+  /**
+   * Returns 1 if this > d
+   * returns 0 if they are equal
+   * returns -1 if this < d
+   */
+  cmp(d: LocalDateConfig): -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
+    return 0
+  }
+
+  /**
+   * Same as Math.abs( diff )
+   */
+  absDiff(d: LocalDateConfig, unit: LocalDateUnit): number {
+    return Math.abs(this.diff(d, unit))
+  }
+
+  /**
+   * Returns the number of **full** units difference (aka `Math.ceil`).
+   *
+   * a.diff(b) means "a minus b"
+   */
+  diff(d: LocalDateConfig, unit: LocalDateUnit): number {
+    d = LocalDate.of(d)
+
+    if (unit === 'year') {
+      return this.year - d.year
+    }
+
+    if (unit === 'month') {
+      return (this.year - d.year) * 12 + (this.month - d.month)
+    }
+
+    // unit is 'day'
+    let days = this.day - d.day
+
+    if (d.year < this.year) {
+      for (let year = d.year; year < this.year; year++) {
+        days += this.getYearDays(year)
+      }
+    } else if (this.year < d.year) {
+      for (let year = this.year; year < d.year; year++) {
+        days -= this.getYearDays(year)
+      }
+    }
+
+    if (d.month < this.month) {
+      for (let month = d.month; month < this.month; month++) {
+        days += this.getMonthLen(this.year, month)
+      }
+    } else if (this.month < d.month) {
+      for (let month = this.month; month < d.month; month++) {
+        days -= this.getMonthLen(d.year, month)
+      }
+    }
+
+    return days
+  }
+
+  add(num: number, unit: LocalDateUnit, mutate = false): LocalDate {
+    let { day, month, year } = this
+
+    if (unit === 'day') {
+      day += num
+    } else if (unit === 'month') {
+      month += num
+    } else if (unit === 'year') {
+      year += num
+    }
+
+    // check day overflow
+    let monLen = this.getMonthLen(year, month)
+    while (day > monLen) {
+      day -= monLen
+      month += 1
+      if (month > 12) {
+        year += 1
+        month -= 12
+      }
+
+      monLen = this.getMonthLen(year, month)
+    }
+    while (day < 1) {
+      day += monLen
+      month -= 1
+      if (month < 1) {
+        year -= 1
+        month += 12
+      }
+
+      monLen = this.getMonthLen(year, month)
+    }
+
+    // check month overflow
+    while (month > 12) {
+      year += 1
+      month -= 12
+    }
+    while (month < 1) {
+      year -= 1
+      month += 12
+    }
+
+    if (mutate) {
+      this.year = year
+      this.month = month
+      this.day = day
+      return this
+    }
+
+    return new LocalDate(year, month, day)
+  }
+
+  subtract(num: number, unit: LocalDateUnit, mutate = false): LocalDate {
+    return this.add(-num, unit, mutate)
+  }
+
+  startOf(unit: LocalDateUnit): 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 {
+    if (unit === 'day') return this
+    if (unit === 'month')
+      return LocalDate.create(this.year, this.month, this.getMonthLen(this.year, this.month))
+    // year
+    return LocalDate.create(this.year, 12, 31)
+  }
+
+  private getYearDays(year: number): number {
+    return this.isLeapYear(year) ? 366 : 365
+  }
+
+  private getMonthLen(year: number, month: number): number {
+    if (month === 2) return this.isLeapYear(year) ? 29 : 28
+    return m31.has(month) ? 31 : 30
+  }
+
+  private isLeapYear(year: number): boolean {
+    if (year % 4 !== 0) return false
+    if (year % 100 !== 0) return true
+    return year % 400 === 0
+  }
+
+  clone(): LocalDate {
+    return new LocalDate(this.year, this.month, this.day)
+  }
+
+  /**
+   * Converts LocalDate into instance of Date.
+   * Year, month and day will match.
+   * Hour, minute, second, ms will be 0.
+   * Timezone will match local timezone.
+   */
+  toDate(): Date {
+    return new Date(this.year, this.month - 1, this.day)
+  }
+
+  toString(): IsoDate {
+    return [
+      String(this.year).padStart(4, '0'),
+      String(this.month).padStart(2, '0'),
+      String(this.day).padStart(2, '0'),
+    ].join('-')
+  }
+
+  toStringCompact(): string {
+    return [
+      String(this.year).padStart(4, '0'),
+      String(this.month).padStart(2, '0'),
+      String(this.day).padStart(2, '0'),
+    ].join('')
+  }
+
+  toJSON(): IsoDate {
+    return this.toString()
+  }
+}
+
+/**
+ * Shortcut wrapper around `LocalDate.parse` / `LocalDate.today`
+ */
+export function localDate(d?: LocalDateConfig): LocalDate {
+  return d ? LocalDate.of(d) : LocalDate.today()
+}

package/src/datetime/localTime.ts

@@ -0,0 +1,362 @@
+import { _assert } from '../error/assert'
+import { IsoDateTime, UnixTimestamp } from '../types'
+
+export type LocalTimeUnit = 'year' | 'month' | 'day' | 'hour' | 'minute' | 'second'
+
+export type LocalTimeConfig = LocalTime | Date | IsoDateTime | UnixTimestamp
+
+export interface LocalTimeComponents {
+  year: number
+  month: number
+  day: number
+  hour: number
+  minute: number
+  second: number
+}
+
+/* eslint-disable no-dupe-class-members */
+
+// Design choices:
+// No milliseconds
+// No timezone support, ISO8601 is parsed as LocalDateTime, discarding Timezone information
+// Formats as unix timestamp, ISO8601 or "pretty string"
+// toString and .toJSON formats as unix timestamp
+// No "unixMillis", just pure unixtimestamp
+// .valueOf returns unix timestamp (no millis)
+// Prevents dayjs(undefined) being dayjs.now()
+// Validates on parse, throws if invalid. Doesn't allow invalid objects
+/**
+ * @experimental
+ */
+export class LocalTime {
+  private constructor(private $date: Date) {}
+
+  /**
+   * Parses input String into LocalDate.
+   * Input can already be a LocalDate - it is returned as-is in that case.
+   */
+  static of(d: LocalTimeConfig): LocalTime {
+    if (d instanceof LocalTime) return d
+    if (d instanceof Date) return new LocalTime(d)
+
+    if (typeof d === 'number') {
+      // unix timestamp
+      return new LocalTime(new Date(d * 1000))
+    }
+
+    const date = new Date(d)
+
+    // validation
+    if (isNaN(date.getDate())) {
+      throw new TypeError(`Cannot parse "${d}" into LocalTime`)
+    }
+
+    return new LocalTime(date)
+  }
+
+  static unix(ts: UnixTimestamp): LocalTime {
+    return new LocalTime(new Date(ts * 1000))
+  }
+
+  static now(): LocalTime {
+    return this.of(new Date())
+  }
+
+  static fromComponents(
+    c: { year: number; month: number } & Partial<LocalTimeComponents>,
+  ): LocalTime {
+    return new LocalTime(new Date(c.year, c.month - 1, c.day, c.hour, c.minute, c.second))
+  }
+
+  get(unit: LocalTimeUnit): number {
+    if (unit === 'year') {
+      return this.$date.getFullYear()
+    }
+    if (unit === 'month') {
+      return this.$date.getMonth() + 1
+    }
+    if (unit === 'day') {
+      return this.$date.getDate()
+    }
+    if (unit === 'hour') {
+      return this.$date.getHours()
+    }
+    if (unit === 'minute') {
+      return this.$date.getMinutes()
+    }
+    // second
+    return this.$date.getSeconds()
+  }
+
+  set(unit: LocalTimeUnit, v: number, mutate = false): LocalTime {
+    const t = mutate ? this : this.clone()
+
+    if (unit === 'year') {
+      t.$date.setFullYear(v)
+    } else if (unit === 'month') {
+      t.$date.setMonth(v - 1)
+    } else if (unit === 'day') {
+      t.$date.setDate(v)
+    } else if (unit === 'hour') {
+      t.$date.setHours(v)
+    } else if (unit === 'minute') {
+      t.$date.setMinutes(v)
+    } else if (unit === 'second') {
+      t.$date.setSeconds(v)
+    }
+
+    return t
+  }
+
+  year(): number
+  year(v: number): LocalTime
+  year(v?: number): number | LocalTime {
+    return v === undefined ? this.$date.getFullYear() : this.set('year', v)
+  }
+  month(): number
+  month(v: number): LocalTime
+  month(v?: number): number | LocalTime {
+    return v === undefined ? this.$date.getMonth() + 1 : this.set('month', v)
+  }
+  date(): number
+  date(v: number): LocalTime
+  date(v?: number): number | LocalTime {
+    return v === undefined ? this.$date.getDate() : this.set('day', v)
+  }
+  hour(): number
+  hour(v: number): LocalTime
+  hour(v?: number): number | LocalTime {
+    return v === undefined ? this.$date.getHours() : this.set('hour', v)
+  }
+  minute(): number
+  minute(v: number): LocalTime
+  minute(v?: number): number | LocalTime {
+    return v === undefined ? this.$date.getMinutes() : this.set('minute', v)
+  }
+  second(): number
+  second(v: number): LocalTime
+  second(v?: number): number | LocalTime {
+    return v === undefined ? this.$date.getSeconds() : this.set('second', v)
+  }
+
+  setComponents(c: Partial<LocalTimeComponents>, mutate = false): LocalTime {
+    const d = mutate ? this.$date : new Date(this.$date)
+
+    if (c.year) {
+      d.setFullYear(c.year)
+    }
+    if (c.month) {
+      d.setMonth(c.month - 1)
+    }
+    if (c.day) {
+      d.setDate(c.day)
+    }
+    if (c.hour !== undefined) {
+      d.setHours(c.hour)
+    }
+    if (c.minute !== undefined) {
+      d.setMinutes(c.minute)
+    }
+    if (c.second !== undefined) {
+      d.setSeconds(c.second)
+    }
+
+    return mutate ? this : new LocalTime(d)
+  }
+
+  add(num: number, unit: LocalTimeUnit, mutate = false): LocalTime {
+    return this.set(unit, this.get(unit) + num, mutate)
+  }
+
+  subtract(num: number, unit: LocalTimeUnit, mutate = false): LocalTime {
+    return this.add(-num, unit, mutate)
+  }
+
+  absDiff(other: LocalTimeConfig, unit: LocalTimeUnit): number {
+    return Math.abs(this.diff(other, unit))
+  }
+
+  diff(other: LocalTimeConfig, unit: LocalTimeUnit): number {
+    const date2 = LocalTime.of(other).$date
+
+    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
+    let r
+
+    if (unit === 'day') {
+      r = secDiff / (24 * 60 * 60)
+    } else if (unit === 'hour') {
+      r = secDiff / (60 * 60)
+    } else if (unit === 'minute') {
+      r = secDiff / 60
+    } else {
+      // unit === 'second'
+      r = secDiff
+    }
+
+    r = r < 0 ? -Math.floor(-r) : Math.floor(r)
+    if (Object.is(r, -0)) return 0
+    return r
+  }
+
+  startOf(unit: LocalTimeUnit, mutate = false): LocalTime {
+    if (unit === 'second') return this
+
+    if (mutate) {
+      const d = this.$date
+      d.setSeconds(0)
+      if (unit === 'minute') return this
+      d.setMinutes(0)
+      if (unit === 'hour') return this
+      d.setHours(0)
+      if (unit === 'day') return this
+      d.setDate(0)
+      if (unit === 'month') return this
+      d.setMonth(0)
+      return this
+    }
+
+    const c = this.components()
+
+    c.second = 0
+    if (unit === 'year') {
+      c.month = c.day = 1
+      c.hour = c.minute = 0
+    } else if (unit === 'month') {
+      c.day = 1
+      c.hour = c.minute = 0
+    } else if (unit === 'day') {
+      c.hour = c.minute = 0
+    } else if (unit === 'hour') {
+      c.minute = 0
+    }
+
+    return LocalTime.fromComponents(c)
+  }
+
+  static sort(items: LocalTime[], mutate = false, descending = false): LocalTime[] {
+    const mod = descending ? -1 : 1
+    return (mutate ? items : [...items]).sort((a, b) => {
+      const v1 = a.$date.valueOf()
+      const v2 = b.$date.valueOf()
+      if (v1 === v2) return 0
+      return (v1 < v2 ? -1 : 1) * mod
+    })
+  }
+
+  static earliestOrUndefined(items: LocalTime[]): LocalTime | undefined {
+    return items.length ? LocalTime.earliest(items) : undefined
+  }
+
+  static earliest(items: LocalTime[]): LocalTime {
+    _assert(items.length, 'LocalTime.earliest called on empty array')
+
+    return items.reduce((min, item) => (min.isSameOrBefore(item) ? min : item))
+  }
+
+  static latestOrUndefined(items: LocalTime[]): LocalTime | undefined {
+    return items.length ? LocalTime.latest(items) : undefined
+  }
+
+  static latest(items: LocalTime[]): LocalTime {
+    _assert(items.length, 'LocalTime.latest called on empty array')
+
+    return items.reduce((max, item) => (max.isSameOrAfter(item) ? max : item))
+  }
+
+  isSame(d: LocalTimeConfig): boolean {
+    return this.cmp(d) === 0
+  }
+
+  isBefore(d: LocalTimeConfig): boolean {
+    return this.cmp(d) === -1
+  }
+
+  isSameOrBefore(d: LocalTimeConfig): boolean {
+    return this.cmp(d) <= 0
+  }
+
+  isAfter(d: LocalTimeConfig): boolean {
+    return this.cmp(d) === 1
+  }
+
+  isSameOrAfter(d: LocalTimeConfig): boolean {
+    return this.cmp(d) >= 0
+  }
+
+  /**
+   * Returns 1 if this > d
+   * returns 0 if they are equal
+   * returns -1 if this < d
+   */
+  cmp(d: LocalTimeConfig): -1 | 0 | 1 {
+    const t1 = this.$date.valueOf()
+    const t2 = LocalTime.of(d).$date.valueOf()
+    if (t1 === t2) return 0
+    return t1 < t2 ? -1 : 1
+  }
+
+  // todo: endOf
+
+  components(): LocalTimeComponents {
+    return {
+      year: this.$date.getFullYear(),
+      month: this.$date.getMonth() + 1,
+      day: this.$date.getDate(),
+      hour: this.$date.getHours(),
+      minute: this.$date.getMinutes(),
+      second: this.$date.getSeconds(),
+    }
+  }
+
+  getDate(): Date {
+    return this.$date
+  }
+
+  clone(): LocalTime {
+    return new LocalTime(new Date(this.$date))
+  }
+
+  unix(): UnixTimestamp {
+    return Math.floor(this.$date.valueOf() / 1000)
+  }
+
+  valueOf(): UnixTimestamp {
+    return Math.floor(this.$date.valueOf() / 1000)
+  }
+
+  toISO8601(): IsoDateTime {
+    return this.$date.toISOString().slice(0, 19)
+  }
+
+  toPretty(): IsoDateTime {
+    return this.$date.toISOString().slice(0, 19).split('T').join(' ')
+  }
+
+  toString(): string {
+    return String(this.unix())
+  }
+
+  toJSON(): UnixTimestamp {
+    return this.unix()
+  }
+}
+
+/**
+ * Shortcut wrapper around `LocalDate.parse` / `LocalDate.today`
+ */
+export function localTime(d?: LocalTimeConfig): LocalTime {
+  return d ? LocalTime.of(d) : LocalTime.now()
+}
+
+// todo: range