@naturalcycles/js-lib 14.243.0 → 14.244.0

package/dist-esm/datetime/localTime.js

@@ -19,6 +19,10 @@ const SECONDS_IN_DAY = 86400;
 // const MILLISECONDS_IN_DAY = 86400000
 // const MILLISECONDS_IN_MINUTE = 60000
 const VALID_DAYS_OF_WEEK = new Set([1, 2, 3, 4, 5, 6, 7]);
+// It supports 2 forms:
+// 1. 2023-03-03
+// 2. 2023-03-03T05:10:02
+const DATE_TIME_REGEX = /^(\d{4})-(\d{2})-(\d{2})([T\s](\d{2}):(\d{2}):(\d{2}))?/;
 export class LocalTime {
     constructor($date) {
         this.$date = $date;
@@ -27,14 +31,14 @@ export class LocalTime {
      * Returns [cloned] LocalTime that is based on the same unixtimestamp, but in UTC timezone.
      * Opposite of `.local()` method.
      */
-    utc() {
+    toUTC() {
         return new LocalTime(new Date(this.$date.toISOString()));
     }
     /**
      * Returns [cloned] LocalTime that is based on the same unixtimestamp, but in local timezone.
      * Opposite of `.utc()` method.
      */
-    local() {
+    toLocal() {
         return new LocalTime(new Date(this.$date.getTime()));
     }
     /**
@@ -156,34 +160,58 @@ export class LocalTime {
         }
         return t;
     }
-    year(v) {
-        return v === undefined ? this.get('year') : this.set('year', v);
+    get year() {
+        return this.$date.getFullYear();
     }
-    month(v) {
-        return v === undefined ? this.get('month') : this.set('month', v);
+    setYear(v) {
+        return this.set('year', v);
     }
-    week(v) {
-        return v === undefined ? getWeek(this.$date) : this.set('week', v);
+    get month() {
+        return this.$date.getMonth() + 1;
     }
-    day(v) {
-        return v === undefined ? this.get('day') : this.set('day', v);
+    setMonth(v) {
+        return this.set('month', v);
     }
-    dayOfWeek(v) {
-        const dow = (this.$date.getDay() || 7);
-        if (v === undefined) {
-            return dow;
-        }
-        _assert(VALID_DAYS_OF_WEEK.has(v), `Invalid dayOfWeek: ${v}`);
-        return this.plus(v - dow, 'day');
+    get week() {
+        return getWeek(this.$date);
+    }
+    setWeek(v) {
+        return this.set('week', v);
+    }
+    get day() {
+        return this.$date.getDate();
     }
-    hour(v) {
-        return v === undefined ? this.get('hour') : this.set('hour', v);
+    setDay(v) {
+        return this.set('day', v);
     }
-    minute(v) {
-        return v === undefined ? this.get('minute') : this.set('minute', v);
+    get hour() {
+        return this.$date.getHours();
+    }
+    setHour(v) {
+        return this.set('hour', v);
+    }
+    get minute() {
+        return this.$date.getMinutes();
+    }
+    setMinute(v) {
+        return this.set('minute', v);
+    }
+    get second() {
+        return this.$date.getSeconds();
     }
-    second(v) {
-        return v === undefined ? this.get('second') : this.set('second', v);
+    setSecond(v) {
+        return this.set('second', v);
+    }
+    /**
+     * Based on ISO: 1-7 is Mon-Sun.
+     */
+    get dayOfWeek() {
+        return (this.$date.getDay() || 7);
+    }
+    setDayOfWeek(v) {
+        _assert(VALID_DAYS_OF_WEEK.has(v), `Invalid dayOfWeek: ${v}`);
+        const dow = this.$date.getDay() || 7;
+        return this.plus(v - dow, 'day');
     }
     setComponents(c, mutate = false) {
         const d = mutate ? this.$date : new Date(this.$date);
@@ -251,7 +279,7 @@ export class LocalTime {
         }
         if (unit === 'year' || unit === 'month') {
             const d = addMonths(this.$date, unit === 'month' ? num : num * 12, mutate);
-            return mutate ? this : localTime.of(d);
+            return mutate ? this : localTime.from(d);
         }
         return this.set(unit, this.get(unit) + num, mutate);
     }
@@ -262,7 +290,7 @@ export class LocalTime {
         return Math.abs(this.diff(other, unit));
     }
     diff(other, unit) {
-        const date2 = localTime.parseToDate(other);
+        const date2 = localTime.from(other).$date;
         const secDiff = (this.$date.valueOf() - date2.valueOf()) / 1000;
         if (!secDiff)
             return 0;
@@ -350,32 +378,32 @@ export class LocalTime {
      * Returns how many days are in the current month.
      * E.g 31 for January.
      */
-    daysInMonth() {
+    get daysInMonth() {
         return localDate.getMonthLength(this.$date.getFullYear(), this.$date.getMonth() + 1);
     }
     isSame(d) {
-        return this.cmp(d) === 0;
+        return this.compare(d) === 0;
     }
     isBefore(d, inclusive = false) {
-        const r = this.cmp(d);
+        const r = this.compare(d);
         return r === -1 || (r === 0 && inclusive);
     }
     isSameOrBefore(d) {
-        return this.cmp(d) <= 0;
+        return this.compare(d) <= 0;
     }
     isAfter(d, inclusive = false) {
-        const r = this.cmp(d);
+        const r = this.compare(d);
         return r === 1 || (r === 0 && inclusive);
     }
     isSameOrAfter(d) {
-        return this.cmp(d) >= 0;
+        return this.compare(d) >= 0;
     }
     isBetween(min, max, incl = '[)') {
-        let r = this.cmp(min);
+        let r = this.compare(min);
         // eslint-disable-next-line @typescript-eslint/prefer-string-starts-ends-with
         if (r < 0 || (r === 0 && incl[0] === '('))
             return false;
-        r = this.cmp(max);
+        r = this.compare(max);
         if (r > 0 || (r === 0 && incl[1] === ')'))
             return false;
         return true;
@@ -390,13 +418,13 @@ export class LocalTime {
      * Third argument allows to override "now".
      */
     isOlderThan(n, unit, now) {
-        return this.isBefore(localTime.of(now ?? new Date()).plus(-n, unit));
+        return this.isBefore(localTime.from(now ?? new Date()).plus(-n, unit));
     }
     /**
      * Checks if this localTime is same or older (<=) than "now" by X units.
      */
     isSameOrOlderThan(n, unit, now) {
-        return this.isSameOrBefore(localTime.of(now ?? new Date()).plus(-n, unit));
+        return this.isSameOrBefore(localTime.from(now ?? new Date()).plus(-n, unit));
     }
     /**
      * Checks if this localTime is younger (>) than "now" by X units.
@@ -408,13 +436,13 @@ export class LocalTime {
      * Third argument allows to override "now".
      */
     isYoungerThan(n, unit, now) {
-        return this.isAfter(localTime.of(now ?? new Date()).plus(-n, unit));
+        return this.isAfter(localTime.from(now ?? new Date()).plus(-n, unit));
     }
     /**
      * Checks if this localTime is same or younger (>=) than "now" by X units.
      */
     isSameOrYoungerThan(n, unit, now) {
-        return this.isSameOrAfter(localTime.of(now ?? new Date()).plus(-n, unit));
+        return this.isSameOrAfter(localTime.from(now ?? new Date()).plus(-n, unit));
     }
     getAgeInYears(now) {
         return this.getAgeIn('year', now);
@@ -435,42 +463,42 @@ export class LocalTime {
         return this.getAgeIn('second', now);
     }
     getAgeIn(unit, now) {
-        return localTime.of(now ?? new Date()).diff(this, unit);
+        return localTime.from(now ?? new Date()).diff(this, unit);
     }
     /**
      * Returns 1 if this > d
      * returns 0 if they are equal
      * returns -1 if this < d
      */
-    cmp(d) {
+    compare(d) {
         const t1 = this.$date.valueOf();
-        const t2 = localTime.parseToDate(d).valueOf();
+        const t2 = localTime.from(d).$date.valueOf();
         if (t1 === t2)
             return 0;
         return t1 < t2 ? -1 : 1;
     }
-    getDateTimeObject() {
+    toDateTimeObject() {
         return {
-            ...this.getDateObject(),
-            ...this.getTimeObject(),
+            ...this.toDateObject(),
+            ...this.toTimeObject(),
         };
     }
-    getDateObject() {
+    toDateObject() {
         return {
             year: this.$date.getFullYear(),
             month: this.$date.getMonth() + 1,
             day: this.$date.getDate(),
         };
     }
-    getTimeObject() {
+    toTimeObject() {
         return {
             hour: this.$date.getHours(),
             minute: this.$date.getMinutes(),
             second: this.$date.getSeconds(),
         };
     }
-    fromNow(now = new Date()) {
-        const msDiff = localTime.parseToDate(now).valueOf() - this.$date.valueOf();
+    toFromNowString(now = new Date()) {
+        const msDiff = localTime.from(now).$date.valueOf() - this.$date.valueOf();
         if (msDiff === 0)
             return 'now';
         if (msDiff >= 0) {
@@ -478,16 +506,16 @@ export class LocalTime {
         }
         return `in ${_ms(msDiff * -1)}`;
     }
-    getDate() {
+    toDate() {
         return this.$date;
     }
     clone() {
         return new LocalTime(new Date(this.$date));
     }
-    unix() {
+    get unix() {
         return Math.floor(this.$date.valueOf() / 1000);
     }
-    unixMillis() {
+    get unixMillis() {
         return this.$date.valueOf();
     }
     valueOf() {
@@ -519,7 +547,7 @@ export class LocalTime {
      * Returns e.g: `1984-06-21`, only the date part of DateTime
      */
     toISODate() {
-        const { year, month, day } = this.getDateObject();
+        const { year, month, day } = this.toDateObject();
         return [
             String(year).padStart(4, '0'),
             String(month).padStart(2, '0'),
@@ -532,7 +560,7 @@ export class LocalTime {
      * Returns e.g: `17:03:15` (or `17:03` with seconds=false)
      */
     toISOTime(seconds = true) {
-        const { hour, minute, second } = this.getTimeObject();
+        const { hour, minute, second } = this.toTimeObject();
         return [
             String(hour).padStart(2, '0'),
             String(minute).padStart(2, '0'),
@@ -547,7 +575,7 @@ export class LocalTime {
      * Returns e.g: `19840621_1705`
      */
     toStringCompact(seconds = false) {
-        const { year, month, day, hour, minute, second } = this.getDateTimeObject();
+        const { year, month, day, hour, minute, second } = this.toDateTimeObject();
         return [
             String(year).padStart(4, '0'),
             String(month).padStart(2, '0'),
@@ -562,7 +590,7 @@ export class LocalTime {
         return this.toISODateTime();
     }
     toJSON() {
-        return this.unix();
+        return this.unix;
     }
     toMonthId() {
         return this.toISODate().slice(0, 7);
@@ -576,82 +604,117 @@ export class LocalTime {
 }
 class LocalTimeFactory {
     /**
-     * Parses input String into LocalDate.
-     * Input can already be a LocalDate - it is returned as-is in that case.
+     * Parses input String into LocalTime.
+     * Input can already be a LocalTime - it is returned as-is in that case.
      */
-    of(d) {
-        const t = this.parseOrNull(d);
-        _assert(t !== null, `Cannot parse "${d}" into LocalTime`, {
-            input: d,
-        });
-        return t;
+    from(input) {
+        const lt = this.fromOrNull(input);
+        this.assertNotNull(lt, input);
+        return lt;
+    }
+    fromDate(date) {
+        return new LocalTime(date);
+    }
+    fromUnix(ts) {
+        return new LocalTime(new Date(ts * 1000));
     }
     /**
      * Create LocalTime from unixTimestamp in milliseconds (not in seconds).
      */
-    ofMillis(millis) {
-        return this.of(new Date(millis));
+    fromMillis(millis) {
+        return new LocalTime(new Date(millis));
     }
     /**
      * Returns null if invalid
      */
-    parseOrNull(d) {
+    fromOrNull(d) {
         if (d instanceof LocalTime)
             return d;
-        let date;
         if (d instanceof Date) {
-            date = d;
+            return new LocalTime(d);
         }
-        else if (typeof d === 'number') {
-            date = new Date(d * 1000);
+        if (typeof d === 'number') {
+            return new LocalTime(new Date(d * 1000));
         }
-        else if (!d) {
-            // This check is after checking the number, to support `0`
-            return null;
+        if (typeof d === 'string') {
+            return this.fromStringOrNull(d);
         }
-        else if (typeof d !== 'string') {
-            // unexpected type, e.g Function or something
+        // This check is after checking the number, to support `0`
+        // unexpected type, e.g Function or something
+        return null;
+    }
+    fromStringOrNull(s) {
+        const date = this.parseStringToDateOrNull(s);
+        return date ? new LocalTime(date) : null;
+    }
+    fromDateTimeObject(input) {
+        const { year, month, day = 1, hour = 0, minute = 0, second = 0 } = input;
+        return new LocalTime(new Date(year, month - 1, day, hour, minute, second));
+    }
+    parseStringToDateOrNull(s) {
+        if (!s)
+            return null;
+        // Slicing removes the "timezone component", and makes the date "local"
+        // e.g 2022-04-06T23:15:00+09:00
+        // becomes 2022-04-06T23:15:00
+        // date = new Date(d.slice(0, 19))
+        // Parsing is inspired by how Day.js does it
+        // Specifically, it ensures that `localTime('2023-03-03')` returns the expected Date, and not a day before
+        // Because `new Date('2023-03-03')` in NewYork gives you '2023-03-02 19:00:00 GMT-0500'
+        const m = s.match(DATE_TIME_REGEX);
+        // Validate in 3 ways:
+        // 1. Should match Regex.
+        // In some ways it's stricter than Date constructor, e.g it doesn't allow 2023/05/05
+        // In other ways it's looser, e.g it allows `2023-05-05T`, while Date constructor doesn't.
+        // 2. Date constructor (of Node/v8 implementation, which we know is different from e.g WebKit/Safari)
+        // should not return `Invalid Date`.
+        // 3. Year, month and day should be valid, e.g 2023-01-32 should not be allowed.
+        // UPD: Actually, 3 can be skipped, because 2 is catching it already
+        // UPD: 2 is skipped, 1 and 3 are kept
+        // if (!m || isNaN(new Date(s).getDate())) return null
+        if (!m)
+            return null;
+        const year = Number(m[1]);
+        const month = Number(m[2]);
+        const day = Number(m[3]);
+        const hour = Number(m[5]);
+        const minute = Number(m[6]);
+        const second = Number(m[7]);
+        // Validation for just the Date part
+        if (!year ||
+            !month ||
+            month < 1 ||
+            month > 12 ||
+            !day ||
+            day < 1 ||
+            day > localDate.getMonthLength(year, month)) {
             return null;
         }
-        else {
-            // Slicing removes the "timezone component", and makes the date "local"
-            // e.g 2022-04-06T23:15:00+09:00
-            // becomes 2022-04-06T23:15:00
-            date = new Date(d.slice(0, 19));
-            // We used to slice to remove the timezone information, now we don't
-            // date = new Date(d)
-        }
-        // validation
-        if (isNaN(date.getDate())) {
-            // throw new TypeError(`Cannot parse "${d}" into LocalTime`)
+        // Validation for Date+Time string, since the string is longer than YYYY-MM-DD
+        if (s.length > 10 &&
+            (isNaN(hour) ||
+                isNaN(minute) ||
+                isNaN(second) ||
+                hour < 0 ||
+                hour > 23 ||
+                minute < 0 ||
+                minute > 59 ||
+                second < 0 ||
+                second > 59)) {
             return null;
         }
-        return new LocalTime(date);
+        return new Date(year, month - 1, day, hour || 0, minute || 0, second || 0, 0);
     }
-    parseToDate(d) {
-        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);
-        _assert(!isNaN(date.getDate()), `Cannot parse "${d}" to Date`, {
-            input: d,
-        });
-        return date;
+    isValid(input) {
+        return this.fromOrNull(input) !== null;
     }
-    parseToUnixTimestamp(d) {
-        if (typeof d === 'number')
-            return d;
-        if (d instanceof LocalTime)
-            return d.unix();
-        const date = d instanceof Date ? d : new Date(d);
-        _assert(!isNaN(date.getDate()), `Cannot parse "${d}" to UnixTimestamp`, {
-            input: d,
-        });
-        return date.valueOf() / 1000;
+    isValidString(isoString) {
+        return this.fromStringOrNull(isoString) !== null;
     }
-    isValid(d) {
-        return this.parseOrNull(d) !== null;
+    assertNotNull(lt, input) {
+        _assert(lt !== null, `Cannot parse "${input}" into LocalTime`, {
+            input,
+        });
     }
     /**
      * Returns the IANA timezone e.g `Europe/Stockholm`.
@@ -678,17 +741,14 @@ class LocalTimeFactory {
      *
      * `localTime` function will instead return LocalTime of `now` for falsy input.
      */
-    orUndefined(d) {
-        return d ? this.of(d) : undefined;
+    orUndefined(input) {
+        return input || input === 0 ? this.from(input) : undefined;
     }
     /**
      * Creates a LocalTime from the input, unless it's falsy - then returns LocalTime.now
      */
-    orNow(d) {
-        return d ? this.of(d) : this.now();
-    }
-    fromComponents(c) {
-        return new LocalTime(new Date(c.year, c.month - 1, c.day || 1, c.hour || 0, c.minute || 0, c.second || 0));
+    orNow(input) {
+        return input || input === 0 ? this.from(input) : this.now();
     }
     sort(items, dir = 'asc', mutate = false) {
         const mod = dir === 'desc' ? -1 : 1;
@@ -707,7 +767,7 @@ class LocalTimeFactory {
         const items2 = items.filter(_isTruthy);
         _assert(items2.length, 'localTime.min called on empty array');
         return items2
-            .map(i => this.of(i))
+            .map(i => this.from(i))
             .reduce((min, item) => (min.$date.valueOf() <= item.$date.valueOf() ? min : item));
     }
     maxOrUndefined(items) {
@@ -717,7 +777,7 @@ class LocalTimeFactory {
         const items2 = items.filter(_isTruthy);
         _assert(items2.length, 'localTime.max called on empty array');
         return items2
-            .map(i => this.of(i))
+            .map(i => this.from(i))
             .reduce((max, item) => (max.$date.valueOf() >= item.$date.valueOf() ? max : item));
     }
 }
@@ -810,7 +870,7 @@ function differenceInMonths(a, b) {
     return -(wholeMonthDiff + ((b.getTime() - anchor) / (anchor2 - anchor)) * sign);
 }
 const localTimeFactory = new LocalTimeFactory();
-export const localTime = localTimeFactory.of.bind(localTimeFactory);
+export const localTime = localTimeFactory.from.bind(localTimeFactory);
 // The line below is the blackest of black magic I have ever written in 2024.
 // And probably 2023 as well.
 Object.setPrototypeOf(localTime, localTimeFactory);

package/dist-esm/datetime/timeInterval.js

@@ -11,7 +11,7 @@ export class TimeInterval {
         this.$end = $end;
     }
     static of(start, end) {
-        return new TimeInterval(localTime.parseToUnixTimestamp(start), localTime.parseToUnixTimestamp(end));
+        return new TimeInterval(localTime.from(start).unix, localTime.from(end).unix);
     }
     get start() {
         return this.$start;
@@ -55,7 +55,7 @@ export class TimeInterval {
         return this.cmp(d) >= 0;
     }
     includes(d, incl = '[)') {
-        d = localTime.parseToUnixTimestamp(d);
+        d = localTime.from(d).unix;
         // eslint-disable-next-line @typescript-eslint/prefer-string-starts-ends-with
         if (d < this.$start || (d === this.$start && incl[0] === '('))
             return false;

package/dist-esm/env/buildInfo.js

@@ -1,11 +1,11 @@
 import { localTime } from '../datetime/localTime';
 export function generateBuildInfoDev() {
     const now = localTime.now();
-    const ts = now.unix();
+    const ts = now.unix;
     const rev = 'devRev';
     const branchName = 'devBranch';
     const repoName = 'devRepo';
-    const tsCommit = now.unix();
+    const tsCommit = now.unix;
     const ver = [now.toStringCompact(), repoName, branchName, rev].join('_');
     return {
         ts,

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@naturalcycles/js-lib",
-  "version": "14.243.0",
+  "version": "14.244.0",
   "scripts": {
     "prepare": "husky",
     "build-prod": "build-prod-esm-cjs",
     "test-tz1": "TZ=Europe/Stockholm yarn test local",
     "test-tz2": "TZ=JST-9 yarn test local",
+    "test-ny": "TZ=GMT-0500 yarn test localTime",
     "docs-dev": "vitepress dev docs --open",
     "docs-build": "vitepress build docs",
     "docs-preview": "vitepress preview docs"

package/src/datetime/dateInterval.ts

@@ -77,7 +77,7 @@ export class DateInterval {
    */
   cmp(d: DateIntervalConfig): -1 | 0 | 1 {
     d = DateInterval.parse(d)
-    return this.start.cmp(d.start) || this.end.cmp(d.end)
+    return this.start.compare(d.start) || this.end.compare(d.end)
   }
 
   getDays(incl: Inclusiveness = '[]'): LocalDate[] {