@naturalcycles/js-lib 14.230.0 → 14.231.0

package/dist/datetime/localDate.d.ts

@@ -113,12 +113,21 @@ export declare class LocalDate {
      * Timezone will match local timezone.
      */
     toDate(): Date;
+    /**
+     * Converts LocalDate to Date in UTC timezone.
+     * Unlike normal `.toDate` that uses browser's timezone by default.
+     */
+    toDateInUTC(): Date;
     toLocalTime(): LocalTime;
     toISODate(): IsoDateString;
     /**
      * Returns e.g: `1984-06-21T17:56:21`
      */
     toISODateTime(): IsoDateTimeString;
+    /**
+     * Returns e.g: `1984-06-21T17:56:21Z` (notice the Z at the end, which indicates UTC)
+     */
+    toISODateTimeUTC(): IsoDateTimeString;
     toString(): IsoDateString;
     toStringCompact(): string;
     toMonthId(): MonthId;
@@ -153,4 +162,4 @@ export declare function localDateOrToday(d?: LocalDateInput | null): LocalDate;
 /**
  Convenience function to return current today's IsoDateString representation, e.g `2024-06-21`
  */
-export declare function todayIsoDateString(): IsoDateString;
+export declare function todayString(): IsoDateString;

package/dist/datetime/localDate.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.todayIsoDateString = exports.localDateOrToday = exports.localDateOrUndefined = exports.localDateToday = exports.localDate = exports.localDateRangeIterable = exports.localDateRange = exports.LocalDate = void 0;
+exports.todayString = exports.localDateOrToday = exports.localDateOrUndefined = exports.localDateToday = exports.localDate = exports.localDateRangeIterable = exports.localDateRange = exports.LocalDate = void 0;
 const assert_1 = require("../error/assert");
 const iterable2_1 = require("../iter/iterable2");
 const localTime_1 = require("./localTime");
@@ -51,7 +51,6 @@ class LocalDate {
         if (d instanceof Date) {
             return this.fromDate(d);
         }
-        // const [year, month, day] = d.slice(0, 10).split('-').map(Number)
         const matches = typeof d === 'string' && DATE_REGEX.exec(d.slice(0, 10));
         if (!matches)
             return null;
@@ -69,10 +68,6 @@ class LocalDate {
         }
         return new LocalDate(year, month, day);
     }
-    // Can use just .toString()
-    // static parseToString(d: LocalDateConfig): IsoDateString {
-    //   return typeof d === 'string' ? d : d.toString()
-    // }
     static isValid(iso) {
         return this.parseOrNull(iso) !== null;
     }
@@ -391,6 +386,13 @@ class LocalDate {
     toDate() {
         return new Date(this.$year, this.$month - 1, this.$day);
     }
+    /**
+     * Converts LocalDate to Date in UTC timezone.
+     * Unlike normal `.toDate` that uses browser's timezone by default.
+     */
+    toDateInUTC() {
+        return new Date(this.toISODateTimeUTC());
+    }
     toLocalTime() {
         return localTime_1.LocalTime.of(this.toDate());
     }
@@ -403,6 +405,12 @@ class LocalDate {
     toISODateTime() {
         return this.toString() + 'T00:00:00';
     }
+    /**
+     * Returns e.g: `1984-06-21T17:56:21Z` (notice the Z at the end, which indicates UTC)
+     */
+    toISODateTimeUTC() {
+        return this.toISODateTime() + 'Z';
+    }
     toString() {
         return [
             String(this.$year).padStart(4, '0'),
@@ -506,8 +514,10 @@ exports.localDateOrToday = localDateOrToday;
 /**
  Convenience function to return current today's IsoDateString representation, e.g `2024-06-21`
  */
-function todayIsoDateString() {
+function todayString() {
     // It was benchmarked to be faster than by concatenating individual Date components
-    return new Date().toISOString().slice(0, 10);
+    // return new Date().toISOString().slice(0, 10)
+    // But, toISOString always returns the date in UTC, so in the Browser it would give unexpected result!
+    return LocalDate.fromDate(new Date()).toString();
 }
-exports.todayIsoDateString = todayIsoDateString;
+exports.todayString = todayString;

package/dist/datetime/localTime.d.ts

@@ -12,10 +12,13 @@ export declare enum ISODayOfWeek {
 }
 export type LocalTimeInput = LocalTime | Date | IsoDateTimeString | UnixTimestampNumber;
 export type LocalTimeFormatter = (ld: LocalTime) => string;
-export interface LocalTimeComponents {
+export type LocalTimeComponents = DateComponents & TimeComponents;
+interface DateComponents {
     year: number;
     month: number;
     day: number;
+}
+interface TimeComponents {
     hour: number;
     minute: number;
     second: number;
@@ -47,6 +50,7 @@ export declare class LocalTime {
         year: number;
         month: number;
     } & Partial<LocalTimeComponents>): LocalTime;
+    static fromDateUTC(d: Date): LocalTime;
     get(unit: LocalTimeUnit): number;
     set(unit: LocalTimeUnit, v: number, mutate?: boolean): LocalTime;
     year(): number;
@@ -126,6 +130,8 @@ export declare class LocalTime {
      */
     cmp(d: LocalTimeInput): -1 | 0 | 1;
     components(): LocalTimeComponents;
+    private dateComponents;
+    private timeComponents;
     fromNow(now?: LocalTimeInput): string;
     getDate(): Date;
     clone(): LocalTime;
@@ -133,6 +139,11 @@ export declare class LocalTime {
     unixMillis(): UnixTimestampMillisNumber;
     valueOf(): UnixTimestampNumber;
     toLocalDate(): LocalDate;
+    /**
+     * Returns e.g: `1984-06-21 17:56:21`
+     * or (if seconds=false):
+     * `1984-06-21 17:56`
+     */
     toPretty(seconds?: boolean): IsoDateTimeString;
     /**
      * Returns e.g: `1984-06-21T17:56:21`
@@ -196,3 +207,4 @@ export declare function getUTCOffsetMinutes(): NumberOfMinutes;
  * Instead of -0 it returns 0, for the peace of mind and less weird test/snapshot differences.
  */
 export declare function getUTCOffsetHours(): NumberOfHours;
+export {};

package/dist/datetime/localTime.js

@@ -64,7 +64,12 @@ class LocalTime {
             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())) {
@@ -107,6 +112,9 @@ class LocalTime {
     static fromComponents(c) {
         return new LocalTime(new Date(c.year, c.month - 1, c.day || 1, c.hour || 0, c.minute || 0, c.second || 0));
     }
+    static fromDateUTC(d) {
+        return new LocalTime(new Date(d.toISOString()));
+    }
     get(unit) {
         if (unit === 'year') {
             return this.$date.getFullYear();
@@ -422,6 +430,20 @@ class LocalTime {
             second: this.$date.getSeconds(),
         };
     }
+    dateComponents() {
+        return {
+            year: this.$date.getFullYear(),
+            month: this.$date.getMonth() + 1,
+            day: this.$date.getDate(),
+        };
+    }
+    timeComponents() {
+        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();
         if (msDiff === 0)
@@ -449,27 +471,52 @@ class LocalTime {
     toLocalDate() {
         return localDate_1.LocalDate.fromDate(this.$date);
     }
+    /**
+     * Returns e.g: `1984-06-21 17:56:21`
+     * or (if seconds=false):
+     * `1984-06-21 17:56`
+     */
     toPretty(seconds = true) {
-        const s = this.$date.toISOString();
-        return s.slice(0, 10) + ' ' + s.slice(11, seconds ? 19 : 16);
+        return this.toISODate() + ' ' + this.toISOTime(seconds);
+        // !! Not using toISOString(), as it returns time in UTC, not in local timezone (unexpected!)
+        // const s = this.$date.toISOString()
+        // return s.slice(0, 10) + ' ' + s.slice(11, seconds ? 19 : 16)
     }
     /**
      * Returns e.g: `1984-06-21T17:56:21`
      */
     toISODateTime() {
-        return this.$date.toISOString().slice(0, 19);
+        return this.toISODate() + 'T' + this.toISOTime();
+        // !! Not using toISOString(), as it returns time in UTC, not in local timezone (unexpected!)
+        // return this.$date.toISOString().slice(0, 19)
     }
     /**
      * 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.dateComponents();
+        return [
+            String(year).padStart(4, '0'),
+            String(month).padStart(2, '0'),
+            String(day).padStart(2, '0'),
+        ].join('-');
+        // !! Not using toISOString(), as it returns time in UTC, not in local timezone (unexpected!)
+        // 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.timeComponents();
+        return [
+            String(hour).padStart(2, '0'),
+            String(minute).padStart(2, '0'),
+            seconds && String(second).padStart(2, '0'),
+        ]
+            .filter(Boolean)
+            .join(':');
+        // !! Not using toISOString(), as it returns time in UTC, not in local timezone (unexpected!)
+        // return this.$date.toISOString().slice(11, seconds ? 19 : 16)
     }
     /**
      * Returns e.g: `19840621_1705`
@@ -493,7 +540,7 @@ class LocalTime {
         return this.unix();
     }
     toMonthId() {
-        return this.$date.toISOString().slice(0, 7);
+        return this.toISODate().slice(0, 7);
     }
     format(fmt) {
         if (fmt instanceof Intl.DateTimeFormat) {

package/dist-esm/datetime/localDate.js

@@ -48,7 +48,6 @@ export class LocalDate {
         if (d instanceof Date) {
             return this.fromDate(d);
         }
-        // const [year, month, day] = d.slice(0, 10).split('-').map(Number)
         const matches = typeof d === 'string' && DATE_REGEX.exec(d.slice(0, 10));
         if (!matches)
             return null;
@@ -66,10 +65,6 @@ export class LocalDate {
         }
         return new LocalDate(year, month, day);
     }
-    // Can use just .toString()
-    // static parseToString(d: LocalDateConfig): IsoDateString {
-    //   return typeof d === 'string' ? d : d.toString()
-    // }
     static isValid(iso) {
         return this.parseOrNull(iso) !== null;
     }
@@ -388,6 +383,13 @@ export class LocalDate {
     toDate() {
         return new Date(this.$year, this.$month - 1, this.$day);
     }
+    /**
+     * Converts LocalDate to Date in UTC timezone.
+     * Unlike normal `.toDate` that uses browser's timezone by default.
+     */
+    toDateInUTC() {
+        return new Date(this.toISODateTimeUTC());
+    }
     toLocalTime() {
         return LocalTime.of(this.toDate());
     }
@@ -400,6 +402,12 @@ export class LocalDate {
     toISODateTime() {
         return this.toString() + 'T00:00:00';
     }
+    /**
+     * Returns e.g: `1984-06-21T17:56:21Z` (notice the Z at the end, which indicates UTC)
+     */
+    toISODateTimeUTC() {
+        return this.toISODateTime() + 'Z';
+    }
     toString() {
         return [
             String(this.$year).padStart(4, '0'),
@@ -496,7 +504,9 @@ export function localDateOrToday(d) {
 /**
  Convenience function to return current today's IsoDateString representation, e.g `2024-06-21`
  */
-export function todayIsoDateString() {
+export function todayString() {
     // It was benchmarked to be faster than by concatenating individual Date components
-    return new Date().toISOString().slice(0, 10);
+    // return new Date().toISOString().slice(0, 10)
+    // But, toISOString always returns the date in UTC, so in the Browser it would give unexpected result!
+    return LocalDate.fromDate(new Date()).toString();
 }

package/dist-esm/datetime/localTime.js

@@ -61,7 +61,12 @@ export class LocalTime {
             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())) {
@@ -104,6 +109,9 @@ export class LocalTime {
     static fromComponents(c) {
         return new LocalTime(new Date(c.year, c.month - 1, c.day || 1, c.hour || 0, c.minute || 0, c.second || 0));
     }
+    static fromDateUTC(d) {
+        return new LocalTime(new Date(d.toISOString()));
+    }
     get(unit) {
         if (unit === 'year') {
             return this.$date.getFullYear();
@@ -420,6 +428,20 @@ export class LocalTime {
             second: this.$date.getSeconds(),
         };
     }
+    dateComponents() {
+        return {
+            year: this.$date.getFullYear(),
+            month: this.$date.getMonth() + 1,
+            day: this.$date.getDate(),
+        };
+    }
+    timeComponents() {
+        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();
         if (msDiff === 0)
@@ -447,27 +469,52 @@ export class LocalTime {
     toLocalDate() {
         return LocalDate.fromDate(this.$date);
     }
+    /**
+     * Returns e.g: `1984-06-21 17:56:21`
+     * or (if seconds=false):
+     * `1984-06-21 17:56`
+     */
     toPretty(seconds = true) {
-        const s = this.$date.toISOString();
-        return s.slice(0, 10) + ' ' + s.slice(11, seconds ? 19 : 16);
+        return this.toISODate() + ' ' + this.toISOTime(seconds);
+        // !! Not using toISOString(), as it returns time in UTC, not in local timezone (unexpected!)
+        // const s = this.$date.toISOString()
+        // return s.slice(0, 10) + ' ' + s.slice(11, seconds ? 19 : 16)
     }
     /**
      * Returns e.g: `1984-06-21T17:56:21`
      */
     toISODateTime() {
-        return this.$date.toISOString().slice(0, 19);
+        return this.toISODate() + 'T' + this.toISOTime();
+        // !! Not using toISOString(), as it returns time in UTC, not in local timezone (unexpected!)
+        // return this.$date.toISOString().slice(0, 19)
     }
     /**
      * 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.dateComponents();
+        return [
+            String(year).padStart(4, '0'),
+            String(month).padStart(2, '0'),
+            String(day).padStart(2, '0'),
+        ].join('-');
+        // !! Not using toISOString(), as it returns time in UTC, not in local timezone (unexpected!)
+        // 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.timeComponents();
+        return [
+            String(hour).padStart(2, '0'),
+            String(minute).padStart(2, '0'),
+            seconds && String(second).padStart(2, '0'),
+        ]
+            .filter(Boolean)
+            .join(':');
+        // !! Not using toISOString(), as it returns time in UTC, not in local timezone (unexpected!)
+        // return this.$date.toISOString().slice(11, seconds ? 19 : 16)
     }
     /**
      * Returns e.g: `19840621_1705`
@@ -491,7 +538,7 @@ export class LocalTime {
         return this.unix();
     }
     toMonthId() {
-        return this.$date.toISOString().slice(0, 7);
+        return this.toISODate().slice(0, 7);
     }
     format(fmt) {
         if (fmt instanceof Intl.DateTimeFormat) {

package/package.json

@@ -1,9 +1,11 @@
 {
   "name": "@naturalcycles/js-lib",
-  "version": "14.230.0",
+  "version": "14.231.0",
   "scripts": {
     "prepare": "husky",
     "build-prod": "build-prod-esm-cjs",
+    "test-tz1": "TZ=Europe/Stockholm test local",
+    "test-tz2": "TZ=JST-9 test local",
     "docs-dev": "vitepress dev docs --open",
     "docs-build": "vitepress build docs",
     "docs-preview": "vitepress preview docs"

package/src/datetime/localDate.ts

@@ -74,7 +74,6 @@ export class LocalDate {
       return this.fromDate(d)
     }
 
-    // const [year, month, day] = d.slice(0, 10).split('-').map(Number)
     const matches = typeof (d as any) === 'string' && DATE_REGEX.exec(d.slice(0, 10))
     if (!matches) return null
 
@@ -97,11 +96,6 @@ export class LocalDate {
     return new LocalDate(year, month, day)
   }
 
-  // Can use just .toString()
-  // static parseToString(d: LocalDateConfig): IsoDateString {
-  //   return typeof d === 'string' ? d : d.toString()
-  // }
-
   static isValid(iso: string | undefined | null): boolean {
     return this.parseOrNull(iso) !== null
   }
@@ -473,6 +467,14 @@ export class LocalDate {
     return new Date(this.$year, this.$month - 1, this.$day)
   }
 
+  /**
+   * Converts LocalDate to Date in UTC timezone.
+   * Unlike normal `.toDate` that uses browser's timezone by default.
+   */
+  toDateInUTC(): Date {
+    return new Date(this.toISODateTimeUTC())
+  }
+
   toLocalTime(): LocalTime {
     return LocalTime.of(this.toDate())
   }
@@ -488,6 +490,13 @@ export class LocalDate {
     return this.toString() + 'T00:00:00'
   }
 
+  /**
+   * Returns e.g: `1984-06-21T17:56:21Z` (notice the Z at the end, which indicates UTC)
+   */
+  toISODateTimeUTC(): IsoDateTimeString {
+    return this.toISODateTime() + 'Z'
+  }
+
   toString(): IsoDateString {
     return [
       String(this.$year).padStart(4, '0'),
@@ -614,7 +623,9 @@ export function localDateOrToday(d?: LocalDateInput | null): LocalDate {
 /**
  Convenience function to return current today's IsoDateString representation, e.g `2024-06-21`
  */
-export function todayIsoDateString(): IsoDateString {
+export function todayString(): IsoDateString {
   // It was benchmarked to be faster than by concatenating individual Date components
-  return new Date().toISOString().slice(0, 10)
+  // return new Date().toISOString().slice(0, 10)
+  // But, toISOString always returns the date in UTC, so in the Browser it would give unexpected result!
+  return LocalDate.fromDate(new Date()).toString()
 }

package/src/datetime/localTime.ts

@@ -28,10 +28,15 @@ export enum ISODayOfWeek {
 export type LocalTimeInput = LocalTime | Date | IsoDateTimeString | UnixTimestampNumber
 export type LocalTimeFormatter = (ld: LocalTime) => string
 
-export interface LocalTimeComponents {
+export type LocalTimeComponents = DateComponents & TimeComponents
+
+interface DateComponents {
   year: number
   month: number
   day: number
+}
+
+interface TimeComponents {
   hour: number
   minute: number
   second: number
@@ -88,7 +93,12 @@ export class LocalTime {
       // unexpected type, e.g Function or something
       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
@@ -146,6 +156,10 @@ export class LocalTime {
     )
   }
 
+  static fromDateUTC(d: Date): LocalTime {
+    return new LocalTime(new Date(d.toISOString()))
+  }
+
   get(unit: LocalTimeUnit): number {
     if (unit === 'year') {
       return this.$date.getFullYear()
@@ -514,6 +528,22 @@ export class LocalTime {
     }
   }
 
+  private dateComponents(): DateComponents {
+    return {
+      year: this.$date.getFullYear(),
+      month: this.$date.getMonth() + 1,
+      day: this.$date.getDate(),
+    }
+  }
+
+  private timeComponents(): TimeComponents {
+    return {
+      hour: this.$date.getHours(),
+      minute: this.$date.getMinutes(),
+      second: this.$date.getSeconds(),
+    }
+  }
+
   fromNow(now: LocalTimeInput = new Date()): string {
     const msDiff = LocalTime.parseToDate(now).valueOf() - this.$date.valueOf()
 
@@ -550,30 +580,59 @@ export class LocalTime {
     return LocalDate.fromDate(this.$date)
   }
 
+  /**
+   * Returns e.g: `1984-06-21 17:56:21`
+   * or (if seconds=false):
+   * `1984-06-21 17:56`
+   */
   toPretty(seconds = true): IsoDateTimeString {
-    const s = this.$date.toISOString()
-    return s.slice(0, 10) + ' ' + s.slice(11, seconds ? 19 : 16)
+    return this.toISODate() + ' ' + this.toISOTime(seconds)
+    // !! Not using toISOString(), as it returns time in UTC, not in local timezone (unexpected!)
+    // const s = this.$date.toISOString()
+    // return s.slice(0, 10) + ' ' + s.slice(11, seconds ? 19 : 16)
   }
 
   /**
    * Returns e.g: `1984-06-21T17:56:21`
    */
   toISODateTime(): IsoDateTimeString {
-    return this.$date.toISOString().slice(0, 19)
+    return this.toISODate() + 'T' + this.toISOTime()
+    // !! Not using toISOString(), as it returns time in UTC, not in local timezone (unexpected!)
+    // return this.$date.toISOString().slice(0, 19)
   }
 
   /**
    * Returns e.g: `1984-06-21`, only the date part of DateTime
    */
   toISODate(): IsoDateString {
-    return this.$date.toISOString().slice(0, 10)
+    const { year, month, day } = this.dateComponents()
+
+    return [
+      String(year).padStart(4, '0'),
+      String(month).padStart(2, '0'),
+      String(day).padStart(2, '0'),
+    ].join('-')
+
+    // !! Not using toISOString(), as it returns time in UTC, not in local timezone (unexpected!)
+    // return this.$date.toISOString().slice(0, 10)
   }
 
   /**
    * Returns e.g: `17:03:15` (or `17:03` with seconds=false)
    */
   toISOTime(seconds = true): string {
-    return this.$date.toISOString().slice(11, seconds ? 19 : 16)
+    const { hour, minute, second } = this.timeComponents()
+
+    return [
+      String(hour).padStart(2, '0'),
+      String(minute).padStart(2, '0'),
+      seconds && String(second).padStart(2, '0'),
+    ]
+      .filter(Boolean)
+      .join(':')
+
+    // !! Not using toISOString(), as it returns time in UTC, not in local timezone (unexpected!)
+    // return this.$date.toISOString().slice(11, seconds ? 19 : 16)
   }
 
   /**
@@ -602,7 +661,7 @@ export class LocalTime {
   }
 
   toMonthId(): MonthId {
-    return this.$date.toISOString().slice(0, 7)
+    return this.toISODate().slice(0, 7)
   }
 
   format(fmt: Intl.DateTimeFormat | LocalTimeFormatter): string {