@naturalcycles/js-lib 14.98.1 → 14.99.0

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,12 @@ export interface LocalTimeComponents {
   second: number
 }
 
+const weekStartsOn = 1 // mon, as per ISO
+const MILLISECONDS_IN_WEEK = 604800000
+// 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 +151,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 +174,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 +192,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 +263,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)
   }
 
@@ -249,6 +297,8 @@ export class LocalTime {
 
     if (unit === 'day') {
       r = secDiff / (24 * 60 * 60)
+    } else if (unit === 'week') {
+      r = secDiff / (7 * 24 * 60 * 60)
     } else if (unit === 'hour') {
       r = secDiff / (60 * 60)
     } else if (unit === 'minute') {
@@ -258,26 +308,64 @@ export class LocalTime {
       r = secDiff
     }
 
-    r = r < 0 ? -Math.floor(-r) : Math.floor(r)
+    r = Math.trunc(r)
     if (Object.is(r, -0)) return 0
     return r
   }
 
   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 +385,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 +451,6 @@ export class LocalTime {
     return t1 < t2 ? -1 : 1
   }
 
-  // todo: endOf
-
   components(): LocalTimeComponents {
     if (this.utcMode) {
       return {
@@ -458,7 +548,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 +609,10 @@ export class LocalTime {
   toJSON(): UnixTimestampNumber {
     return this.unix()
   }
+
+  format(fmt: LocalTimeFormatter): string {
+    return fmt(this)
+  }
 }
 
 /**
@@ -527,3 +621,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

@@ -102,6 +102,7 @@ import {
   AnyObjectWithId,
   Saved,
   Unsaved,
+  UnsavedId,
   BatchResult,
   InstanceId,
   IsoDate,
@@ -161,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'
 
@@ -172,10 +185,14 @@ export type {
   TimeIntervalConfig,
   TimeIntervalString,
   LocalDateConfig,
+  LocalDateFormatter,
   LocalDateUnit,
+  LocalDateUnitStrict,
   Inclusiveness,
   LocalTimeConfig,
+  LocalTimeFormatter,
   LocalTimeUnit,
+  ISODayOfWeek,
   LocalTimeComponents,
   AbortableMapper,
   AbortablePredicate,
@@ -232,6 +249,7 @@ export type {
   SavedDBEntity,
   Saved,
   Unsaved,
+  UnsavedId,
   CreatedUpdated,
   CreatedUpdatedId,
   ObjectWithId,

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(

package/src/types.ts

@@ -1,4 +1,4 @@
-import { Merge, Promisable } from './typeFest'
+import { Except, Merge, Promisable } from './typeFest'
 
 /**
  * Map from String to String (or <T>).
@@ -72,7 +72,14 @@ export type Saved<T extends Partial<ObjectWithId>> = Merge<
   SavedDBEntity<Exclude<T['id'], undefined>>
 >
 
-export type Unsaved<T extends ObjectWithId> = Merge<T, BaseDBEntity<T['id']>>
+export type Unsaved<T extends Partial<ObjectWithId>> = Merge<
+  T,
+  BaseDBEntity<Exclude<T['id'], undefined>>
+>
+
+export type UnsavedId<T extends Partial<ObjectWithId>> = Except<T, 'id'> & {
+  id: Exclude<T['id'], undefined>
+}
 
 /**
  * Convenience type shorthand.