@naturalcycles/js-lib 14.97.0 → 14.98.1

package/src/datetime/localDate.ts

@@ -1,14 +1,14 @@
 import { _assert } from '../error/assert'
-import { Sequence } from '../seq/seq'
-import { END, IsoDateString, UnixTimestampNumber } from '../types'
+import { IsoDateString, UnixTimestampNumber } from '../types'
 import { LocalTime } from './localTime'
 
 export type LocalDateUnit = 'year' | 'month' | 'day'
 export type Inclusiveness = '()' | '[]' | '[)' | '(]'
 
-const m31 = new Set<number>([1, 3, 5, 7, 8, 10, 12])
+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 | string
+export type LocalDateConfig = LocalDate | IsoDateString
 
 /* eslint-disable no-dupe-class-members */
 
@@ -61,8 +61,13 @@ export class LocalDate {
     if (!d) return null
     if (d instanceof LocalDate) return d
 
-    // todo: explore more performant options
-    const [year, month, day] = d.slice(0, 10).split('-').map(Number)
+    // const [year, month, day] = d.slice(0, 10).split('-').map(Number)
+    const matches = DATE_REGEX.exec(d.slice(0, 10))
+    if (!matches) return null
+
+    const year = Number(matches[1])
+    const month = Number(matches[2])
+    const day = Number(matches[3])
 
     if (
       !year ||
@@ -79,6 +84,11 @@ export class LocalDate {
     return new LocalDate(year, month, day)
   }
 
+  // Can use just .toString()
+  // static parseToString(d: LocalDateConfig): IsoDateString {
+  //   return typeof d === 'string' ? d : d.toString()
+  // }
+
   static isValid(iso: string | undefined | null): boolean {
     return this.parseOrNull(iso) !== null
   }
@@ -117,64 +127,30 @@ export class LocalDate {
   }
 
   static range(
-    minIncl: LocalDateConfig,
-    maxExcl: LocalDateConfig,
+    min: LocalDateConfig,
+    max: LocalDateConfig,
+    incl: Inclusiveness = '[)',
     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
-  }
+    const dates: LocalDate[] = []
+    const $min = LocalDate.of(min)
+    const $max = LocalDate.of(max).startOf(stepUnit)
 
-  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',
-  ): IsoDateString[] {
-    return LocalDate.range(minIncl, maxExcl, step, stepUnit).map(ld => ld.toString())
-  }
+    let current = $min.startOf(stepUnit)
+    if (current.isAfter($min, incl[0] === '[')) {
+      // ok
+    } else {
+      current.add(1, stepUnit, true)
+    }
 
-  static rangeIncl(
-    minIncl: LocalDateConfig,
-    maxIncl: LocalDateConfig,
-    step = 1,
-    stepUnit: LocalDateUnit = 'day',
-  ): LocalDate[] {
-    return LocalDate.range(minIncl, LocalDate.of(maxIncl).add(1, stepUnit), step, stepUnit)
-  }
+    const incl2 = incl[1] === ']'
+    while (current.isBefore($max, incl2)) {
+      dates.push(current)
+      current = current.add(step, stepUnit)
+    }
 
-  static rangeInclString(
-    minIncl: LocalDateConfig,
-    maxIncl: LocalDateConfig,
-    step = 1,
-    stepUnit: LocalDateUnit = 'day',
-  ): IsoDateString[] {
-    return LocalDate.range(minIncl, LocalDate.of(maxIncl).add(1, stepUnit), step, stepUnit).map(
-      ld => ld.toString(),
-    )
+    return dates
   }
 
   get(unit: LocalDateUnit): number {
@@ -216,16 +192,18 @@ export class LocalDate {
     return this.$day === d.$day && this.$month === d.$month && this.$year === d.$year
   }
 
-  isBefore(d: LocalDateConfig): boolean {
-    return this.cmp(d) === -1
+  isBefore(d: LocalDateConfig, inclusive = false): boolean {
+    const r = this.cmp(d)
+    return r === -1 || (r === 0 && inclusive)
   }
 
   isSameOrBefore(d: LocalDateConfig): boolean {
     return this.cmp(d) <= 0
   }
 
-  isAfter(d: LocalDateConfig): boolean {
-    return this.cmp(d) === 1
+  isAfter(d: LocalDateConfig, inclusive = false): boolean {
+    const r = this.cmp(d)
+    return r === 1 || (r === 0 && inclusive)
   }
 
   isSameOrAfter(d: LocalDateConfig): boolean {
@@ -317,26 +295,31 @@ export class LocalDate {
     }
 
     // check day overflow
-    let monLen = LocalDate.getMonthLength($year, $month)
-    while ($day > monLen) {
-      $day -= monLen
-      $month += 1
-      if ($month > 12) {
-        $year += 1
-        $month -= 12
-      }
-
-      monLen = LocalDate.getMonthLength($year, $month)
-    }
-    while ($day < 1) {
-      $day += monLen
-      $month -= 1
-      if ($month < 1) {
-        $year -= 1
-        $month += 12
+    if (unit === 'day') {
+      if ($day < 1) {
+        while ($day < 1) {
+          $month -= 1
+          if ($month < 1) {
+            $year -= 1
+            $month += 12
+          }
+
+          $day += LocalDate.getMonthLength($year, $month)
+        }
+      } else {
+        let monLen = LocalDate.getMonthLength($year, $month)
+
+        while ($day > monLen) {
+          $day -= monLen
+          $month += 1
+          if ($month > 12) {
+            $year += 1
+            $month -= 12
+          }
+
+          monLen = LocalDate.getMonthLength($year, $month)
+        }
       }
-
-      monLen = LocalDate.getMonthLength($year, $month)
     }
 
     // check month overflow
@@ -388,13 +371,11 @@ export class LocalDate {
 
   static getMonthLength(year: number, month: number): number {
     if (month === 2) return this.isLeapYear(year) ? 29 : 28
-    return m31.has(month) ? 31 : 30
+    return MDAYS[month]!
   }
 
   static isLeapYear(year: number): boolean {
-    if (year % 4 !== 0) return false
-    if (year % 100 !== 0) return true
-    return year % 400 === 0
+    return year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0)
   }
 
   clone(): LocalDate {

package/src/datetime/localTime.ts

@@ -62,7 +62,7 @@ export class LocalTime {
     } else if (typeof d === 'number') {
       date = new Date(d * 1000)
     } else {
-      date = new Date(d)
+      date = new Date(d.slice(0, 19))
     }
 
     // validation
@@ -78,6 +78,32 @@ export class LocalTime {
     return new LocalTime(date, false)
   }
 
+  static parseToDate(d: LocalTimeConfig): 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)
+
+    if (isNaN(date.getDate())) {
+      throw new TypeError(`Cannot parse "${d}" to Date`)
+    }
+
+    return date
+  }
+
+  static parseToUnixTimestamp(d: LocalTimeConfig): UnixTimestampNumber {
+    if (typeof d === 'number') return d
+    if (d instanceof LocalTime) return d.unix()
+
+    const date = d instanceof Date ? d : new Date(d)
+
+    if (isNaN(date.getDate())) {
+      throw new TypeError(`Cannot parse "${d}" to UnixTimestamp`)
+    }
+
+    return date.valueOf() / 1000
+  }
+
   static isValid(d: LocalTimeConfig | undefined | null): boolean {
     return this.parseOrNull(d) !== null
   }
@@ -205,7 +231,7 @@ export class LocalTime {
   }
 
   diff(other: LocalTimeConfig, unit: LocalTimeUnit): number {
-    const date2 = LocalTime.of(other).$date
+    const date2 = LocalTime.parseToDate(other)
 
     if (unit === 'year') {
       return this.$date.getFullYear() - date2.getFullYear()
@@ -295,16 +321,18 @@ export class LocalTime {
     return this.cmp(d) === 0
   }
 
-  isBefore(d: LocalTimeConfig): boolean {
-    return this.cmp(d) === -1
+  isBefore(d: LocalTimeConfig, inclusive = false): boolean {
+    const r = this.cmp(d)
+    return r === -1 || (r === 0 && inclusive)
   }
 
   isSameOrBefore(d: LocalTimeConfig): boolean {
     return this.cmp(d) <= 0
   }
 
-  isAfter(d: LocalTimeConfig): boolean {
-    return this.cmp(d) === 1
+  isAfter(d: LocalTimeConfig, inclusive = false): boolean {
+    const r = this.cmp(d)
+    return r === 1 || (r === 0 && inclusive)
   }
 
   isSameOrAfter(d: LocalTimeConfig): boolean {
@@ -326,7 +354,7 @@ export class LocalTime {
    */
   cmp(d: LocalTimeConfig): -1 | 0 | 1 {
     const t1 = this.$date.valueOf()
-    const t2 = LocalTime.of(d).$date.valueOf()
+    const t2 = LocalTime.parseToDate(d).valueOf()
     if (t1 === t2) return 0
     return t1 < t2 ? -1 : 1
   }
@@ -355,8 +383,8 @@ export class LocalTime {
     }
   }
 
-  fromNow(now: LocalTimeConfig = LocalTime.now()): string {
-    const msDiff = LocalTime.of(now).unixMillis() - this.unixMillis()
+  fromNow(now: LocalTimeConfig = new Date()): string {
+    const msDiff = LocalTime.parseToDate(now).valueOf() - this.$date.valueOf()
 
     if (msDiff === 0) return 'now'
 
@@ -499,5 +527,3 @@ export class LocalTime {
 export function localTime(d?: LocalTimeConfig): LocalTime {
   return d ? LocalTime.of(d) : LocalTime.now()
 }
-
-// todo: range

package/src/datetime/timeInterval.ts

@@ -0,0 +1,104 @@
+import { UnixTimestampNumber } from '../types'
+import { Inclusiveness } from './localDate'
+import { LocalTime, LocalTimeConfig } from './localTime'
+
+export type TimeIntervalConfig = TimeInterval | TimeIntervalString
+export type TimeIntervalString = string
+
+/**
+ * Class that supports an "interval of time" between 2 timestamps - start and end.
+ * Example: `1649267185/1649267187`.
+ *
+ * @experimental
+ */
+export class TimeInterval {
+  private constructor(private $start: UnixTimestampNumber, private $end: UnixTimestampNumber) {}
+
+  static of(start: LocalTimeConfig, end: LocalTimeConfig): TimeInterval {
+    return new TimeInterval(
+      LocalTime.parseToUnixTimestamp(start),
+      LocalTime.parseToUnixTimestamp(end),
+    )
+  }
+
+  get start(): UnixTimestampNumber {
+    return this.$start
+  }
+
+  get end(): UnixTimestampNumber {
+    return this.$end
+  }
+
+  get startTime(): LocalTime {
+    return LocalTime.of(this.$start)
+  }
+
+  get endTime(): LocalTime {
+    return LocalTime.of(this.$end)
+  }
+
+  /**
+   * Parses string like `1649267185/1649267187` into a TimeInterval.
+   */
+  static parse(d: TimeIntervalConfig): TimeInterval {
+    if (d instanceof TimeInterval) return d
+
+    const [start, end] = d.split('/').map(Number)
+
+    if (!end || !start) {
+      throw new Error(`Cannot parse "${d}" into TimeInterval`)
+    }
+
+    return new TimeInterval(start, end)
+  }
+
+  isSame(d: TimeIntervalConfig): boolean {
+    return this.cmp(d) === 0
+  }
+
+  isBefore(d: TimeIntervalConfig, inclusive = false): boolean {
+    const r = this.cmp(d)
+    return r === -1 || (r === 0 && inclusive)
+  }
+
+  isSameOrBefore(d: TimeIntervalConfig): boolean {
+    return this.cmp(d) <= 0
+  }
+
+  isAfter(d: TimeIntervalConfig, inclusive = false): boolean {
+    const r = this.cmp(d)
+    return r === 1 || (r === 0 && inclusive)
+  }
+
+  isSameOrAfter(d: TimeIntervalConfig): boolean {
+    return this.cmp(d) >= 0
+  }
+
+  includes(d: LocalTimeConfig, incl: Inclusiveness = '[)'): boolean {
+    d = LocalTime.parseToUnixTimestamp(d)
+    if (d < this.$start || (d === this.$start && incl[0] === '(')) return false
+    if (d > this.$end || (d === this.$end && incl[1] === ')')) return false
+    return true
+  }
+
+  /**
+   * TimeIntervals compare by start date.
+   * If it's the same - then by end date.
+   */
+  cmp(d: TimeIntervalConfig): -1 | 0 | 1 {
+    d = TimeInterval.parse(d)
+    if (this.$start > d.$start) return 1
+    if (this.$start < d.$start) return -1
+    if (this.$end > d.$end) return 1
+    if (this.$end < d.$end) return -1
+    return 0
+  }
+
+  toString(): TimeIntervalString {
+    return [this.$start, this.$end].join('/')
+  }
+
+  toJSON(): TimeIntervalString {
+    return this.toString()
+  }
+}

package/src/index.ts

@@ -160,13 +160,17 @@ export * from './string/leven'
 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 { DateIntervalConfig, DateIntervalString } from './datetime/dateInterval'
+import { TimeIntervalConfig, TimeIntervalString } from './datetime/timeInterval'
 
 export type {
   DateIntervalConfig,
   DateIntervalString,
+  TimeIntervalConfig,
+  TimeIntervalString,
   LocalDateConfig,
   LocalDateUnit,
   Inclusiveness,

package/src/json-schema/jsonSchemaBuilder.ts

@@ -365,7 +365,9 @@ export class JsonSchemaObjectBuilder<T extends AnyObject> extends JsonSchemaAnyB
     return this
   }
 
-  baseDBEntity<ID = string>(idType = 'string'): JsonSchemaObjectBuilder<T & BaseDBEntity<ID>> {
+  baseDBEntity<ID extends string | number = string>(
+    idType = 'string',
+  ): JsonSchemaObjectBuilder<T & BaseDBEntity<ID>> {
     Object.assign(this.schema.properties, {
       id: { type: idType },
       created: { type: 'number', format: 'unixTimestamp' },
@@ -375,7 +377,9 @@ export class JsonSchemaObjectBuilder<T extends AnyObject> extends JsonSchemaAnyB
     return this
   }
 
-  savedDBEntity<ID = string>(idType = 'string'): JsonSchemaObjectBuilder<T & SavedDBEntity<ID>> {
+  savedDBEntity<ID extends string | number = string>(
+    idType = 'string',
+  ): JsonSchemaObjectBuilder<T & SavedDBEntity<ID>> {
     return this.baseDBEntity(idType).addRequired(['id', 'created', 'updated']) as any
   }
 

package/src/math/math.util.ts

@@ -12,6 +12,13 @@ export function _average(values: number[]): number {
   return values.reduce((a, b) => a + b) / values.length
 }
 
+/**
+ * Same as _average, but safely returns null if input array is empty or nullish.
+ */
+export function _averageOrNull(values: number[] | undefined | null): number | null {
+  return values?.length ? values.reduce((a, b) => a + b) / values.length : null
+}
+
 /**
  * valuesArray and weightsArray length is expected to be the same.
  */

package/src/math/sma.ts

@@ -15,6 +15,10 @@ export class SimpleMovingAverage {
    */
   avg = 0
 
+  /**
+   * Push new value.
+   * Returns newly calculated average (using newly pushed value).
+   */
   push(n: number): number {
     this.data[this.nextIndex] = n
     this.nextIndex =

package/src/types.ts

@@ -6,7 +6,7 @@ import { Merge, Promisable } from './typeFest'
  * Alternative: Record<string, T | undefined>
  */
 export interface StringMap<T = string> {
-  [k: string]: T | undefined
+  [k: string | number]: T | undefined
 }
 
 /**
@@ -29,15 +29,50 @@ export interface CreatedUpdated {
   updated: number
 }
 
-export interface CreatedUpdatedId<ID = string> extends CreatedUpdated {
+export interface CreatedUpdatedId<ID extends string | number = string | number>
+  extends CreatedUpdated {
   id: ID
 }
 
-export interface ObjectWithId<ID = string> {
+export interface ObjectWithId<ID extends string | number = string | number> {
   id: ID
 }
 
-export interface AnyObjectWithId<ID = string> extends AnyObject, ObjectWithId<ID> {}
+export interface AnyObjectWithId<ID extends string | number = string | number>
+  extends AnyObject,
+    ObjectWithId<ID> {}
+
+/**
+ * Base interface for any Entity that was saved to DB.
+ */
+export interface SavedDBEntity<ID extends string | number = string> {
+  id: ID
+
+  /**
+   * unixTimestamp of when the entity was first created (in the DB).
+   */
+  created: UnixTimestampNumber
+
+  /**
+   * unixTimestamp of when the entity was last updated (in the DB).
+   */
+  updated: UnixTimestampNumber
+}
+
+/**
+ * Base interface for any Entity that can be saved to DB.
+ * This interface fits when entity was NOT YET saved to DB,
+ * hence `id`, `created` and `updated` fields CAN BE undefined (yet).
+ * When it's known to be saved - `SavedDBEntity` interface can be used instead.
+ */
+export type BaseDBEntity<ID extends string | number = string> = Partial<SavedDBEntity<ID>>
+
+export type Saved<T extends Partial<ObjectWithId>> = Merge<
+  T,
+  SavedDBEntity<Exclude<T['id'], undefined>>
+>
+
+export type Unsaved<T extends ObjectWithId> = Merge<T, BaseDBEntity<T['id']>>
 
 /**
  * Convenience type shorthand.
@@ -181,34 +216,6 @@ export type UnixTimestamp = number
  */
 export type Integer = number
 
-/**
- * Base interface for any Entity that was saved to DB.
- */
-export interface SavedDBEntity<ID = string> {
-  id: ID
-
-  /**
-   * unixTimestamp of when the entity was first created (in the DB).
-   */
-  created: UnixTimestampNumber
-
-  /**
-   * unixTimestamp of when the entity was last updated (in the DB).
-   */
-  updated: UnixTimestampNumber
-}
-
-/**
- * Base interface for any Entity that can be saved to DB.
- * This interface fits when entity was NOT YET saved to DB,
- * hence `id`, `created` and `updated` fields CAN BE undefined (yet).
- * When it's known to be saved - `SavedDBEntity` interface can be used instead.
- */
-export type BaseDBEntity<ID = string> = Partial<SavedDBEntity<ID>>
-
-export type Saved<E, ID = string> = Merge<E, SavedDBEntity<ID>>
-export type Unsaved<E, ID = string> = Merge<E, BaseDBEntity<ID>>
-
 /**
  * Named type for JSON.parse / JSON.stringify second argument
  */