@naturalcycles/js-lib 14.91.2 → 14.94.0

package/dist-esm/datetime/dateInterval.js

@@ -0,0 +1,76 @@
+import { LocalDate } from './localDate';
+/**
+ * Class that supports ISO8601 "Time interval" standard that looks like `2022-02-24/2022-03-30`.
+ *
+ * @experimental
+ */
+export class DateInterval {
+    constructor(start, end) {
+        this.start = start;
+        this.end = end;
+    }
+    static of(start, end) {
+        return new DateInterval(LocalDate.of(start), LocalDate.of(end));
+    }
+    /**
+     * Parses string like `2022-02-24/2023-03-30` into a DateInterval.
+     */
+    static parse(d) {
+        if (d instanceof DateInterval)
+            return d;
+        const [start, end] = d.split('/');
+        if (!end || !start) {
+            throw new Error(`Cannot parse "${d}" into DateInterval`);
+        }
+        return new DateInterval(LocalDate.of(start), LocalDate.of(end));
+    }
+    isSame(d) {
+        return this.cmp(d) === 0;
+    }
+    isBefore(d) {
+        return this.cmp(d) === -1;
+    }
+    isSameOrBefore(d) {
+        return this.cmp(d) <= 0;
+    }
+    isAfter(d) {
+        return this.cmp(d) === 1;
+    }
+    isSameOrAfter(d) {
+        return this.cmp(d) >= 0;
+    }
+    /**
+     * Ranges of DateInterval (start, end) are INCLUSIVE.
+     */
+    includes(d) {
+        d = LocalDate.of(d);
+        return d.isSameOrAfter(this.start) && d.isSameOrBefore(this.end);
+    }
+    /**
+     * DateIntervals compare by start date.
+     * If it's the same - then by end date.
+     */
+    cmp(d) {
+        d = DateInterval.parse(d);
+        return this.start.cmp(d.start) || this.end.cmp(d.end);
+    }
+    /**
+     * Returns an array of LocalDates that are included in the interval.
+     * Ranges are INCLUSIVE.
+     */
+    getDays() {
+        const days = [];
+        let current = this.start;
+        do {
+            days.push(current);
+            current = current.add(1, 'day');
+        } while (current.isSameOrBefore(this.end));
+        return days;
+    }
+    toString() {
+        return [this.start, this.end].join('/');
+    }
+    toJSON() {
+        return this.toString();
+    }
+}

package/dist-esm/datetime/localDate.js

@@ -36,6 +36,9 @@ export class LocalDate {
     static fromDate(d) {
         return new LocalDate(d.getFullYear(), d.getMonth() + 1, d.getDate());
     }
+    static fromDateUTC(d) {
+        return new LocalDate(d.getUTCFullYear(), d.getUTCMonth() + 1, d.getUTCDate());
+    }
     /**
      * Returns null if invalid.
      */
@@ -61,6 +64,9 @@ export class LocalDate {
     static today() {
         return this.fromDate(new Date());
     }
+    static todayUTC() {
+        return this.fromDateUTC(new Date());
+    }
     static sort(items, mutate = false, descending = false) {
         const mod = descending ? -1 : 1;
         return (mutate ? items : [...items]).sort((a, b) => a.cmp(b) * mod);
@@ -122,6 +128,15 @@ export class LocalDate {
     isSameOrAfter(d) {
         return this.cmp(d) >= 0;
     }
+    isBetween(min, max, incl = '[)') {
+        let r = this.cmp(min);
+        if (r < 0 || (r === 0 && incl[0] === '('))
+            return false;
+        r = this.cmp(max);
+        if (r > 0 || (r === 0 && incl[1] === ')'))
+            return false;
+        return true;
+    }
     /**
      * Returns 1 if this > d
      * returns 0 if they are equal

package/dist-esm/datetime/localTime.js

@@ -1,4 +1,5 @@
 import { _assert } from '../error/assert';
+import { _ms } from '../time/time.util';
 import { LocalDate } from './localDate';
 /* eslint-disable no-dupe-class-members */
 // Design choices:
@@ -10,12 +11,16 @@ import { LocalDate } from './localDate';
 // .valueOf returns unix timestamp (no millis)
 // Prevents dayjs(undefined) being dayjs.now()
 // Validates on parse, throws if invalid. Doesn't allow invalid objects
+// No arbitrary .format('') (which is slow to parse) vs well-defined (opinionated) formats
+// Separate LocalTime, powered by native js Date, and LocalDate - a smaller functionality class when
+// you only need "whole dates", no time, no timezone worry
 /**
  * @experimental
  */
 export class LocalTime {
-    constructor($date) {
+    constructor($date, utcMode) {
         this.$date = $date;
+        this.utcMode = utcMode;
     }
     /**
      * Parses input String into LocalDate.
@@ -28,6 +33,14 @@ export class LocalTime {
         }
         return t;
     }
+    utc() {
+        this.utcMode = true;
+        return this;
+    }
+    local() {
+        this.utcMode = false;
+        return this;
+    }
     /**
      * Returns null if invalid
      */
@@ -49,106 +62,110 @@ export class LocalTime {
             // throw new TypeError(`Cannot parse "${d}" into LocalTime`)
             return null;
         }
-        return new LocalTime(date);
+        // if (utc) {
+        //   date.setMinutes(date.getMinutes() + date.getTimezoneOffset())
+        // }
+        return new LocalTime(date, false);
     }
     static isValid(d) {
         return this.parseOrNull(d) !== null;
     }
-    static unix(ts) {
-        return new LocalTime(new Date(ts * 1000));
-    }
     static now() {
-        return this.of(new Date());
+        return new LocalTime(new Date(), false);
     }
     static fromComponents(c) {
-        return new LocalTime(new Date(c.year, c.month - 1, c.day, c.hour, c.minute, c.second));
+        return new LocalTime(new Date(c.year, c.month - 1, c.day, c.hour, c.minute, c.second), false);
     }
     get(unit) {
         if (unit === 'year') {
-            return this.$date.getFullYear();
+            return this.utcMode ? this.$date.getUTCFullYear() : this.$date.getFullYear();
         }
         if (unit === 'month') {
-            return this.$date.getMonth() + 1;
+            return (this.utcMode ? this.$date.getUTCMonth() : this.$date.getMonth()) + 1;
         }
         if (unit === 'day') {
-            return this.$date.getDate();
+            return this.utcMode ? this.$date.getUTCDate() : this.$date.getDate();
         }
         if (unit === 'hour') {
-            return this.$date.getHours();
+            return this.utcMode ? this.$date.getUTCHours() : this.$date.getHours();
         }
         if (unit === 'minute') {
-            return this.$date.getMinutes();
+            return this.utcMode ? this.$date.getUTCMinutes() : this.$date.getMinutes();
         }
         // second
-        return this.$date.getSeconds();
+        return this.utcMode ? this.$date.getUTCSeconds() : this.$date.getSeconds();
     }
     set(unit, v, mutate = false) {
         const t = mutate ? this : this.clone();
+        /* eslint-disable @typescript-eslint/no-unused-expressions */
         if (unit === 'year') {
-            t.$date.setFullYear(v);
+            this.utcMode ? t.$date.setUTCFullYear(v) : t.$date.setFullYear(v);
         }
         else if (unit === 'month') {
-            t.$date.setMonth(v - 1);
+            this.utcMode ? t.$date.setUTCMonth(v - 1) : t.$date.setMonth(v - 1);
         }
         else if (unit === 'day') {
-            t.$date.setDate(v);
+            this.utcMode ? t.$date.setUTCDate(v) : t.$date.setDate(v);
         }
         else if (unit === 'hour') {
-            t.$date.setHours(v);
+            this.utcMode ? t.$date.setUTCHours(v) : t.$date.setHours(v);
         }
         else if (unit === 'minute') {
-            t.$date.setMinutes(v);
+            this.utcMode ? t.$date.setUTCMinutes(v) : t.$date.setMinutes(v);
         }
         else if (unit === 'second') {
-            t.$date.setSeconds(v);
+            this.utcMode ? t.$date.setUTCSeconds(v) : t.$date.setSeconds(v);
         }
+        /* eslint-enable @typescript-eslint/no-unused-expressions */
         return t;
     }
     year(v) {
-        return v === undefined ? this.$date.getFullYear() : this.set('year', v);
+        return v === undefined ? this.get('year') : this.set('year', v);
     }
     month(v) {
-        return v === undefined ? this.$date.getMonth() + 1 : this.set('month', v);
+        return v === undefined ? this.get('month') : this.set('month', v);
     }
     date(v) {
-        return v === undefined ? this.$date.getDate() : this.set('day', v);
+        return v === undefined ? this.get('day') : this.set('day', v);
     }
     hour(v) {
-        return v === undefined ? this.$date.getHours() : this.set('hour', v);
+        return v === undefined ? this.get('hour') : this.set('hour', v);
     }
     minute(v) {
-        return v === undefined ? this.$date.getMinutes() : this.set('minute', v);
+        return v === undefined ? this.get('minute') : this.set('minute', v);
     }
     second(v) {
-        return v === undefined ? this.$date.getSeconds() : this.set('second', v);
+        return v === undefined ? this.get('second') : this.set('second', v);
     }
     setComponents(c, mutate = false) {
         const d = mutate ? this.$date : new Date(this.$date);
+        /* eslint-disable @typescript-eslint/no-unused-expressions */
         if (c.year) {
-            d.setFullYear(c.year);
+            this.utcMode ? d.setUTCFullYear(c.year) : d.setFullYear(c.year);
         }
         if (c.month) {
-            d.setMonth(c.month - 1);
+            this.utcMode ? d.setUTCMonth(c.month - 1) : d.setMonth(c.month - 1);
         }
         if (c.day) {
-            d.setDate(c.day);
+            this.utcMode ? d.setUTCDate(c.day) : d.setDate(c.day);
         }
         if (c.hour !== undefined) {
-            d.setHours(c.hour);
+            this.utcMode ? d.setUTCHours(c.hour) : d.setHours(c.hour);
         }
         if (c.minute !== undefined) {
-            d.setMinutes(c.minute);
+            this.utcMode ? d.setUTCMinutes(c.minute) : d.setMinutes(c.minute);
         }
         if (c.second !== undefined) {
-            d.setSeconds(c.second);
+            this.utcMode ? d.setUTCSeconds(c.second) : d.setSeconds(c.second);
         }
-        return mutate ? this : new LocalTime(d);
+        /* eslint-enable @typescript-eslint/no-unused-expressions */
+        return mutate ? this : new LocalTime(d, this.utcMode);
     }
     add(num, unit, mutate = false) {
         return this.set(unit, this.get(unit) + num, mutate);
     }
     subtract(num, unit, mutate = false) {
-        return this.add(-num, unit, mutate);
+        return this.add(num * -1, unit, mutate);
     }
     absDiff(other, unit) {
         return Math.abs(this.diff(other, unit));
@@ -186,40 +203,23 @@ export class LocalTime {
     startOf(unit, mutate = false) {
         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);
+        const d = mutate ? this.$date : new Date(this.$date);
+        /* 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') {
+                        this.utcMode ? d.setUTCMonth(0) : d.setMonth(0);
+                    }
+                }
+            }
+        }
+        /* eslint-enable @typescript-eslint/no-unused-expressions */
+        return mutate ? this : new LocalTime(d, this.utcMode);
     }
     static sort(items, mutate = false, descending = false) {
         const mod = descending ? -1 : 1;
@@ -260,6 +260,15 @@ export class LocalTime {
     isSameOrAfter(d) {
         return this.cmp(d) >= 0;
     }
+    isBetween(min, max, incl = '[)') {
+        let r = this.cmp(min);
+        if (r < 0 || (r === 0 && incl[0] === '('))
+            return false;
+        r = this.cmp(max);
+        if (r > 0 || (r === 0 && incl[1] === ')'))
+            return false;
+        return true;
+    }
     /**
      * Returns 1 if this > d
      * returns 0 if they are equal
@@ -274,6 +283,16 @@ export class LocalTime {
     }
     // todo: endOf
     components() {
+        if (this.utcMode) {
+            return {
+                year: this.$date.getUTCFullYear(),
+                month: this.$date.getUTCMonth() + 1,
+                day: this.$date.getUTCDate(),
+                hour: this.$date.getUTCHours(),
+                minute: this.$date.getUTCMinutes(),
+                second: this.$date.getSeconds(),
+            };
+        }
         return {
             year: this.$date.getFullYear(),
             month: this.$date.getMonth() + 1,
@@ -283,11 +302,20 @@ export class LocalTime {
             second: this.$date.getSeconds(),
         };
     }
+    fromNow(now = LocalTime.now()) {
+        const msDiff = LocalTime.of(now).unixMillis() - this.unixMillis();
+        if (msDiff === 0)
+            return 'now';
+        if (msDiff >= 0) {
+            return `${_ms(msDiff)} ago`;
+        }
+        return `in ${_ms(msDiff * -1)}`;
+    }
     getDate() {
         return this.$date;
     }
     clone() {
-        return new LocalTime(new Date(this.$date));
+        return new LocalTime(new Date(this.$date), this.utcMode);
     }
     unix() {
         return Math.floor(this.$date.valueOf() / 1000);
@@ -299,14 +327,31 @@ export class LocalTime {
         return Math.floor(this.$date.valueOf() / 1000);
     }
     toLocalDate() {
+        if (this.utcMode) {
+            return LocalDate.create(this.$date.getUTCFullYear(), this.$date.getUTCMonth() + 1, this.$date.getUTCDate());
+        }
         return LocalDate.create(this.$date.getFullYear(), this.$date.getMonth() + 1, this.$date.getDate());
     }
     toPretty(seconds = true) {
-        return this.$date
-            .toISOString()
-            .slice(0, seconds ? 19 : 16)
-            .split('T')
-            .join(' ');
+        const { year, month, day, hour, minute, second } = this.components();
+        return ([
+            String(year).padStart(4, '0'),
+            String(month).padStart(2, '0'),
+            String(day).padStart(2, '0'),
+        ].join('-') +
+            ' ' +
+            [
+                String(hour).padStart(2, '0'),
+                String(minute).padStart(2, '0'),
+                seconds && String(second).padStart(2, '0'),
+            ]
+                .filter(Boolean)
+                .join(':'));
+        // return this.$date
+        //   .toISOString()
+        //   .slice(0, seconds ? 19 : 16)
+        //   .split('T')
+        //   .join(' ')
     }
     /**
      * Returns e.g: `1984-06-21T17:56:21`, only the date part of DateTime
@@ -318,20 +363,41 @@ export class LocalTime {
      * Returns e.g: `1984-06-21`, only the date part of DateTime
      */
     toISODate() {
-        return this.$date.toISOString().slice(0, 10);
+        const { year, month, day } = this.components();
+        return [
+            String(year).padStart(4, '0'),
+            String(month).padStart(2, '0'),
+            String(day).padStart(2, '0'),
+        ].join('-');
+        // return this.$date.toISOString().slice(0, 10)
+    }
+    /**
+     * Returns e.g: `17:03:15` (or `17:03` with seconds=false)
+     */
+    toISOTime(seconds = true) {
+        // return this.$date.toISOString().slice(11, seconds ? 19 : 16)
+        const { hour, minute, second } = this.components();
+        return [
+            String(hour).padStart(2, '0'),
+            String(minute).padStart(2, '0'),
+            seconds && String(second).padStart(2, '0'),
+        ]
+            .filter(Boolean)
+            .join(':');
     }
     /**
      * Returns e.g: `19840621_1705`
      */
     toStringCompact(seconds = false) {
+        const { year, month, day, hour, minute, second } = this.components();
         return [
-            String(this.$date.getFullYear()).padStart(4, '0'),
-            String(this.$date.getMonth() + 1).padStart(2, '0'),
-            String(this.$date.getDate()).padStart(2, '0'),
+            String(year).padStart(4, '0'),
+            String(month).padStart(2, '0'),
+            String(day).padStart(2, '0'),
             '_',
-            String(this.$date.getHours()).padStart(2, '0'),
-            String(this.$date.getMinutes()).padStart(2, '0'),
-            seconds ? String(this.$date.getSeconds()).padStart(2, '0') : '',
+            String(hour).padStart(2, '0'),
+            String(minute).padStart(2, '0'),
+            seconds ? String(second).padStart(2, '0') : '',
         ].join('');
     }
     toString() {

package/dist-esm/index.js

@@ -59,4 +59,5 @@ export * from './math/stack.util';
 export * from './string/leven';
 export * from './datetime/localDate';
 export * from './datetime/localTime';
+export * from './datetime/dateInterval';
 export { is, _createPromiseDecorator, _stringMapValues, _stringMapEntries, _objectKeys, pMap, _passthroughMapper, _passUndefinedMapper, _passthroughPredicate, _passNothingPredicate, _noop, ErrorMode, pDefer, AggregatedError, pRetry, pRetryFn, pTimeout, pTimeoutFn, _tryCatch, _TryCatch, _stringifyAny, jsonSchema, JsonSchemaAnyBuilder, commonLoggerMinLevel, commonLoggerNoop, commonLogLevelNumber, commonLoggerPipe, commonLoggerPrefix, commonLoggerCreate, PQueue, END, SKIP, };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturalcycles/js-lib",
-  "version": "14.91.2",
+  "version": "14.94.0",
   "scripts": {
     "prepare": "husky install",
     "build-prod": "build-prod-esm-cjs",

package/src/datetime/dateInterval.ts

@@ -0,0 +1,91 @@
+import { LocalDate, LocalDateConfig } from './localDate'
+
+export type DateIntervalConfig = DateInterval | string
+
+/**
+ * Class that supports ISO8601 "Time interval" standard that looks like `2022-02-24/2022-03-30`.
+ *
+ * @experimental
+ */
+export class DateInterval {
+  private constructor(public start: LocalDate, public end: LocalDate) {}
+
+  static of(start: LocalDateConfig, end: LocalDateConfig): DateInterval {
+    return new DateInterval(LocalDate.of(start), LocalDate.of(end))
+  }
+
+  /**
+   * Parses string like `2022-02-24/2023-03-30` into a DateInterval.
+   */
+  static parse(d: DateIntervalConfig): DateInterval {
+    if (d instanceof DateInterval) return d
+
+    const [start, end] = d.split('/')
+
+    if (!end || !start) {
+      throw new Error(`Cannot parse "${d}" into DateInterval`)
+    }
+
+    return new DateInterval(LocalDate.of(start), LocalDate.of(end))
+  }
+
+  isSame(d: DateIntervalConfig): boolean {
+    return this.cmp(d) === 0
+  }
+
+  isBefore(d: DateIntervalConfig): boolean {
+    return this.cmp(d) === -1
+  }
+
+  isSameOrBefore(d: DateIntervalConfig): boolean {
+    return this.cmp(d) <= 0
+  }
+
+  isAfter(d: DateIntervalConfig): boolean {
+    return this.cmp(d) === 1
+  }
+
+  isSameOrAfter(d: DateIntervalConfig): boolean {
+    return this.cmp(d) >= 0
+  }
+
+  /**
+   * Ranges of DateInterval (start, end) are INCLUSIVE.
+   */
+  includes(d: LocalDateConfig): boolean {
+    d = LocalDate.of(d)
+    return d.isSameOrAfter(this.start) && d.isSameOrBefore(this.end)
+  }
+
+  /**
+   * DateIntervals compare by start date.
+   * If it's the same - then by end date.
+   */
+  cmp(d: DateIntervalConfig): -1 | 0 | 1 {
+    d = DateInterval.parse(d)
+    return this.start.cmp(d.start) || this.end.cmp(d.end)
+  }
+
+  /**
+   * Returns an array of LocalDates that are included in the interval.
+   * Ranges are INCLUSIVE.
+   */
+  getDays(): LocalDate[] {
+    const days: LocalDate[] = []
+    let current = this.start
+    do {
+      days.push(current)
+      current = current.add(1, 'day')
+    } while (current.isSameOrBefore(this.end))
+
+    return days
+  }
+
+  toString(): string {
+    return [this.start, this.end].join('/')
+  }
+
+  toJSON(): string {
+    return this.toString()
+  }
+}

package/src/datetime/localDate.ts

@@ -4,6 +4,7 @@ import { END, IsoDate, UnixTimestamp } 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])
 
@@ -47,6 +48,10 @@ export class LocalDate {
     return new LocalDate(d.getFullYear(), d.getMonth() + 1, d.getDate())
   }
 
+  static fromDateUTC(d: Date): LocalDate {
+    return new LocalDate(d.getUTCFullYear(), d.getUTCMonth() + 1, d.getUTCDate())
+  }
+
   /**
    * Returns null if invalid.
    */
@@ -79,6 +84,10 @@ export class LocalDate {
     return this.fromDate(new Date())
   }
 
+  static todayUTC(): LocalDate {
+    return this.fromDateUTC(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)
@@ -186,6 +195,14 @@ export class LocalDate {
     return this.cmp(d) >= 0
   }
 
+  isBetween(min: LocalDateConfig, max: LocalDateConfig, incl: Inclusiveness = '[)'): boolean {
+    let r = this.cmp(min)
+    if (r < 0 || (r === 0 && incl[0] === '(')) return false
+    r = this.cmp(max)
+    if (r > 0 || (r === 0 && incl[1] === ')')) return false
+    return true
+  }
+
   /**
    * Returns 1 if this > d
    * returns 0 if they are equal