@naturalcycles/js-lib 14.243.1 → 14.244.0

package/dist/datetime/localTime.d.ts

@@ -15,6 +15,7 @@ export type LocalTimeInput = LocalTime | Date | IsoDateTimeString | UnixTimestam
 export type LocalTimeInputNullable = LocalTimeInput | null | undefined;
 export type LocalTimeFormatter = (ld: LocalTime) => string;
 export type DateTimeObject = DateObject & TimeObject;
+export type DateTimeObjectInput = DateObject & Partial<TimeObject>;
 export interface DateObject {
     year: number;
     month: number;
@@ -32,12 +33,12 @@ export declare class LocalTime {
      * Returns [cloned] LocalTime that is based on the same unixtimestamp, but in UTC timezone.
      * Opposite of `.local()` method.
      */
-    utc(): LocalTime;
+    toUTC(): LocalTime;
     /**
      * Returns [cloned] LocalTime that is based on the same unixtimestamp, but in local timezone.
      * Opposite of `.utc()` method.
      */
-    local(): LocalTime;
+    toLocal(): LocalTime;
     /**
      * Returns [cloned] fake LocalTime that has yyyy-mm-dd hh:mm:ss in the provided timezone.
      * It is a fake LocalTime in a sense that it's timezone is not real.
@@ -85,25 +86,25 @@ export declare class LocalTime {
     getUTCOffsetString(tz: string): string;
     get(unit: LocalTimeUnit): number;
     set(unit: LocalTimeUnit, v: number, mutate?: boolean): LocalTime;
-    year(): number;
-    year(v: number): LocalTime;
-    month(): number;
-    month(v: number): LocalTime;
-    week(): number;
-    week(v: number): LocalTime;
-    day(): number;
-    day(v: number): LocalTime;
+    get year(): number;
+    setYear(v: number): LocalTime;
+    get month(): number;
+    setMonth(v: number): LocalTime;
+    get week(): number;
+    setWeek(v: number): LocalTime;
+    get day(): number;
+    setDay(v: number): LocalTime;
+    get hour(): number;
+    setHour(v: number): LocalTime;
+    get minute(): number;
+    setMinute(v: number): LocalTime;
+    get second(): number;
+    setSecond(v: number): LocalTime;
     /**
      * Based on ISO: 1-7 is Mon-Sun.
      */
-    dayOfWeek(): ISODayOfWeek;
-    dayOfWeek(v: ISODayOfWeek): LocalTime;
-    hour(): number;
-    hour(v: number): LocalTime;
-    minute(): number;
-    minute(v: number): LocalTime;
-    second(): number;
-    second(v: number): LocalTime;
+    get dayOfWeek(): ISODayOfWeek;
+    setDayOfWeek(v: ISODayOfWeek): LocalTime;
     setComponents(c: Partial<DateTimeObject>, mutate?: boolean): LocalTime;
     plusSeconds(num: number): LocalTime;
     plusMinutes(num: number): LocalTime;
@@ -129,7 +130,7 @@ export declare class LocalTime {
      * Returns how many days are in the current month.
      * E.g 31 for January.
      */
-    daysInMonth(): number;
+    get daysInMonth(): number;
     isSame(d: LocalTimeInput): boolean;
     isBefore(d: LocalTimeInput, inclusive?: boolean): boolean;
     isSameOrBefore(d: LocalTimeInput): boolean;
@@ -176,15 +177,15 @@ export declare class LocalTime {
      * returns 0 if they are equal
      * returns -1 if this < d
      */
-    cmp(d: LocalTimeInput): -1 | 0 | 1;
-    getDateTimeObject(): DateTimeObject;
-    getDateObject(): DateObject;
-    getTimeObject(): TimeObject;
-    fromNow(now?: LocalTimeInput): string;
-    getDate(): Date;
+    compare(d: LocalTimeInput): -1 | 0 | 1;
+    toDateTimeObject(): DateTimeObject;
+    toDateObject(): DateObject;
+    toTimeObject(): TimeObject;
+    toFromNowString(now?: LocalTimeInput): string;
+    toDate(): Date;
     clone(): LocalTime;
-    unix(): UnixTimestampNumber;
-    unixMillis(): UnixTimestampMillisNumber;
+    get unix(): UnixTimestampNumber;
+    get unixMillis(): UnixTimestampMillisNumber;
     valueOf(): UnixTimestampNumber;
     toLocalDate(): LocalDate;
     /**
@@ -216,20 +217,26 @@ export declare class LocalTime {
 }
 declare 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: LocalTimeInput): LocalTime;
+    from(input: LocalTimeInput): LocalTime;
+    fromDate(date: Date): LocalTime;
+    fromUnix(ts: UnixTimestampNumber): LocalTime;
     /**
      * Create LocalTime from unixTimestamp in milliseconds (not in seconds).
      */
-    ofMillis(millis: UnixTimestampMillisNumber): LocalTime;
+    fromMillis(millis: UnixTimestampMillisNumber): LocalTime;
     /**
      * Returns null if invalid
      */
-    parseOrNull(d: LocalTimeInputNullable): LocalTime | null;
+    fromOrNull(d: LocalTimeInputNullable): LocalTime | null;
+    fromStringOrNull(s: string | undefined | null): LocalTime | null;
+    fromDateTimeObject(input: DateTimeObjectInput): LocalTime;
     private parseStringToDateOrNull;
-    isValid(d: LocalTimeInputNullable): boolean;
+    isValid(input: LocalTimeInputNullable): boolean;
+    isValidString(isoString: string | undefined | null): boolean;
+    private assertNotNull;
     /**
      * Returns the IANA timezone e.g `Europe/Stockholm`.
      * https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
@@ -249,15 +256,11 @@ declare class LocalTimeFactory {
      *
      * `localTime` function will instead return LocalTime of `now` for falsy input.
      */
-    orUndefined(d: LocalTimeInputNullable): LocalTime | undefined;
+    orUndefined(input: LocalTimeInputNullable): LocalTime | undefined;
     /**
      * Creates a LocalTime from the input, unless it's falsy - then returns LocalTime.now
      */
-    orNow(d: LocalTimeInputNullable): LocalTime;
-    fromComponents(c: {
-        year: number;
-        month: number;
-    } & Partial<DateTimeObject>): LocalTime;
+    orNow(input: LocalTimeInputNullable): LocalTime;
     sort(items: LocalTime[], dir?: SortDirection, mutate?: boolean): LocalTime[];
     minOrUndefined(items: LocalTimeInputNullable[]): LocalTime | undefined;
     min(items: LocalTimeInputNullable[]): LocalTime;

package/dist/datetime/localTime.js

@@ -35,14 +35,14 @@ 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()));
     }
     /**
@@ -164,34 +164,58 @@ 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;
-        }
-        (0, assert_1._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();
     }
-    second(v) {
-        return v === undefined ? this.get('second') : this.set('second', v);
+    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();
+    }
+    setSecond(v) {
+        return this.set('second', v);
+    }
+    /**
+     * Based on ISO: 1-7 is Mon-Sun.
+     */
+    get dayOfWeek() {
+        return (this.$date.getDay() || 7);
+    }
+    setDayOfWeek(v) {
+        (0, assert_1._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);
@@ -259,7 +283,7 @@ class LocalTime {
         }
         if (unit === 'year' || unit === 'month') {
             const d = addMonths(this.$date, unit === 'month' ? num : num * 12, mutate);
-            return mutate ? this : exports.localTime.of(d);
+            return mutate ? this : exports.localTime.from(d);
         }
         return this.set(unit, this.get(unit) + num, mutate);
     }
@@ -270,7 +294,7 @@ class LocalTime {
         return Math.abs(this.diff(other, unit));
     }
     diff(other, unit) {
-        const date2 = exports.localTime.of(other).$date;
+        const date2 = exports.localTime.from(other).$date;
         const secDiff = (this.$date.valueOf() - date2.valueOf()) / 1000;
         if (!secDiff)
             return 0;
@@ -358,32 +382,32 @@ class LocalTime {
      * Returns how many days are in the current month.
      * E.g 31 for January.
      */
-    daysInMonth() {
+    get daysInMonth() {
         return localDate_1.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;
@@ -398,13 +422,13 @@ class LocalTime {
      * Third argument allows to override "now".
      */
     isOlderThan(n, unit, now) {
-        return this.isBefore(exports.localTime.of(now ?? new Date()).plus(-n, unit));
+        return this.isBefore(exports.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(exports.localTime.of(now ?? new Date()).plus(-n, unit));
+        return this.isSameOrBefore(exports.localTime.from(now ?? new Date()).plus(-n, unit));
     }
     /**
      * Checks if this localTime is younger (>) than "now" by X units.
@@ -416,13 +440,13 @@ class LocalTime {
      * Third argument allows to override "now".
      */
     isYoungerThan(n, unit, now) {
-        return this.isAfter(exports.localTime.of(now ?? new Date()).plus(-n, unit));
+        return this.isAfter(exports.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(exports.localTime.of(now ?? new Date()).plus(-n, unit));
+        return this.isSameOrAfter(exports.localTime.from(now ?? new Date()).plus(-n, unit));
     }
     getAgeInYears(now) {
         return this.getAgeIn('year', now);
@@ -443,42 +467,42 @@ class LocalTime {
         return this.getAgeIn('second', now);
     }
     getAgeIn(unit, now) {
-        return exports.localTime.of(now ?? new Date()).diff(this, unit);
+        return exports.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 = exports.localTime.of(d).$date.valueOf();
+        const t2 = exports.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 = exports.localTime.of(now).$date.valueOf() - this.$date.valueOf();
+    toFromNowString(now = new Date()) {
+        const msDiff = exports.localTime.from(now).$date.valueOf() - this.$date.valueOf();
         if (msDiff === 0)
             return 'now';
         if (msDiff >= 0) {
@@ -486,16 +510,16 @@ class LocalTime {
         }
         return `in ${(0, time_util_1._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() {
@@ -527,7 +551,7 @@ 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'),
@@ -540,7 +564,7 @@ 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'),
@@ -555,7 +579,7 @@ 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'),
@@ -570,7 +594,7 @@ class LocalTime {
         return this.toISODateTime();
     }
     toJSON() {
-        return this.unix();
+        return this.unix;
     }
     toMonthId() {
         return this.toISODate().slice(0, 7);
@@ -585,51 +609,56 @@ class LocalTime {
 exports.LocalTime = 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);
-        (0, assert_1._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;
-        }
-        else if (typeof d !== 'string') {
-            // unexpected type, e.g Function or something
-            return null;
-        }
-        else {
-            date = this.parseStringToDateOrNull(d);
-            if (date === null)
-                return null;
+        if (typeof d === 'string') {
+            return this.fromStringOrNull(d);
         }
-        return new LocalTime(date);
+        // 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
@@ -681,8 +710,16 @@ class LocalTimeFactory {
         }
         return new Date(year, month - 1, day, hour || 0, minute || 0, second || 0, 0);
     }
-    isValid(d) {
-        return this.parseOrNull(d) !== null;
+    isValid(input) {
+        return this.fromOrNull(input) !== null;
+    }
+    isValidString(isoString) {
+        return this.fromStringOrNull(isoString) !== null;
+    }
+    assertNotNull(lt, input) {
+        (0, assert_1._assert)(lt !== null, `Cannot parse "${input}" into LocalTime`, {
+            input,
+        });
     }
     /**
      * Returns the IANA timezone e.g `Europe/Stockholm`.
@@ -709,17 +746,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;
@@ -738,7 +772,7 @@ class LocalTimeFactory {
         const items2 = items.filter(is_util_1._isTruthy);
         (0, assert_1._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) {
@@ -748,7 +782,7 @@ class LocalTimeFactory {
         const items2 = items.filter(is_util_1._isTruthy);
         (0, assert_1._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));
     }
 }
@@ -841,7 +875,7 @@ function differenceInMonths(a, b) {
     return -(wholeMonthDiff + ((b.getTime() - anchor) / (anchor2 - anchor)) * sign);
 }
 const localTimeFactory = new LocalTimeFactory();
-exports.localTime = localTimeFactory.of.bind(localTimeFactory);
+exports.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(exports.localTime, localTimeFactory);

package/dist/datetime/timeInterval.js

@@ -14,7 +14,7 @@ class TimeInterval {
         this.$end = $end;
     }
     static of(start, end) {
-        return new TimeInterval(localTime_1.localTime.of(start).unix(), localTime_1.localTime.of(end).unix());
+        return new TimeInterval(localTime_1.localTime.from(start).unix, localTime_1.localTime.from(end).unix);
     }
     get start() {
         return this.$start;
@@ -58,7 +58,7 @@ class TimeInterval {
         return this.cmp(d) >= 0;
     }
     includes(d, incl = '[)') {
-        d = localTime_1.localTime.of(d).unix();
+        d = localTime_1.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/env/buildInfo.js

@@ -4,11 +4,11 @@ exports.generateBuildInfoDev = generateBuildInfoDev;
 const localTime_1 = require("../datetime/localTime");
 function generateBuildInfoDev() {
     const now = localTime_1.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/dist-esm/datetime/dateInterval.js

@@ -60,7 +60,7 @@ export class DateInterval {
      */
     cmp(d) {
         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 = '[]') {
         return localDate.range(this.start, this.end, incl, 1, 'day');