@naturalcycles/js-lib 14.96.0 → 14.97.1

package/src/datetime/localTime.ts

@@ -1,11 +1,11 @@
 import { _assert } from '../error/assert'
 import { _ms } from '../time/time.util'
-import { IsoDate, IsoDateTime, UnixTimestamp } from '../types'
+import { IsoDateString, IsoDateTimeString, UnixTimestampNumber } from '../types'
 import { Inclusiveness, LocalDate } from './localDate'
 
 export type LocalTimeUnit = 'year' | 'month' | 'day' | 'hour' | 'minute' | 'second'
 
-export type LocalTimeConfig = LocalTime | Date | IsoDateTime | UnixTimestamp
+export type LocalTimeConfig = LocalTime | Date | IsoDateTimeString | UnixTimestampNumber
 
 export interface LocalTimeComponents {
   year: number
@@ -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
   }
@@ -144,9 +170,9 @@ export class LocalTime {
   month(v?: number): number | LocalTime {
     return v === undefined ? this.get('month') : this.set('month', v)
   }
-  date(): number
-  date(v: number): LocalTime
-  date(v?: number): number | LocalTime {
+  day(): number
+  day(v: number): LocalTime
+  day(v?: number): number | LocalTime {
     return v === undefined ? this.get('day') : this.set('day', v)
   }
   hour(): number
@@ -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'
 
@@ -375,7 +403,7 @@ export class LocalTime {
     return new LocalTime(new Date(this.$date), this.utcMode)
   }
 
-  unix(): UnixTimestamp {
+  unix(): UnixTimestampNumber {
     return Math.floor(this.$date.valueOf() / 1000)
   }
 
@@ -383,7 +411,7 @@ export class LocalTime {
     return this.$date.valueOf()
   }
 
-  valueOf(): UnixTimestamp {
+  valueOf(): UnixTimestampNumber {
     return Math.floor(this.$date.valueOf() / 1000)
   }
 
@@ -403,7 +431,7 @@ export class LocalTime {
     )
   }
 
-  toPretty(seconds = true): IsoDateTime {
+  toPretty(seconds = true): IsoDateTimeString {
     const { year, month, day, hour, minute, second } = this.components()
 
     return (
@@ -432,14 +460,14 @@ export class LocalTime {
   /**
    * Returns e.g: `1984-06-21T17:56:21`, only the date part of DateTime
    */
-  toISODateTime(): IsoDateTime {
+  toISODateTime(): IsoDateTimeString {
     return this.$date.toISOString().slice(0, 19)
   }
 
   /**
    * Returns e.g: `1984-06-21`, only the date part of DateTime
    */
-  toISODate(): IsoDate {
+  toISODate(): IsoDateString {
     const { year, month, day } = this.components()
 
     return [
@@ -488,7 +516,7 @@ export class LocalTime {
     return String(this.unix())
   }
 
-  toJSON(): UnixTimestamp {
+  toJSON(): UnixTimestampNumber {
     return this.unix()
   }
 }
@@ -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/error/try.ts

@@ -11,13 +11,19 @@ import { AppError } from './app.error'
  * For convenience, second argument type is non-optional,
  * so you can use it without `!`. But you SHOULD always check `if (err)` first!
  *
+ * ERR is typed as Error, not `unknown`. While unknown would be more correct,
+ * according to recent TypeScript, Error gives more developer convenience.
+ * In our code we NEVER throw non-errors.
+ * Only possibility of non-error is in the 3rd-party library code, in these cases it
+ * can be manually cast to `unknown` for extra safety.
+ *
  * @example
  *
  * const [err, v] = _try(() => someFunction())
  * if (err) ...do something...
  * v // go ahead and use v
  */
-export function _try<ERR = unknown, RETURN = void>(
+export function _try<ERR = Error, RETURN = void>(
   fn: () => RETURN,
 ): [err: ERR | null, value: RETURN] {
   try {
@@ -33,7 +39,7 @@ export function _try<ERR = unknown, RETURN = void>(
  * Also, intentionally types second return item as non-optional,
  * but you should check for `err` presense first!
  */
-export async function pTry<ERR = unknown, RETURN = void>(
+export async function pTry<ERR = Error, RETURN = void>(
   promise: Promise<RETURN>,
 ): Promise<[err: ERR | null, value: Awaited<RETURN>]> {
   try {
@@ -50,7 +56,7 @@ export async function pTry<ERR = unknown, RETURN = void>(
  */
 export class UnexpectedPassError extends AppError {
   constructor() {
-    super('_expectedError passed unexpectedly')
+    super('expected error was not thrown')
   }
 }
 

package/src/error/tryCatch.ts

@@ -1,4 +1,4 @@
-import { _since, _stringifyAny, CommonLogger } from '../index'
+import { _anyToError, _since, _stringifyAny, CommonLogger } from '../index'
 import { AnyFunction } from '../types'
 
 export interface TryCatchOptions {
@@ -6,7 +6,7 @@ export interface TryCatchOptions {
    * The value returned from the function will be returned from the wrapped method (!).
    * onError function may be asynchronous.
    */
-  onError?: (err: unknown) => any
+  onError?: (err: Error) => any
 
   /**
    * @default false
@@ -59,7 +59,7 @@ export function _tryCatch<T extends AnyFunction>(fn: T, opt: TryCatchOptions = {
 
       if (onError) {
         try {
-          return await onError(err) // eslint-disable-line @typescript-eslint/return-await
+          return await onError(_anyToError(err)) // eslint-disable-line @typescript-eslint/return-await
         } catch {}
       }
       // returns undefined, but doesn't rethrow

package/src/index.ts

@@ -105,7 +105,8 @@ import {
   BatchResult,
   InstanceId,
   IsoDate,
-  IsoDateTime,
+  IsoDateString,
+  IsoDateTimeString,
   KeyValueTuple,
   Mapper,
   ObjectMapper,
@@ -117,6 +118,7 @@ import {
   Reviver,
   SavedDBEntity,
   StringMap,
+  UnixTimestampNumber,
   UnixTimestamp,
   Integer,
   ValueOf,
@@ -158,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,
@@ -197,7 +203,8 @@ export type {
   ObjectPredicate,
   InstanceId,
   IsoDate,
-  IsoDateTime,
+  IsoDateString,
+  IsoDateTimeString,
   Reviver,
   PMapOptions,
   Mapper,
@@ -218,6 +225,7 @@ export type {
   ConditionalPick,
   ConditionalExcept,
   Class,
+  UnixTimestampNumber,
   UnixTimestamp,
   Integer,
   BaseDBEntity,

package/src/types.ts

@@ -150,6 +150,11 @@ export interface InstanceId {
  *
  * @example '2019-06-21'
  */
+export type IsoDateString = string
+
+/**
+ * @deprecated use IsoDateString
+ */
 export type IsoDate = string
 
 /**
@@ -157,13 +162,18 @@ export type IsoDate = string
  *
  * @example '2019-06-21T05:21:73Z'
  */
-export type IsoDateTime = string
+export type IsoDateTimeString = string
 
 /**
  * Interface explicitly states that the value is a Unix timestamp (in seconds).
  *
  * @example 1628945450
  */
+export type UnixTimestampNumber = number
+
+/**
+ * @deprecated use UnixTimestampNumber
+ */
 export type UnixTimestamp = number
 
 /**
@@ -180,12 +190,12 @@ export interface SavedDBEntity<ID = string> {
   /**
    * unixTimestamp of when the entity was first created (in the DB).
    */
-  created: UnixTimestamp
+  created: UnixTimestampNumber
 
   /**
    * unixTimestamp of when the entity was last updated (in the DB).
    */
-  updated: UnixTimestamp
+  updated: UnixTimestampNumber
 }
 
 /**