@naturalcycles/js-lib 14.96.1 → 14.98.0

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

@@ -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/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,17 @@ export interface CreatedUpdated {
   updated: number
 }
 
-export interface CreatedUpdatedId<ID = string> extends CreatedUpdated {
+export interface CreatedUpdatedId<ID extends string | number = string> extends CreatedUpdated {
   id: ID
 }
 
-export interface ObjectWithId<ID = string> {
+export interface ObjectWithId<ID extends string | number = string> {
   id: ID
 }
 
-export interface AnyObjectWithId<ID = string> extends AnyObject, ObjectWithId<ID> {}
+export interface AnyObjectWithId<ID extends string | number = string>
+  extends AnyObject,
+    ObjectWithId<ID> {}
 
 /**
  * Convenience type shorthand.
@@ -150,6 +152,11 @@ export interface InstanceId {
  *
  * @example '2019-06-21'
  */
+export type IsoDateString = string
+
+/**
+ * @deprecated use IsoDateString
+ */
 export type IsoDate = string
 
 /**
@@ -157,13 +164,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
 
 /**
@@ -174,18 +186,18 @@ export type Integer = number
 /**
  * Base interface for any Entity that was saved to DB.
  */
-export interface SavedDBEntity<ID = string> {
+export interface SavedDBEntity<ID extends string | number = string> {
   id: ID
 
   /**
    * 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
 }
 
 /**
@@ -194,10 +206,10 @@ export interface SavedDBEntity<ID = string> {
  * 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 BaseDBEntity<ID extends string | number = string> = Partial<SavedDBEntity<ID>>
 
-export type Saved<E, ID = string> = Merge<E, SavedDBEntity<ID>>
-export type Unsaved<E, ID = string> = Merge<E, BaseDBEntity<ID>>
+export type Saved<E, ID extends string | number = string> = Merge<E, SavedDBEntity<ID>>
+export type Unsaved<E, ID extends string | number = string> = Merge<E, BaseDBEntity<ID>>
 
 /**
  * Named type for JSON.parse / JSON.stringify second argument