@naturalcycles/js-lib 14.99.3 → 14.101.0

package/dist/datetime/localDate.d.ts

@@ -1,4 +1,4 @@
-import { IsoDateString, IsoDateTimeString, UnixTimestampNumber } from '../types';
+import { IsoDateString, IsoDateTimeString, UnixTimestampMillisNumber, UnixTimestampNumber } from '../types';
 import { LocalTime } from './localTime';
 export declare type LocalDateUnit = LocalDateUnitStrict | 'week';
 export declare type LocalDateUnitStrict = 'year' | 'month' | 'day';
@@ -89,7 +89,7 @@ export declare class LocalDate {
     toString(): IsoDateString;
     toStringCompact(): string;
     unix(): UnixTimestampNumber;
-    unixMillis(): number;
+    unixMillis(): UnixTimestampMillisNumber;
     toJSON(): IsoDateString;
     format(fmt: LocalDateFormatter): string;
 }

package/dist/datetime/localDate.js

@@ -218,15 +218,23 @@ class LocalDate {
         const [big, small] = sign === 1 ? [this, d] : [d, this];
         if (unit === 'year') {
             let years = big.$year - small.$year;
-            if (big.$month < small.$month || (big.$month === small.$month && big.$day < small.$day)) {
+            if (big.$month < small.$month ||
+                (big.$month === small.$month &&
+                    big.$day < small.$day &&
+                    !(big.$day === LocalDate.getMonthLength(big.$year, big.$month) &&
+                        small.$day === LocalDate.getMonthLength(small.$year, small.$month)))) {
                 years--;
             }
             return years * sign || 0;
         }
         if (unit === 'month') {
             let months = (big.$year - small.$year) * 12 + (big.$month - small.$month);
-            if (big.$day < small.$day)
-                months--;
+            if (big.$day < small.$day) {
+                const bigMonthLen = LocalDate.getMonthLength(big.$year, big.$month);
+                if (big.$day !== bigMonthLen || small.$day < bigMonthLen) {
+                    months--;
+                }
+            }
             return months * sign || 0;
         }
         // unit is 'day' or 'week'
@@ -266,20 +274,36 @@ class LocalDate {
         else if (unit === 'year') {
             $year += num;
         }
+        // check month overflow
+        while ($month > 12) {
+            $year += 1;
+            $month -= 12;
+        }
+        while ($month < 1) {
+            $year -= 1;
+            $month += 12;
+        }
         // check day overflow
-        if (unit === 'day') {
-            if ($day < 1) {
-                while ($day < 1) {
-                    $month -= 1;
-                    if ($month < 1) {
-                        $year -= 1;
-                        $month += 12;
-                    }
-                    $day += LocalDate.getMonthLength($year, $month);
+        // Applies not only for 'day' unit, but also e.g 2022-05-31 plus 1 month should be 2022-06-30 (not 31!)
+        if ($day < 1) {
+            while ($day < 1) {
+                $month -= 1;
+                if ($month < 1) {
+                    $year -= 1;
+                    $month += 12;
+                }
+                $day += LocalDate.getMonthLength($year, $month);
+            }
+        }
+        else {
+            let monLen = LocalDate.getMonthLength($year, $month);
+            if (unit !== 'day') {
+                if ($day > monLen) {
+                    // Case of 2022-05-31 plus 1 month should be 2022-06-30, not 31
+                    $day = monLen;
                 }
             }
             else {
-                let monLen = LocalDate.getMonthLength($year, $month);
                 while ($day > monLen) {
                     $day -= monLen;
                     $month += 1;
@@ -291,15 +315,6 @@ class LocalDate {
                 }
             }
         }
-        // check month overflow
-        while ($month > 12) {
-            $year += 1;
-            $month -= 12;
-        }
-        while ($month < 1) {
-            $year -= 1;
-            $month += 12;
-        }
         if (mutate) {
             this.$year = $year;
             this.$month = $month;

package/dist/datetime/localTime.d.ts

@@ -1,4 +1,4 @@
-import { IsoDateString, IsoDateTimeString, UnixTimestampNumber } from '../types';
+import { IsoDateString, IsoDateTimeString, UnixTimestampMillisNumber, UnixTimestampNumber } from '../types';
 import { Inclusiveness, LocalDate } from './localDate';
 export declare type LocalTimeUnit = 'year' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second';
 export declare enum ISODayOfWeek {
@@ -31,6 +31,10 @@ export declare class LocalTime {
      * Input can already be a LocalDate - it is returned as-is in that case.
      */
     static of(d: LocalTimeConfig): LocalTime;
+    /**
+     * Create LocalTime from unixTimestamp in milliseconds (not in seconds).
+     */
+    static ofMillis(millis: UnixTimestampMillisNumber): LocalTime;
     /**
      * Returns null if invalid
      */
@@ -93,7 +97,7 @@ export declare class LocalTime {
     getDate(): Date;
     clone(): LocalTime;
     unix(): UnixTimestampNumber;
-    unixMillis(): number;
+    unixMillis(): UnixTimestampMillisNumber;
     valueOf(): UnixTimestampNumber;
     toLocalDate(): LocalDate;
     toPretty(seconds?: boolean): IsoDateTimeString;

package/dist/datetime/localTime.js

@@ -39,6 +39,12 @@ class LocalTime {
         }
         return t;
     }
+    /**
+     * Create LocalTime from unixTimestamp in milliseconds (not in seconds).
+     */
+    static ofMillis(millis) {
+        return LocalTime.of(new Date(millis));
+    }
     /**
      * Returns null if invalid
      */
@@ -177,14 +183,9 @@ class LocalTime {
     }
     setComponents(c, mutate = false) {
         const d = mutate ? this.$date : new Date(this.$date);
-        if (c.year) {
-            d.setFullYear(c.year);
-        }
-        if (c.month) {
-            d.setMonth(c.month - 1);
-        }
-        if (c.day) {
-            d.setDate(c.day);
+        // Year, month and day set all-at-once, to avoid 30/31 (and 28/29) mishap
+        if (c.day || c.month !== undefined || c.year !== undefined) {
+            d.setFullYear(c.year ?? d.getFullYear(), c.month ? c.month - 1 : d.getMonth(), c.day || d.getDate());
         }
         if (c.hour !== undefined) {
             d.setHours(c.hour);
@@ -202,6 +203,10 @@ class LocalTime {
             num *= 7;
             unit = 'day';
         }
+        if (unit === 'year' || unit === 'month') {
+            const d = addMonths(this.$date, unit === 'month' ? num : num * 12, mutate);
+            return mutate ? this : LocalTime.of(d);
+        }
         return this.set(unit, this.get(unit) + num, mutate);
     }
     subtract(num, unit, mutate = false) {
@@ -215,33 +220,14 @@ class LocalTime {
         const secDiff = (this.$date.valueOf() - date2.valueOf()) / 1000;
         if (!secDiff)
             return 0;
-        if (unit === 'year' || unit === 'month') {
-            const sign = secDiff > 0 ? 1 : -1;
-            // Put items in descending order: "big minus small"
-            const [big, small] = sign === 1 ? [this.$date, date2] : [date2, this.$date];
-            if (unit === 'year') {
-                let years = big.getFullYear() - small.getFullYear();
-                const big2 = new Date(big);
-                const small2 = new Date(small);
-                big2.setFullYear(1584);
-                small2.setFullYear(1584);
-                if (big2 < small2)
-                    years--;
-                return years * sign || 0;
-            }
-            if (unit === 'month') {
-                let months = (big.getFullYear() - small.getFullYear()) * 12 + big.getMonth() - small.getMonth();
-                const big2 = new Date(big);
-                const small2 = new Date(small);
-                big2.setFullYear(1584, 0);
-                small2.setFullYear(1584, 0);
-                if (big2 < small2)
-                    months--;
-                return months * sign || 0;
-            }
-        }
         let r;
-        if (unit === 'day') {
+        if (unit === 'year') {
+            r = differenceInMonths(this.getDate(), date2) / 12;
+        }
+        else if (unit === 'month') {
+            r = differenceInMonths(this.getDate(), date2);
+        }
+        else if (unit === 'day') {
             r = secDiff / SECONDS_IN_DAY;
         }
         else if (unit === 'week') {
@@ -486,7 +472,7 @@ class LocalTime {
         ].join('');
     }
     toString() {
-        return String(this.unix());
+        return this.toISODateTime();
     }
     toJSON() {
         return this.unix();
@@ -543,29 +529,6 @@ function getWeekYear(date) {
         return year - 1;
     }
 }
-// function setWeekYear(
-//   date: Date,
-//   year: number,
-// ): Date {
-//   const diff = differenceInCalendarDays(date, startOfWeekYear(date))
-//   const fourthOfJanuary = new Date(0)
-//   fourthOfJanuary.setFullYear(year, 0, 4)
-//   fourthOfJanuary.setHours(0, 0, 0, 0)
-//   date = startOfWeekYear(fourthOfJanuary)
-//   date.setDate(date.getDate() + diff)
-//   return date
-// }
-// function differenceInCalendarDays(
-//   dateLeft: Date,
-//   dateRight: Date,
-// ): number {
-//   return Math.round((startOfDay(dateLeft).getTime() - startOfDay(dateRight).getTime()) / MILLISECONDS_IN_DAY)
-// }
-// function startOfDay(date: Date, mutate = false): Date {
-//   const d = mutate ? date : new Date(date)
-//   d.setHours(0, 0, 0, 0)
-//   return d
-// }
 // based on: https://github.com/date-fns/date-fns/blob/fd6bb1a0bab143f2da068c05a9c562b9bee1357d/src/startOfWeek/index.ts
 function startOfWeek(date, mutate = false) {
     const d = mutate ? date : new Date(date);
@@ -583,3 +546,36 @@ function endOfWeek(date, mutate = false) {
     d.setDate(d.getDate() + diff);
     return d;
 }
+function addMonths(d, num, mutate = false) {
+    if (!mutate)
+        d = new Date(d);
+    let day = d.getDate();
+    let month = d.getMonth() + 1 + num;
+    if (day < 29) {
+        d.setMonth(month - 1);
+        return d;
+    }
+    let year = d.getFullYear();
+    while (month > 12) {
+        year++;
+        month -= 12;
+    }
+    while (month < 1) {
+        year--;
+        month += 12;
+    }
+    const monthLen = localDate_1.LocalDate.getMonthLength(year, month);
+    if (day > monthLen)
+        day = monthLen;
+    d.setFullYear(year, month - 1, day);
+    return d;
+}
+function differenceInMonths(a, b) {
+    if (a.getDate() < b.getDate())
+        return -differenceInMonths(b, a);
+    const wholeMonthDiff = (b.getFullYear() - a.getFullYear()) * 12 + (b.getMonth() - a.getMonth());
+    const anchor = addMonths(a, wholeMonthDiff).getTime();
+    const sign = b.getTime() - anchor >= 0 ? 1 : -1;
+    const anchor2 = addMonths(a, wholeMonthDiff + sign).getTime();
+    return -(wholeMonthDiff + ((b.getTime() - anchor) / (anchor2 - anchor)) * sign);
+}

package/dist/index.d.ts

@@ -51,7 +51,7 @@ export * from './string/string.util';
 import { JsonStringifyFunction, StringifyAnyOptions, _stringifyAny } from './string/stringifyAny';
 export * from './time/time.util';
 import { Class, ConditionalExcept, ConditionalPick, Merge, Promisable, ReadonlyDeep, Simplify } from './typeFest';
-import { AsyncMapper, AsyncPredicate, BaseDBEntity, CreatedUpdated, CreatedUpdatedId, ObjectWithId, AnyObjectWithId, Saved, Unsaved, UnsavedId, BatchResult, InstanceId, IsoDate, IsoDateString, IsoDateTimeString, KeyValueTuple, Mapper, ObjectMapper, ObjectPredicate, Predicate, PromiseMap, AnyObject, AnyFunction, Reviver, SavedDBEntity, StringMap, UnixTimestampNumber, UnixTimestamp, Integer, ValueOf, ValuesOf, AbortableMapper, AbortableAsyncPredicate, AbortableAsyncMapper, AbortablePredicate, END, SKIP, _noop, _objectKeys, _passNothingPredicate, _passthroughMapper, _passthroughPredicate, _passUndefinedMapper, _stringMapEntries, _stringMapValues } from './types';
+import { AsyncMapper, AsyncPredicate, BaseDBEntity, CreatedUpdated, CreatedUpdatedId, ObjectWithId, AnyObjectWithId, Saved, Unsaved, UnsavedId, BatchResult, InstanceId, IsoDate, IsoDateString, IsoDateTimeString, KeyValueTuple, Mapper, ObjectMapper, ObjectPredicate, Predicate, PromiseMap, AnyObject, AnyFunction, Reviver, SavedDBEntity, StringMap, UnixTimestampNumber, UnixTimestampMillisNumber, UnixTimestamp, Integer, ValueOf, ValuesOf, AbortableMapper, AbortableAsyncPredicate, AbortableAsyncMapper, AbortablePredicate, END, SKIP, _noop, _objectKeys, _passNothingPredicate, _passthroughMapper, _passthroughPredicate, _passUndefinedMapper, _stringMapEntries, _stringMapValues } from './types';
 export * from './unit/size.util';
 import { is } from './vendor/is';
 import { CommonLogLevel, CommonLogFunction, CommonLogger, commonLoggerMinLevel, commonLoggerNoop, commonLogLevelNumber, commonLoggerPipe, commonLoggerPrefix, CommonLogWithLevelFunction, commonLoggerCreate } from './log/commonLogger';
@@ -68,5 +68,5 @@ import { LocalDateConfig, LocalDateFormatter, LocalDateUnit, LocalDateUnitStrict
 import { LocalTimeConfig, LocalTimeFormatter, LocalTimeUnit, LocalTimeComponents, ISODayOfWeek } from './datetime/localTime';
 import { DateIntervalConfig, DateIntervalString } from './datetime/dateInterval';
 import { TimeIntervalConfig, TimeIntervalString } from './datetime/timeInterval';
-export type { DateIntervalConfig, DateIntervalString, TimeIntervalConfig, TimeIntervalString, LocalDateConfig, LocalDateFormatter, LocalDateUnit, LocalDateUnitStrict, Inclusiveness, LocalTimeConfig, LocalTimeFormatter, LocalTimeUnit, ISODayOfWeek, LocalTimeComponents, AbortableMapper, AbortablePredicate, AbortableAsyncPredicate, AbortableAsyncMapper, PQueueCfg, MemoCache, AsyncMemoCache, PromiseDecoratorCfg, PromiseDecoratorResp, ErrorData, ErrorObject, HttpErrorData, HttpErrorResponse, Admin401ErrorData, Admin403ErrorData, StringMap, PromiseMap, AnyObject, AnyFunction, ValuesOf, ValueOf, KeyValueTuple, ObjectMapper, ObjectPredicate, InstanceId, IsoDate, IsoDateString, IsoDateTimeString, Reviver, PMapOptions, Mapper, AsyncMapper, Predicate, AsyncPredicate, BatchResult, DeferredPromise, PRetryOptions, PTimeoutOptions, TryCatchOptions, StringifyAnyOptions, JsonStringifyFunction, Merge, ReadonlyDeep, Promisable, Simplify, ConditionalPick, ConditionalExcept, Class, UnixTimestampNumber, UnixTimestamp, Integer, BaseDBEntity, SavedDBEntity, Saved, Unsaved, UnsavedId, CreatedUpdated, CreatedUpdatedId, ObjectWithId, AnyObjectWithId, JsonSchema, JsonSchemaAny, JsonSchemaOneOf, JsonSchemaAllOf, JsonSchemaAnyOf, JsonSchemaNot, JsonSchemaRef, JsonSchemaConst, JsonSchemaEnum, JsonSchemaString, JsonSchemaNumber, JsonSchemaBoolean, JsonSchemaNull, JsonSchemaRootObject, JsonSchemaObject, JsonSchemaArray, JsonSchemaTuple, JsonSchemaBuilder, CommonLogLevel, CommonLogWithLevelFunction, CommonLogFunction, CommonLogger, };
+export type { DateIntervalConfig, DateIntervalString, TimeIntervalConfig, TimeIntervalString, LocalDateConfig, LocalDateFormatter, LocalDateUnit, LocalDateUnitStrict, Inclusiveness, LocalTimeConfig, LocalTimeFormatter, LocalTimeUnit, ISODayOfWeek, LocalTimeComponents, AbortableMapper, AbortablePredicate, AbortableAsyncPredicate, AbortableAsyncMapper, PQueueCfg, MemoCache, AsyncMemoCache, PromiseDecoratorCfg, PromiseDecoratorResp, ErrorData, ErrorObject, HttpErrorData, HttpErrorResponse, Admin401ErrorData, Admin403ErrorData, StringMap, PromiseMap, AnyObject, AnyFunction, ValuesOf, ValueOf, KeyValueTuple, ObjectMapper, ObjectPredicate, InstanceId, IsoDate, IsoDateString, IsoDateTimeString, Reviver, PMapOptions, Mapper, AsyncMapper, Predicate, AsyncPredicate, BatchResult, DeferredPromise, PRetryOptions, PTimeoutOptions, TryCatchOptions, StringifyAnyOptions, JsonStringifyFunction, Merge, ReadonlyDeep, Promisable, Simplify, ConditionalPick, ConditionalExcept, Class, UnixTimestampNumber, UnixTimestampMillisNumber, UnixTimestamp, Integer, BaseDBEntity, SavedDBEntity, Saved, Unsaved, UnsavedId, CreatedUpdated, CreatedUpdatedId, ObjectWithId, AnyObjectWithId, JsonSchema, JsonSchemaAny, JsonSchemaOneOf, JsonSchemaAllOf, JsonSchemaAnyOf, JsonSchemaNot, JsonSchemaRef, JsonSchemaConst, JsonSchemaEnum, JsonSchemaString, JsonSchemaNumber, JsonSchemaBoolean, JsonSchemaNull, JsonSchemaRootObject, JsonSchemaObject, JsonSchemaArray, JsonSchemaTuple, JsonSchemaBuilder, CommonLogLevel, CommonLogWithLevelFunction, CommonLogFunction, CommonLogger, };
 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/dist/types.d.ts

@@ -154,6 +154,12 @@ export declare type IsoDateTimeString = string;
  * @example 1628945450
  */
 export declare type UnixTimestampNumber = number;
+/**
+ * Interface explicitly states that the value is a "Unix timestamp in **milleseconds**" (not seconds)
+ *
+ * @example 1628945450000
+ */
+export declare type UnixTimestampMillisNumber = number;
 /**
  * @deprecated use UnixTimestampNumber
  */

package/dist-esm/datetime/localDate.js

@@ -215,15 +215,23 @@ export class LocalDate {
         const [big, small] = sign === 1 ? [this, d] : [d, this];
         if (unit === 'year') {
             let years = big.$year - small.$year;
-            if (big.$month < small.$month || (big.$month === small.$month && big.$day < small.$day)) {
+            if (big.$month < small.$month ||
+                (big.$month === small.$month &&
+                    big.$day < small.$day &&
+                    !(big.$day === LocalDate.getMonthLength(big.$year, big.$month) &&
+                        small.$day === LocalDate.getMonthLength(small.$year, small.$month)))) {
                 years--;
             }
             return years * sign || 0;
         }
         if (unit === 'month') {
             let months = (big.$year - small.$year) * 12 + (big.$month - small.$month);
-            if (big.$day < small.$day)
-                months--;
+            if (big.$day < small.$day) {
+                const bigMonthLen = LocalDate.getMonthLength(big.$year, big.$month);
+                if (big.$day !== bigMonthLen || small.$day < bigMonthLen) {
+                    months--;
+                }
+            }
             return months * sign || 0;
         }
         // unit is 'day' or 'week'
@@ -263,20 +271,36 @@ export class LocalDate {
         else if (unit === 'year') {
             $year += num;
         }
+        // check month overflow
+        while ($month > 12) {
+            $year += 1;
+            $month -= 12;
+        }
+        while ($month < 1) {
+            $year -= 1;
+            $month += 12;
+        }
         // check day overflow
-        if (unit === 'day') {
-            if ($day < 1) {
-                while ($day < 1) {
-                    $month -= 1;
-                    if ($month < 1) {
-                        $year -= 1;
-                        $month += 12;
-                    }
-                    $day += LocalDate.getMonthLength($year, $month);
+        // Applies not only for 'day' unit, but also e.g 2022-05-31 plus 1 month should be 2022-06-30 (not 31!)
+        if ($day < 1) {
+            while ($day < 1) {
+                $month -= 1;
+                if ($month < 1) {
+                    $year -= 1;
+                    $month += 12;
+                }
+                $day += LocalDate.getMonthLength($year, $month);
+            }
+        }
+        else {
+            let monLen = LocalDate.getMonthLength($year, $month);
+            if (unit !== 'day') {
+                if ($day > monLen) {
+                    // Case of 2022-05-31 plus 1 month should be 2022-06-30, not 31
+                    $day = monLen;
                 }
             }
             else {
-                let monLen = LocalDate.getMonthLength($year, $month);
                 while ($day > monLen) {
                     $day -= monLen;
                     $month += 1;
@@ -288,15 +312,6 @@ export class LocalDate {
                 }
             }
         }
-        // check month overflow
-        while ($month > 12) {
-            $year += 1;
-            $month -= 12;
-        }
-        while ($month < 1) {
-            $year -= 1;
-            $month += 12;
-        }
         if (mutate) {
             this.$year = $year;
             this.$month = $month;

package/dist-esm/datetime/localTime.js

@@ -36,6 +36,12 @@ export class LocalTime {
         }
         return t;
     }
+    /**
+     * Create LocalTime from unixTimestamp in milliseconds (not in seconds).
+     */
+    static ofMillis(millis) {
+        return LocalTime.of(new Date(millis));
+    }
     /**
      * Returns null if invalid
      */
@@ -173,15 +179,11 @@ export class LocalTime {
         return v === undefined ? this.get('second') : this.set('second', v);
     }
     setComponents(c, mutate = false) {
+        var _a;
         const d = mutate ? this.$date : new Date(this.$date);
-        if (c.year) {
-            d.setFullYear(c.year);
-        }
-        if (c.month) {
-            d.setMonth(c.month - 1);
-        }
-        if (c.day) {
-            d.setDate(c.day);
+        // Year, month and day set all-at-once, to avoid 30/31 (and 28/29) mishap
+        if (c.day || c.month !== undefined || c.year !== undefined) {
+            d.setFullYear((_a = c.year) !== null && _a !== void 0 ? _a : d.getFullYear(), c.month ? c.month - 1 : d.getMonth(), c.day || d.getDate());
         }
         if (c.hour !== undefined) {
             d.setHours(c.hour);
@@ -199,6 +201,10 @@ export class LocalTime {
             num *= 7;
             unit = 'day';
         }
+        if (unit === 'year' || unit === 'month') {
+            const d = addMonths(this.$date, unit === 'month' ? num : num * 12, mutate);
+            return mutate ? this : LocalTime.of(d);
+        }
         return this.set(unit, this.get(unit) + num, mutate);
     }
     subtract(num, unit, mutate = false) {
@@ -212,33 +218,14 @@ export class LocalTime {
         const secDiff = (this.$date.valueOf() - date2.valueOf()) / 1000;
         if (!secDiff)
             return 0;
-        if (unit === 'year' || unit === 'month') {
-            const sign = secDiff > 0 ? 1 : -1;
-            // Put items in descending order: "big minus small"
-            const [big, small] = sign === 1 ? [this.$date, date2] : [date2, this.$date];
-            if (unit === 'year') {
-                let years = big.getFullYear() - small.getFullYear();
-                const big2 = new Date(big);
-                const small2 = new Date(small);
-                big2.setFullYear(1584);
-                small2.setFullYear(1584);
-                if (big2 < small2)
-                    years--;
-                return years * sign || 0;
-            }
-            if (unit === 'month') {
-                let months = (big.getFullYear() - small.getFullYear()) * 12 + big.getMonth() - small.getMonth();
-                const big2 = new Date(big);
-                const small2 = new Date(small);
-                big2.setFullYear(1584, 0);
-                small2.setFullYear(1584, 0);
-                if (big2 < small2)
-                    months--;
-                return months * sign || 0;
-            }
-        }
         let r;
-        if (unit === 'day') {
+        if (unit === 'year') {
+            r = differenceInMonths(this.getDate(), date2) / 12;
+        }
+        else if (unit === 'month') {
+            r = differenceInMonths(this.getDate(), date2);
+        }
+        else if (unit === 'day') {
             r = secDiff / SECONDS_IN_DAY;
         }
         else if (unit === 'week') {
@@ -483,7 +470,7 @@ export class LocalTime {
         ].join('');
     }
     toString() {
-        return String(this.unix());
+        return this.toISODateTime();
     }
     toJSON() {
         return this.unix();
@@ -538,29 +525,6 @@ function getWeekYear(date) {
         return year - 1;
     }
 }
-// function setWeekYear(
-//   date: Date,
-//   year: number,
-// ): Date {
-//   const diff = differenceInCalendarDays(date, startOfWeekYear(date))
-//   const fourthOfJanuary = new Date(0)
-//   fourthOfJanuary.setFullYear(year, 0, 4)
-//   fourthOfJanuary.setHours(0, 0, 0, 0)
-//   date = startOfWeekYear(fourthOfJanuary)
-//   date.setDate(date.getDate() + diff)
-//   return date
-// }
-// function differenceInCalendarDays(
-//   dateLeft: Date,
-//   dateRight: Date,
-// ): number {
-//   return Math.round((startOfDay(dateLeft).getTime() - startOfDay(dateRight).getTime()) / MILLISECONDS_IN_DAY)
-// }
-// function startOfDay(date: Date, mutate = false): Date {
-//   const d = mutate ? date : new Date(date)
-//   d.setHours(0, 0, 0, 0)
-//   return d
-// }
 // based on: https://github.com/date-fns/date-fns/blob/fd6bb1a0bab143f2da068c05a9c562b9bee1357d/src/startOfWeek/index.ts
 function startOfWeek(date, mutate = false) {
     const d = mutate ? date : new Date(date);
@@ -578,3 +542,36 @@ function endOfWeek(date, mutate = false) {
     d.setDate(d.getDate() + diff);
     return d;
 }
+function addMonths(d, num, mutate = false) {
+    if (!mutate)
+        d = new Date(d);
+    let day = d.getDate();
+    let month = d.getMonth() + 1 + num;
+    if (day < 29) {
+        d.setMonth(month - 1);
+        return d;
+    }
+    let year = d.getFullYear();
+    while (month > 12) {
+        year++;
+        month -= 12;
+    }
+    while (month < 1) {
+        year--;
+        month += 12;
+    }
+    const monthLen = LocalDate.getMonthLength(year, month);
+    if (day > monthLen)
+        day = monthLen;
+    d.setFullYear(year, month - 1, day);
+    return d;
+}
+function differenceInMonths(a, b) {
+    if (a.getDate() < b.getDate())
+        return -differenceInMonths(b, a);
+    const wholeMonthDiff = (b.getFullYear() - a.getFullYear()) * 12 + (b.getMonth() - a.getMonth());
+    const anchor = addMonths(a, wholeMonthDiff).getTime();
+    const sign = b.getTime() - anchor >= 0 ? 1 : -1;
+    const anchor2 = addMonths(a, wholeMonthDiff + sign).getTime();
+    return -(wholeMonthDiff + ((b.getTime() - anchor) / (anchor2 - anchor)) * sign);
+}

package/package.json

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

package/src/datetime/localDate.ts

@@ -1,5 +1,10 @@
 import { _assert } from '../error/assert'
-import { IsoDateString, IsoDateTimeString, UnixTimestampNumber } from '../types'
+import {
+  IsoDateString,
+  IsoDateTimeString,
+  UnixTimestampMillisNumber,
+  UnixTimestampNumber,
+} from '../types'
 import { LocalTime } from './localTime'
 
 export type LocalDateUnit = LocalDateUnitStrict | 'week'
@@ -269,7 +274,15 @@ export class LocalDate {
     if (unit === 'year') {
       let years = big.$year - small.$year
 
-      if (big.$month < small.$month || (big.$month === small.$month && big.$day < small.$day)) {
+      if (
+        big.$month < small.$month ||
+        (big.$month === small.$month &&
+          big.$day < small.$day &&
+          !(
+            big.$day === LocalDate.getMonthLength(big.$year, big.$month) &&
+            small.$day === LocalDate.getMonthLength(small.$year, small.$month)
+          ))
+      ) {
         years--
       }
 
@@ -278,7 +291,12 @@ export class LocalDate {
 
     if (unit === 'month') {
       let months = (big.$year - small.$year) * 12 + (big.$month - small.$month)
-      if (big.$day < small.$day) months--
+      if (big.$day < small.$day) {
+        const bigMonthLen = LocalDate.getMonthLength(big.$year, big.$month)
+        if (big.$day !== bigMonthLen || small.$day < bigMonthLen) {
+          months--
+        }
+      }
       return months * sign || 0
     }
 
@@ -324,21 +342,37 @@ export class LocalDate {
       $year += num
     }
 
+    // check month overflow
+    while ($month > 12) {
+      $year += 1
+      $month -= 12
+    }
+    while ($month < 1) {
+      $year -= 1
+      $month += 12
+    }
+
     // check day overflow
-    if (unit === 'day') {
-      if ($day < 1) {
-        while ($day < 1) {
-          $month -= 1
-          if ($month < 1) {
-            $year -= 1
-            $month += 12
-          }
+    // Applies not only for 'day' unit, but also e.g 2022-05-31 plus 1 month should be 2022-06-30 (not 31!)
+    if ($day < 1) {
+      while ($day < 1) {
+        $month -= 1
+        if ($month < 1) {
+          $year -= 1
+          $month += 12
+        }
 
-          $day += LocalDate.getMonthLength($year, $month)
+        $day += LocalDate.getMonthLength($year, $month)
+      }
+    } else {
+      let monLen = LocalDate.getMonthLength($year, $month)
+
+      if (unit !== 'day') {
+        if ($day > monLen) {
+          // Case of 2022-05-31 plus 1 month should be 2022-06-30, not 31
+          $day = monLen
         }
       } else {
-        let monLen = LocalDate.getMonthLength($year, $month)
-
         while ($day > monLen) {
           $day -= monLen
           $month += 1
@@ -352,16 +386,6 @@ export class LocalDate {
       }
     }
 
-    // check month overflow
-    while ($month > 12) {
-      $year += 1
-      $month -= 12
-    }
-    while ($month < 1) {
-      $year -= 1
-      $month += 12
-    }
-
     if (mutate) {
       this.$year = $year
       this.$month = $month
@@ -458,7 +482,7 @@ export class LocalDate {
     return Math.floor(this.toDate().valueOf() / 1000)
   }
 
-  unixMillis(): number {
+  unixMillis(): UnixTimestampMillisNumber {
     return this.toDate().valueOf()
   }
 

package/src/datetime/localTime.ts

@@ -1,6 +1,11 @@
 import { _assert } from '../error/assert'
 import { _ms } from '../time/time.util'
-import { IsoDateString, IsoDateTimeString, UnixTimestampNumber } from '../types'
+import {
+  IsoDateString,
+  IsoDateTimeString,
+  UnixTimestampMillisNumber,
+  UnixTimestampNumber,
+} from '../types'
 import { Inclusiveness, LocalDate } from './localDate'
 
 export type LocalTimeUnit = 'year' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second'
@@ -56,6 +61,13 @@ export class LocalTime {
     return t
   }
 
+  /**
+   * Create LocalTime from unixTimestamp in milliseconds (not in seconds).
+   */
+  static ofMillis(millis: UnixTimestampMillisNumber): LocalTime {
+    return LocalTime.of(new Date(millis))
+  }
+
   /**
    * Returns null if invalid
    */
@@ -229,15 +241,15 @@ export class LocalTime {
   setComponents(c: Partial<LocalTimeComponents>, mutate = false): LocalTime {
     const d = mutate ? this.$date : new Date(this.$date)
 
-    if (c.year) {
-      d.setFullYear(c.year)
-    }
-    if (c.month) {
-      d.setMonth(c.month - 1)
-    }
-    if (c.day) {
-      d.setDate(c.day)
+    // Year, month and day set all-at-once, to avoid 30/31 (and 28/29) mishap
+    if (c.day || c.month !== undefined || c.year !== undefined) {
+      d.setFullYear(
+        c.year ?? d.getFullYear(),
+        c.month ? c.month - 1 : d.getMonth(),
+        c.day || d.getDate(),
+      )
     }
+
     if (c.hour !== undefined) {
       d.setHours(c.hour)
     }
@@ -256,6 +268,12 @@ export class LocalTime {
       num *= 7
       unit = 'day'
     }
+
+    if (unit === 'year' || unit === 'month') {
+      const d = addMonths(this.$date, unit === 'month' ? num : num * 12, mutate)
+      return mutate ? this : LocalTime.of(d)
+    }
+
     return this.set(unit, this.get(unit) + num, mutate)
   }
 
@@ -273,37 +291,13 @@ export class LocalTime {
     const secDiff = (this.$date.valueOf() - date2.valueOf()) / 1000
     if (!secDiff) return 0
 
-    if (unit === 'year' || unit === 'month') {
-      const sign = secDiff > 0 ? 1 : -1
-
-      // Put items in descending order: "big minus small"
-      const [big, small] = sign === 1 ? [this.$date, date2] : [date2, this.$date]
-
-      if (unit === 'year') {
-        let years = big.getFullYear() - small.getFullYear()
-        const big2 = new Date(big)
-        const small2 = new Date(small)
-        big2.setFullYear(1584)
-        small2.setFullYear(1584)
-        if (big2 < small2) years--
-        return years * sign || 0
-      }
-
-      if (unit === 'month') {
-        let months =
-          (big.getFullYear() - small.getFullYear()) * 12 + big.getMonth() - small.getMonth()
-        const big2 = new Date(big)
-        const small2 = new Date(small)
-        big2.setFullYear(1584, 0)
-        small2.setFullYear(1584, 0)
-        if (big2 < small2) months--
-        return months * sign || 0
-      }
-    }
-
     let r
 
-    if (unit === 'day') {
+    if (unit === 'year') {
+      r = differenceInMonths(this.getDate(), date2) / 12
+    } else if (unit === 'month') {
+      r = differenceInMonths(this.getDate(), date2)
+    } else if (unit === 'day') {
       r = secDiff / SECONDS_IN_DAY
     } else if (unit === 'week') {
       r = secDiff / (7 * 24 * 60 * 60)
@@ -489,7 +483,7 @@ export class LocalTime {
     return Math.floor(this.$date.valueOf() / 1000)
   }
 
-  unixMillis(): number {
+  unixMillis(): UnixTimestampMillisNumber {
     return this.$date.valueOf()
   }
 
@@ -587,7 +581,7 @@ export class LocalTime {
   }
 
   toString(): string {
-    return String(this.unix())
+    return this.toISODateTime()
   }
 
   toJSON(): UnixTimestampNumber {
@@ -651,32 +645,6 @@ function getWeekYear(date: Date): number {
   }
 }
 
-// function setWeekYear(
-//   date: Date,
-//   year: number,
-// ): Date {
-//   const diff = differenceInCalendarDays(date, startOfWeekYear(date))
-//   const fourthOfJanuary = new Date(0)
-//   fourthOfJanuary.setFullYear(year, 0, 4)
-//   fourthOfJanuary.setHours(0, 0, 0, 0)
-//   date = startOfWeekYear(fourthOfJanuary)
-//   date.setDate(date.getDate() + diff)
-//   return date
-// }
-
-// function differenceInCalendarDays(
-//   dateLeft: Date,
-//   dateRight: Date,
-// ): number {
-//   return Math.round((startOfDay(dateLeft).getTime() - startOfDay(dateRight).getTime()) / MILLISECONDS_IN_DAY)
-// }
-
-// function startOfDay(date: Date, mutate = false): Date {
-//   const d = mutate ? date : new Date(date)
-//   d.setHours(0, 0, 0, 0)
-//   return d
-// }
-
 // based on: https://github.com/date-fns/date-fns/blob/fd6bb1a0bab143f2da068c05a9c562b9bee1357d/src/startOfWeek/index.ts
 function startOfWeek(date: Date, mutate = false): Date {
   const d = mutate ? date : new Date(date)
@@ -699,3 +667,41 @@ function endOfWeek(date: Date, mutate = false): Date {
   d.setDate(d.getDate() + diff)
   return d
 }
+
+function addMonths(d: Date, num: number, mutate = false): Date {
+  if (!mutate) d = new Date(d)
+
+  let day = d.getDate()
+  let month = d.getMonth() + 1 + num
+
+  if (day < 29) {
+    d.setMonth(month - 1)
+    return d
+  }
+
+  let year = d.getFullYear()
+
+  while (month > 12) {
+    year++
+    month -= 12
+  }
+  while (month < 1) {
+    year--
+    month += 12
+  }
+
+  const monthLen = LocalDate.getMonthLength(year, month)
+  if (day > monthLen) day = monthLen
+
+  d.setFullYear(year, month - 1, day)
+  return d
+}
+
+function differenceInMonths(a: Date, b: Date): number {
+  if (a.getDate() < b.getDate()) return -differenceInMonths(b, a)
+  const wholeMonthDiff = (b.getFullYear() - a.getFullYear()) * 12 + (b.getMonth() - a.getMonth())
+  const anchor = addMonths(a, wholeMonthDiff).getTime()
+  const sign = b.getTime() - anchor >= 0 ? 1 : -1
+  const anchor2 = addMonths(a, wholeMonthDiff + sign).getTime()
+  return -(wholeMonthDiff + ((b.getTime() - anchor) / (anchor2 - anchor)) * sign)
+}

package/src/index.ts

@@ -120,6 +120,7 @@ import {
   SavedDBEntity,
   StringMap,
   UnixTimestampNumber,
+  UnixTimestampMillisNumber,
   UnixTimestamp,
   Integer,
   ValueOf,
@@ -243,6 +244,7 @@ export type {
   ConditionalExcept,
   Class,
   UnixTimestampNumber,
+  UnixTimestampMillisNumber,
   UnixTimestamp,
   Integer,
   BaseDBEntity,

package/src/types.ts

@@ -213,6 +213,13 @@ export type IsoDateTimeString = string
  */
 export type UnixTimestampNumber = number
 
+/**
+ * Interface explicitly states that the value is a "Unix timestamp in **milleseconds**" (not seconds)
+ *
+ * @example 1628945450000
+ */
+export type UnixTimestampMillisNumber = number
+
 /**
  * @deprecated use UnixTimestampNumber
  */