@naturalcycles/js-lib 14.236.0 → 14.237.0

package/dist/datetime/localDate.d.ts

@@ -1,6 +1,6 @@
 import { Iterable2 } from '../iter/iterable2';
 import type { Inclusiveness, IsoDateString, IsoDateTimeString, MonthId, SortDirection, UnixTimestampMillisNumber, UnixTimestampNumber } from '../types';
-import { ISODayOfWeek, LocalTime } from './localTime';
+import { DateObject, ISODayOfWeek, LocalTime } from './localTime';
 export type LocalDateUnit = LocalDateUnitStrict | 'week';
 export type LocalDateUnitStrict = 'year' | 'month' | 'day';
 export type LocalDateInput = LocalDate | Date | IsoDateString;
@@ -103,6 +103,7 @@ export declare class LocalDate {
      * Unlike normal `.toDate` that uses browser's timezone by default.
      */
     toDateInUTC(): Date;
+    toDateObject(): DateObject;
     /**
      * Converts LocalDate to LocalTime with 0 hours, 0 minutes, 0 seconds.
      * LocalTime's Date will be in local timezone.

package/dist/datetime/localDate.js

@@ -323,6 +323,13 @@ class LocalDate {
     toDateInUTC() {
         return new Date(this.toISODateTimeInUTC());
     }
+    toDateObject() {
+        return {
+            year: this.$year,
+            month: this.$month,
+            day: this.$day,
+        };
+    }
     /**
      * Converts LocalDate to LocalTime with 0 hours, 0 minutes, 0 seconds.
      * LocalTime's Date will be in local timezone.

package/dist/datetime/localTime.d.ts

@@ -1,5 +1,6 @@
 import type { Inclusiveness, IsoDateString, IsoDateTimeString, MonthId, NumberOfHours, NumberOfMinutes, SortDirection, UnixTimestampMillisNumber, UnixTimestampNumber } from '../types';
 import { LocalDate } from './localDate';
+import { WallTime } from './wallTime';
 export type LocalTimeUnit = 'year' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second';
 export declare enum ISODayOfWeek {
     MONDAY = 1,
@@ -12,13 +13,13 @@ export declare enum ISODayOfWeek {
 }
 export type LocalTimeInput = LocalTime | Date | IsoDateTimeString | UnixTimestampNumber;
 export type LocalTimeFormatter = (ld: LocalTime) => string;
-export type LocalTimeComponents = DateComponents & TimeComponents;
-interface DateComponents {
+export type DateTimeObject = DateObject & TimeObject;
+export interface DateObject {
     year: number;
     month: number;
     day: number;
 }
-interface TimeComponents {
+export interface TimeObject {
     hour: number;
     minute: number;
     second: number;
@@ -36,6 +37,51 @@ export declare class LocalTime {
      * Opposite of `.utc()` method.
      */
     local(): 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.
+     * See this ("common errors"): https://stackoverflow.com/a/15171030/4919972
+     * Fake also means that unixTimestamp of that new LocalDate is not the same.
+     * For that reason we return WallTime, and not a LocalTime.
+     * WallTime can be pretty-printed as Date-only, Time-only or DateAndTime.
+     *
+     * E.g `inTimezone('America/New_York').toISOTime()`
+     *
+     * https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+     *
+     * @experimental
+     */
+    inTimezone(tz: string): WallTime;
+    /**
+     * UTC offset is the opposite of "timezone offset" - it's the number of minutes to add
+     * to the local time to get UTC time.
+     *
+     * E.g utcOffset for CEST is -120,
+     * which means that you need to add -120 minutes to the local time to get UTC time.
+     *
+     * Instead of -0 it returns 0, for the peace of mind and less weird test/snapshot differences.
+     *
+     * If timezone (tz) is specified, e.g `America/New_York`,
+     * it will return the UTC offset for that timezone.
+     *
+     * https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+     */
+    getUTCOffsetMinutes(tz?: string): NumberOfMinutes;
+    /**
+     * Same as getUTCOffsetMinutes, but rounded to hours.
+     *
+     * E.g for CEST it is -2.
+     *
+     * Instead of -0 it returns 0, for the peace of mind and less weird test/snapshot differences.
+     *
+     * If timezone (tz) is specified, e.g `America/New_York`,
+     * it will return the UTC offset for that timezone.
+     */
+    getUTCOffsetHours(tz?: string): NumberOfHours;
+    /**
+     * Returns e.g `-05:00` for New_York winter time.
+     */
+    getUTCOffsetString(tz: string): string;
     get(unit: LocalTimeUnit): number;
     set(unit: LocalTimeUnit, v: number, mutate?: boolean): LocalTime;
     year(): number;
@@ -57,7 +103,7 @@ export declare class LocalTime {
     minute(v: number): LocalTime;
     second(): number;
     second(v: number): LocalTime;
-    setComponents(c: Partial<LocalTimeComponents>, mutate?: boolean): LocalTime;
+    setComponents(c: Partial<DateTimeObject>, mutate?: boolean): LocalTime;
     plusSeconds(num: number): LocalTime;
     plusMinutes(num: number): LocalTime;
     plusHours(num: number): LocalTime;
@@ -123,9 +169,9 @@ export declare class LocalTime {
      * returns -1 if this < d
      */
     cmp(d: LocalTimeInput): -1 | 0 | 1;
-    components(): LocalTimeComponents;
-    private dateComponents;
-    private timeComponents;
+    getDateTimeObject(): DateTimeObject;
+    getDateObject(): DateObject;
+    getTimeObject(): TimeObject;
     fromNow(now?: LocalTimeInput): string;
     getDate(): Date;
     clone(): LocalTime;
@@ -177,6 +223,19 @@ declare class LocalTimeFactory {
     parseToDate(d: LocalTimeInput): Date;
     parseToUnixTimestamp(d: LocalTimeInput): UnixTimestampNumber;
     isValid(d: LocalTimeInput | undefined | null): boolean;
+    /**
+     * Returns the IANA timezone e.g `Europe/Stockholm`.
+     * https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+     */
+    getTimezone(): string;
+    /**
+     * Returns true if passed IANA timezone is valid/supported.
+     * E.g `Europe/Stockholm` is valid, but `Europe/Stockholm2` is not.
+     *
+     * This implementation is not optimized for performance. If you need frequent validation -
+     * consider caching the Intl.supportedValuesOf values as Set and reuse that.
+     */
+    isTimezoneValid(tz: string): boolean;
     now(): LocalTime;
     /**
      * Creates a LocalTime from the input, unless it's falsy - then returns undefined.
@@ -191,7 +250,7 @@ declare class LocalTimeFactory {
     fromComponents(c: {
         year: number;
         month: number;
-    } & Partial<LocalTimeComponents>): LocalTime;
+    } & Partial<DateTimeObject>): LocalTime;
     sort(items: LocalTime[], dir?: SortDirection, mutate?: boolean): LocalTime[];
     minOrUndefined(items: LocalTimeInput[]): LocalTime | undefined;
     min(items: LocalTimeInput[]): LocalTime;
@@ -207,22 +266,4 @@ export declare const localTime: LocalTimeFn;
  Like Date.now(), but in seconds.
  */
 export declare function nowUnix(): UnixTimestampNumber;
-/**
- * UTC offset is the opposite of "timezone offset" - it's the number of minutes to add
- * to the local time to get UTC time.
- *
- * E.g utcOffset for CEST is -120,
- * which means that you need to add -120 minutes to the local time to get UTC time.
- *
- * Instead of -0 it returns 0, for the peace of mind and less weird test/snapshot differences.
- */
-export declare function getUTCOffsetMinutes(): NumberOfMinutes;
-/**
- * Same as getUTCOffsetMinutes, but rounded to hours.
- *
- * E.g for CEST it is -2.
- *
- * 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

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getUTCOffsetHours = exports.getUTCOffsetMinutes = exports.nowUnix = exports.localTime = exports.LocalTime = exports.ISODayOfWeek = void 0;
+exports.nowUnix = exports.localTime = exports.LocalTime = exports.ISODayOfWeek = void 0;
 const assert_1 = require("../error/assert");
 const time_util_1 = require("../time/time.util");
 const localDate_1 = require("./localDate");
+const wallTime_1 = require("./wallTime");
 var ISODayOfWeek;
 (function (ISODayOfWeek) {
     ISODayOfWeek[ISODayOfWeek["MONDAY"] = 1] = "MONDAY";
@@ -38,6 +39,78 @@ class LocalTime {
     local() {
         return new LocalTime(new Date(this.$date.getTime()));
     }
+    /**
+     * 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.
+     * See this ("common errors"): https://stackoverflow.com/a/15171030/4919972
+     * Fake also means that unixTimestamp of that new LocalDate is not the same.
+     * For that reason we return WallTime, and not a LocalTime.
+     * WallTime can be pretty-printed as Date-only, Time-only or DateAndTime.
+     *
+     * E.g `inTimezone('America/New_York').toISOTime()`
+     *
+     * https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+     *
+     * @experimental
+     */
+    inTimezone(tz) {
+        const d = new Date(this.$date.toLocaleString('en-US', { timeZone: tz }));
+        return new wallTime_1.WallTime({
+            year: d.getFullYear(),
+            month: d.getMonth() + 1,
+            day: d.getDate(),
+            hour: d.getHours(),
+            minute: d.getMinutes(),
+            second: d.getSeconds(),
+        });
+    }
+    /**
+     * UTC offset is the opposite of "timezone offset" - it's the number of minutes to add
+     * to the local time to get UTC time.
+     *
+     * E.g utcOffset for CEST is -120,
+     * which means that you need to add -120 minutes to the local time to get UTC time.
+     *
+     * Instead of -0 it returns 0, for the peace of mind and less weird test/snapshot differences.
+     *
+     * If timezone (tz) is specified, e.g `America/New_York`,
+     * it will return the UTC offset for that timezone.
+     *
+     * https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+     */
+    getUTCOffsetMinutes(tz) {
+        if (tz) {
+            // based on: https://stackoverflow.com/a/53652131/4919972
+            const nowTime = this.$date.getTime();
+            const tzTime = new Date(this.$date.toLocaleString('en-US', { timeZone: tz })).getTime();
+            return Math.round((tzTime - nowTime) / 60000) || 0;
+        }
+        return -this.$date.getTimezoneOffset() || 0;
+    }
+    /**
+     * Same as getUTCOffsetMinutes, but rounded to hours.
+     *
+     * E.g for CEST it is -2.
+     *
+     * Instead of -0 it returns 0, for the peace of mind and less weird test/snapshot differences.
+     *
+     * If timezone (tz) is specified, e.g `America/New_York`,
+     * it will return the UTC offset for that timezone.
+     */
+    getUTCOffsetHours(tz) {
+        return Math.round(this.getUTCOffsetMinutes(tz) / 60);
+    }
+    /**
+     * Returns e.g `-05:00` for New_York winter time.
+     */
+    getUTCOffsetString(tz) {
+        const minutes = this.getUTCOffsetMinutes(tz);
+        const hours = Math.trunc(minutes / 60);
+        const sign = hours < 0 ? '-' : '+';
+        const h = String(Math.abs(hours)).padStart(2, '0');
+        const m = String(minutes % 60).padStart(2, '0');
+        return `${sign}${h}:${m}`;
+    }
     get(unit) {
         if (unit === 'year') {
             return this.$date.getFullYear();
@@ -357,20 +430,20 @@ class LocalTime {
             return 0;
         return t1 < t2 ? -1 : 1;
     }
-    components() {
+    getDateTimeObject() {
         return {
-            ...this.dateComponents(),
-            ...this.timeComponents(),
+            ...this.getDateObject(),
+            ...this.getTimeObject(),
         };
     }
-    dateComponents() {
+    getDateObject() {
         return {
             year: this.$date.getFullYear(),
             month: this.$date.getMonth() + 1,
             day: this.$date.getDate(),
         };
     }
-    timeComponents() {
+    getTimeObject() {
         return {
             hour: this.$date.getHours(),
             minute: this.$date.getMinutes(),
@@ -427,7 +500,7 @@ class LocalTime {
      * Returns e.g: `1984-06-21`, only the date part of DateTime
      */
     toISODate() {
-        const { year, month, day } = this.dateComponents();
+        const { year, month, day } = this.getDateObject();
         return [
             String(year).padStart(4, '0'),
             String(month).padStart(2, '0'),
@@ -440,7 +513,7 @@ class LocalTime {
      * Returns e.g: `17:03:15` (or `17:03` with seconds=false)
      */
     toISOTime(seconds = true) {
-        const { hour, minute, second } = this.timeComponents();
+        const { hour, minute, second } = this.getTimeObject();
         return [
             String(hour).padStart(2, '0'),
             String(minute).padStart(2, '0'),
@@ -455,7 +528,7 @@ class LocalTime {
      * Returns e.g: `19840621_1705`
      */
     toStringCompact(seconds = false) {
-        const { year, month, day, hour, minute, second } = this.components();
+        const { year, month, day, hour, minute, second } = this.getDateTimeObject();
         return [
             String(year).padStart(4, '0'),
             String(month).padStart(2, '0'),
@@ -560,6 +633,23 @@ class LocalTimeFactory {
     isValid(d) {
         return this.parseOrNull(d) !== null;
     }
+    /**
+     * Returns the IANA timezone e.g `Europe/Stockholm`.
+     * https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+     */
+    getTimezone() {
+        return Intl.DateTimeFormat().resolvedOptions().timeZone;
+    }
+    /**
+     * Returns true if passed IANA timezone is valid/supported.
+     * E.g `Europe/Stockholm` is valid, but `Europe/Stockholm2` is not.
+     *
+     * This implementation is not optimized for performance. If you need frequent validation -
+     * consider caching the Intl.supportedValuesOf values as Set and reuse that.
+     */
+    isTimezoneValid(tz) {
+        return Intl.supportedValuesOf('timeZone').includes(tz);
+    }
     now() {
         return new LocalTime(new Date());
     }
@@ -710,27 +800,3 @@ function nowUnix() {
     return Math.floor(Date.now() / 1000);
 }
 exports.nowUnix = nowUnix;
-/**
- * UTC offset is the opposite of "timezone offset" - it's the number of minutes to add
- * to the local time to get UTC time.
- *
- * E.g utcOffset for CEST is -120,
- * which means that you need to add -120 minutes to the local time to get UTC time.
- *
- * Instead of -0 it returns 0, for the peace of mind and less weird test/snapshot differences.
- */
-function getUTCOffsetMinutes() {
-    return -new Date().getTimezoneOffset() || 0;
-}
-exports.getUTCOffsetMinutes = getUTCOffsetMinutes;
-/**
- * Same as getUTCOffsetMinutes, but rounded to hours.
- *
- * E.g for CEST it is -2.
- *
- * Instead of -0 it returns 0, for the peace of mind and less weird test/snapshot differences.
- */
-function getUTCOffsetHours() {
-    return Math.round(getUTCOffsetMinutes() / 60);
-}
-exports.getUTCOffsetHours = getUTCOffsetHours;

package/dist/datetime/wallTime.d.ts

@@ -0,0 +1,33 @@
+import { DateTimeObject } from './localTime';
+/**
+ * Representation of a "time on the wall clock",
+ * which means "local time, regardless of timezone".
+ *
+ * Experimental simplified container object to hold
+ * date and time components as numbers.
+ * No math or manipulation is possible here.
+ * Can be pretty-printed as Date, Time or DateAndTime.
+ */
+export declare class WallTime implements DateTimeObject {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+    constructor(obj: DateTimeObject);
+    /**
+     * Returns e.g: `1984-06-21 17:56:21`
+     * or (if seconds=false):
+     * `1984-06-21 17:56`
+     */
+    toPretty(seconds?: boolean): string;
+    /**
+     * Returns e.g: `1984-06-21`, only the date part of DateTime
+     */
+    toISODate(): string;
+    /**
+     * Returns e.g: `17:03:15` (or `17:03` with seconds=false)
+     */
+    toISOTime(seconds?: boolean): string;
+}

package/dist/datetime/wallTime.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WallTime = void 0;
+/**
+ * Representation of a "time on the wall clock",
+ * which means "local time, regardless of timezone".
+ *
+ * Experimental simplified container object to hold
+ * date and time components as numbers.
+ * No math or manipulation is possible here.
+ * Can be pretty-printed as Date, Time or DateAndTime.
+ */
+class WallTime {
+    constructor(obj) {
+        Object.assign(this, obj);
+    }
+    /**
+     * Returns e.g: `1984-06-21 17:56:21`
+     * or (if seconds=false):
+     * `1984-06-21 17:56`
+     */
+    toPretty(seconds = true) {
+        return this.toISODate() + ' ' + this.toISOTime(seconds);
+    }
+    /**
+     * Returns e.g: `1984-06-21`, only the date part of DateTime
+     */
+    toISODate() {
+        return [
+            String(this.year).padStart(4, '0'),
+            String(this.month).padStart(2, '0'),
+            String(this.day).padStart(2, '0'),
+        ].join('-');
+    }
+    /**
+     * Returns e.g: `17:03:15` (or `17:03` with seconds=false)
+     */
+    toISOTime(seconds = true) {
+        return [
+            String(this.hour).padStart(2, '0'),
+            String(this.minute).padStart(2, '0'),
+            seconds && String(this.second).padStart(2, '0'),
+        ]
+            .filter(Boolean)
+            .join(':');
+    }
+}
+exports.WallTime = WallTime;

package/dist/index.d.ts

@@ -26,7 +26,6 @@ export * from './json-schema/jsonSchema.cnst';
 export * from './json-schema/jsonSchema.model';
 export * from './json-schema/jsonSchema.util';
 export * from './json-schema/jsonSchemaBuilder';
-export * from './json-schema/jsonSchemaBuilder';
 export * from './math/math.util';
 export * from './math/sma';
 export * from './number/createDeterministicRandom';
@@ -68,10 +67,7 @@ export * from './math/stack.util';
 export * from './string/leven';
 export * from './datetime/localDate';
 export * from './datetime/localTime';
-export * from './datetime/dateInterval';
-export * from './datetime/timeInterval';
-export * from './datetime/localDate';
-export * from './datetime/localTime';
+export * from './datetime/wallTime';
 export * from './datetime/dateInterval';
 export * from './datetime/timeInterval';
 export * from './env';

package/dist/index.js

@@ -30,7 +30,6 @@ tslib_1.__exportStar(require("./json-schema/jsonSchema.cnst"), exports);
 tslib_1.__exportStar(require("./json-schema/jsonSchema.model"), exports);
 tslib_1.__exportStar(require("./json-schema/jsonSchema.util"), exports);
 tslib_1.__exportStar(require("./json-schema/jsonSchemaBuilder"), exports);
-tslib_1.__exportStar(require("./json-schema/jsonSchemaBuilder"), exports);
 tslib_1.__exportStar(require("./math/math.util"), exports);
 tslib_1.__exportStar(require("./math/sma"), exports);
 tslib_1.__exportStar(require("./number/createDeterministicRandom"), exports);
@@ -72,10 +71,7 @@ tslib_1.__exportStar(require("./math/stack.util"), exports);
 tslib_1.__exportStar(require("./string/leven"), exports);
 tslib_1.__exportStar(require("./datetime/localDate"), exports);
 tslib_1.__exportStar(require("./datetime/localTime"), exports);
-tslib_1.__exportStar(require("./datetime/dateInterval"), exports);
-tslib_1.__exportStar(require("./datetime/timeInterval"), exports);
-tslib_1.__exportStar(require("./datetime/localDate"), exports);
-tslib_1.__exportStar(require("./datetime/localTime"), exports);
+tslib_1.__exportStar(require("./datetime/wallTime"), exports);
 tslib_1.__exportStar(require("./datetime/dateInterval"), exports);
 tslib_1.__exportStar(require("./datetime/timeInterval"), exports);
 tslib_1.__exportStar(require("./env"), exports);

package/dist-esm/datetime/localDate.js

@@ -320,6 +320,13 @@ export class LocalDate {
     toDateInUTC() {
         return new Date(this.toISODateTimeInUTC());
     }
+    toDateObject() {
+        return {
+            year: this.$year,
+            month: this.$month,
+            day: this.$day,
+        };
+    }
     /**
      * Converts LocalDate to LocalTime with 0 hours, 0 minutes, 0 seconds.
      * LocalTime's Date will be in local timezone.

package/dist-esm/datetime/localTime.js

@@ -1,6 +1,7 @@
 import { _assert } from '../error/assert';
 import { _ms } from '../time/time.util';
 import { localDate } from './localDate';
+import { WallTime } from './wallTime';
 export var ISODayOfWeek;
 (function (ISODayOfWeek) {
     ISODayOfWeek[ISODayOfWeek["MONDAY"] = 1] = "MONDAY";
@@ -35,6 +36,78 @@ export class LocalTime {
     local() {
         return new LocalTime(new Date(this.$date.getTime()));
     }
+    /**
+     * 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.
+     * See this ("common errors"): https://stackoverflow.com/a/15171030/4919972
+     * Fake also means that unixTimestamp of that new LocalDate is not the same.
+     * For that reason we return WallTime, and not a LocalTime.
+     * WallTime can be pretty-printed as Date-only, Time-only or DateAndTime.
+     *
+     * E.g `inTimezone('America/New_York').toISOTime()`
+     *
+     * https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+     *
+     * @experimental
+     */
+    inTimezone(tz) {
+        const d = new Date(this.$date.toLocaleString('en-US', { timeZone: tz }));
+        return new WallTime({
+            year: d.getFullYear(),
+            month: d.getMonth() + 1,
+            day: d.getDate(),
+            hour: d.getHours(),
+            minute: d.getMinutes(),
+            second: d.getSeconds(),
+        });
+    }
+    /**
+     * UTC offset is the opposite of "timezone offset" - it's the number of minutes to add
+     * to the local time to get UTC time.
+     *
+     * E.g utcOffset for CEST is -120,
+     * which means that you need to add -120 minutes to the local time to get UTC time.
+     *
+     * Instead of -0 it returns 0, for the peace of mind and less weird test/snapshot differences.
+     *
+     * If timezone (tz) is specified, e.g `America/New_York`,
+     * it will return the UTC offset for that timezone.
+     *
+     * https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+     */
+    getUTCOffsetMinutes(tz) {
+        if (tz) {
+            // based on: https://stackoverflow.com/a/53652131/4919972
+            const nowTime = this.$date.getTime();
+            const tzTime = new Date(this.$date.toLocaleString('en-US', { timeZone: tz })).getTime();
+            return Math.round((tzTime - nowTime) / 60000) || 0;
+        }
+        return -this.$date.getTimezoneOffset() || 0;
+    }
+    /**
+     * Same as getUTCOffsetMinutes, but rounded to hours.
+     *
+     * E.g for CEST it is -2.
+     *
+     * Instead of -0 it returns 0, for the peace of mind and less weird test/snapshot differences.
+     *
+     * If timezone (tz) is specified, e.g `America/New_York`,
+     * it will return the UTC offset for that timezone.
+     */
+    getUTCOffsetHours(tz) {
+        return Math.round(this.getUTCOffsetMinutes(tz) / 60);
+    }
+    /**
+     * Returns e.g `-05:00` for New_York winter time.
+     */
+    getUTCOffsetString(tz) {
+        const minutes = this.getUTCOffsetMinutes(tz);
+        const hours = Math.trunc(minutes / 60);
+        const sign = hours < 0 ? '-' : '+';
+        const h = String(Math.abs(hours)).padStart(2, '0');
+        const m = String(minutes % 60).padStart(2, '0');
+        return `${sign}${h}:${m}`;
+    }
     get(unit) {
         if (unit === 'year') {
             return this.$date.getFullYear();
@@ -354,20 +427,20 @@ export class LocalTime {
             return 0;
         return t1 < t2 ? -1 : 1;
     }
-    components() {
+    getDateTimeObject() {
         return {
-            ...this.dateComponents(),
-            ...this.timeComponents(),
+            ...this.getDateObject(),
+            ...this.getTimeObject(),
         };
     }
-    dateComponents() {
+    getDateObject() {
         return {
             year: this.$date.getFullYear(),
             month: this.$date.getMonth() + 1,
             day: this.$date.getDate(),
         };
     }
-    timeComponents() {
+    getTimeObject() {
         return {
             hour: this.$date.getHours(),
             minute: this.$date.getMinutes(),
@@ -424,7 +497,7 @@ export class LocalTime {
      * Returns e.g: `1984-06-21`, only the date part of DateTime
      */
     toISODate() {
-        const { year, month, day } = this.dateComponents();
+        const { year, month, day } = this.getDateObject();
         return [
             String(year).padStart(4, '0'),
             String(month).padStart(2, '0'),
@@ -437,7 +510,7 @@ export class LocalTime {
      * Returns e.g: `17:03:15` (or `17:03` with seconds=false)
      */
     toISOTime(seconds = true) {
-        const { hour, minute, second } = this.timeComponents();
+        const { hour, minute, second } = this.getTimeObject();
         return [
             String(hour).padStart(2, '0'),
             String(minute).padStart(2, '0'),
@@ -452,7 +525,7 @@ export class LocalTime {
      * Returns e.g: `19840621_1705`
      */
     toStringCompact(seconds = false) {
-        const { year, month, day, hour, minute, second } = this.components();
+        const { year, month, day, hour, minute, second } = this.getDateTimeObject();
         return [
             String(year).padStart(4, '0'),
             String(month).padStart(2, '0'),
@@ -556,6 +629,23 @@ class LocalTimeFactory {
     isValid(d) {
         return this.parseOrNull(d) !== null;
     }
+    /**
+     * Returns the IANA timezone e.g `Europe/Stockholm`.
+     * https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+     */
+    getTimezone() {
+        return Intl.DateTimeFormat().resolvedOptions().timeZone;
+    }
+    /**
+     * Returns true if passed IANA timezone is valid/supported.
+     * E.g `Europe/Stockholm` is valid, but `Europe/Stockholm2` is not.
+     *
+     * This implementation is not optimized for performance. If you need frequent validation -
+     * consider caching the Intl.supportedValuesOf values as Set and reuse that.
+     */
+    isTimezoneValid(tz) {
+        return Intl.supportedValuesOf('timeZone').includes(tz);
+    }
     now() {
         return new LocalTime(new Date());
     }
@@ -705,25 +795,3 @@ Object.setPrototypeOf(localTime, localTimeFactory);
 export function nowUnix() {
     return Math.floor(Date.now() / 1000);
 }
-/**
- * UTC offset is the opposite of "timezone offset" - it's the number of minutes to add
- * to the local time to get UTC time.
- *
- * E.g utcOffset for CEST is -120,
- * which means that you need to add -120 minutes to the local time to get UTC time.
- *
- * Instead of -0 it returns 0, for the peace of mind and less weird test/snapshot differences.
- */
-export function getUTCOffsetMinutes() {
-    return -new Date().getTimezoneOffset() || 0;
-}
-/**
- * Same as getUTCOffsetMinutes, but rounded to hours.
- *
- * E.g for CEST it is -2.
- *
- * Instead of -0 it returns 0, for the peace of mind and less weird test/snapshot differences.
- */
-export function getUTCOffsetHours() {
-    return Math.round(getUTCOffsetMinutes() / 60);
-}

package/dist-esm/datetime/wallTime.js

@@ -0,0 +1,44 @@
+/**
+ * Representation of a "time on the wall clock",
+ * which means "local time, regardless of timezone".
+ *
+ * Experimental simplified container object to hold
+ * date and time components as numbers.
+ * No math or manipulation is possible here.
+ * Can be pretty-printed as Date, Time or DateAndTime.
+ */
+export class WallTime {
+    constructor(obj) {
+        Object.assign(this, obj);
+    }
+    /**
+     * Returns e.g: `1984-06-21 17:56:21`
+     * or (if seconds=false):
+     * `1984-06-21 17:56`
+     */
+    toPretty(seconds = true) {
+        return this.toISODate() + ' ' + this.toISOTime(seconds);
+    }
+    /**
+     * Returns e.g: `1984-06-21`, only the date part of DateTime
+     */
+    toISODate() {
+        return [
+            String(this.year).padStart(4, '0'),
+            String(this.month).padStart(2, '0'),
+            String(this.day).padStart(2, '0'),
+        ].join('-');
+    }
+    /**
+     * Returns e.g: `17:03:15` (or `17:03` with seconds=false)
+     */
+    toISOTime(seconds = true) {
+        return [
+            String(this.hour).padStart(2, '0'),
+            String(this.minute).padStart(2, '0'),
+            seconds && String(this.second).padStart(2, '0'),
+        ]
+            .filter(Boolean)
+            .join(':');
+    }
+}

package/dist-esm/index.js

@@ -26,7 +26,6 @@ export * from './json-schema/jsonSchema.cnst';
 export * from './json-schema/jsonSchema.model';
 export * from './json-schema/jsonSchema.util';
 export * from './json-schema/jsonSchemaBuilder';
-export * from './json-schema/jsonSchemaBuilder';
 export * from './math/math.util';
 export * from './math/sma';
 export * from './number/createDeterministicRandom';
@@ -68,10 +67,7 @@ export * from './math/stack.util';
 export * from './string/leven';
 export * from './datetime/localDate';
 export * from './datetime/localTime';
-export * from './datetime/dateInterval';
-export * from './datetime/timeInterval';
-export * from './datetime/localDate';
-export * from './datetime/localTime';
+export * from './datetime/wallTime';
 export * from './datetime/dateInterval';
 export * from './datetime/timeInterval';
 export * from './env';

package/package.json

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

package/src/datetime/localDate.ts

@@ -9,7 +9,7 @@ import type {
   UnixTimestampMillisNumber,
   UnixTimestampNumber,
 } from '../types'
-import { ISODayOfWeek, localTime, LocalTime } from './localTime'
+import { DateObject, ISODayOfWeek, localTime, LocalTime } from './localTime'
 
 export type LocalDateUnit = LocalDateUnitStrict | 'week'
 export type LocalDateUnitStrict = 'year' | 'month' | 'day'
@@ -381,6 +381,14 @@ export class LocalDate {
     return new Date(this.toISODateTimeInUTC())
   }
 
+  toDateObject(): DateObject {
+    return {
+      year: this.$year,
+      month: this.$month,
+      day: this.$day,
+    }
+  }
+
   /**
    * Converts LocalDate to LocalTime with 0 hours, 0 minutes, 0 seconds.
    * LocalTime's Date will be in local timezone.

package/src/datetime/localTime.ts

@@ -12,6 +12,7 @@ import type {
   UnixTimestampNumber,
 } from '../types'
 import { localDate, LocalDate } from './localDate'
+import { WallTime } from './wallTime'
 
 export type LocalTimeUnit = 'year' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second'
 
@@ -28,15 +29,15 @@ export enum ISODayOfWeek {
 export type LocalTimeInput = LocalTime | Date | IsoDateTimeString | UnixTimestampNumber
 export type LocalTimeFormatter = (ld: LocalTime) => string
 
-export type LocalTimeComponents = DateComponents & TimeComponents
+export type DateTimeObject = DateObject & TimeObject
 
-interface DateComponents {
+export interface DateObject {
   year: number
   month: number
   day: number
 }
 
-interface TimeComponents {
+export interface TimeObject {
   hour: number
   minute: number
   second: number
@@ -68,6 +69,83 @@ export class LocalTime {
     return new LocalTime(new Date(this.$date.getTime()))
   }
 
+  /**
+   * 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.
+   * See this ("common errors"): https://stackoverflow.com/a/15171030/4919972
+   * Fake also means that unixTimestamp of that new LocalDate is not the same.
+   * For that reason we return WallTime, and not a LocalTime.
+   * WallTime can be pretty-printed as Date-only, Time-only or DateAndTime.
+   *
+   * E.g `inTimezone('America/New_York').toISOTime()`
+   *
+   * https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+   *
+   * @experimental
+   */
+  inTimezone(tz: string): WallTime {
+    const d = new Date(this.$date.toLocaleString('en-US', { timeZone: tz }))
+    return new WallTime({
+      year: d.getFullYear(),
+      month: d.getMonth() + 1,
+      day: d.getDate(),
+      hour: d.getHours(),
+      minute: d.getMinutes(),
+      second: d.getSeconds(),
+    })
+  }
+
+  /**
+   * UTC offset is the opposite of "timezone offset" - it's the number of minutes to add
+   * to the local time to get UTC time.
+   *
+   * E.g utcOffset for CEST is -120,
+   * which means that you need to add -120 minutes to the local time to get UTC time.
+   *
+   * Instead of -0 it returns 0, for the peace of mind and less weird test/snapshot differences.
+   *
+   * If timezone (tz) is specified, e.g `America/New_York`,
+   * it will return the UTC offset for that timezone.
+   *
+   * https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+   */
+  getUTCOffsetMinutes(tz?: string): NumberOfMinutes {
+    if (tz) {
+      // based on: https://stackoverflow.com/a/53652131/4919972
+      const nowTime = this.$date.getTime()
+      const tzTime = new Date(this.$date.toLocaleString('en-US', { timeZone: tz })).getTime()
+      return Math.round((tzTime - nowTime) / 60000) || 0
+    }
+
+    return -this.$date.getTimezoneOffset() || 0
+  }
+
+  /**
+   * Same as getUTCOffsetMinutes, but rounded to hours.
+   *
+   * E.g for CEST it is -2.
+   *
+   * Instead of -0 it returns 0, for the peace of mind and less weird test/snapshot differences.
+   *
+   * If timezone (tz) is specified, e.g `America/New_York`,
+   * it will return the UTC offset for that timezone.
+   */
+  getUTCOffsetHours(tz?: string): NumberOfHours {
+    return Math.round(this.getUTCOffsetMinutes(tz) / 60)
+  }
+
+  /**
+   * Returns e.g `-05:00` for New_York winter time.
+   */
+  getUTCOffsetString(tz: string): string {
+    const minutes = this.getUTCOffsetMinutes(tz)
+    const hours = Math.trunc(minutes / 60)
+    const sign = hours < 0 ? '-' : '+'
+    const h = String(Math.abs(hours)).padStart(2, '0')
+    const m = String(minutes % 60).padStart(2, '0')
+    return `${sign}${h}:${m}`
+  }
+
   get(unit: LocalTimeUnit): number {
     if (unit === 'year') {
       return this.$date.getFullYear()
@@ -166,7 +244,7 @@ export class LocalTime {
     return v === undefined ? this.get('second') : this.set('second', v)
   }
 
-  setComponents(c: Partial<LocalTimeComponents>, mutate = false): LocalTime {
+  setComponents(c: Partial<DateTimeObject>, mutate = false): LocalTime {
     const d = mutate ? this.$date : new Date(this.$date)
 
     // Year, month and day set all-at-once, to avoid 30/31 (and 28/29) mishap
@@ -434,14 +512,14 @@ export class LocalTime {
     return t1 < t2 ? -1 : 1
   }
 
-  components(): LocalTimeComponents {
+  getDateTimeObject(): DateTimeObject {
     return {
-      ...this.dateComponents(),
-      ...this.timeComponents(),
+      ...this.getDateObject(),
+      ...this.getTimeObject(),
     }
   }
 
-  private dateComponents(): DateComponents {
+  getDateObject(): DateObject {
     return {
       year: this.$date.getFullYear(),
       month: this.$date.getMonth() + 1,
@@ -449,7 +527,7 @@ export class LocalTime {
     }
   }
 
-  private timeComponents(): TimeComponents {
+  getTimeObject(): TimeObject {
     return {
       hour: this.$date.getHours(),
       minute: this.$date.getMinutes(),
@@ -518,7 +596,7 @@ export class LocalTime {
    * Returns e.g: `1984-06-21`, only the date part of DateTime
    */
   toISODate(): IsoDateString {
-    const { year, month, day } = this.dateComponents()
+    const { year, month, day } = this.getDateObject()
 
     return [
       String(year).padStart(4, '0'),
@@ -534,7 +612,7 @@ export class LocalTime {
    * Returns e.g: `17:03:15` (or `17:03` with seconds=false)
    */
   toISOTime(seconds = true): string {
-    const { hour, minute, second } = this.timeComponents()
+    const { hour, minute, second } = this.getTimeObject()
 
     return [
       String(hour).padStart(2, '0'),
@@ -552,7 +630,7 @@ export class LocalTime {
    * Returns e.g: `19840621_1705`
    */
   toStringCompact(seconds = false): string {
-    const { year, month, day, hour, minute, second } = this.components()
+    const { year, month, day, hour, minute, second } = this.getDateTimeObject()
 
     return [
       String(year).padStart(4, '0'),
@@ -672,6 +750,25 @@ class LocalTimeFactory {
     return this.parseOrNull(d) !== null
   }
 
+  /**
+   * Returns the IANA timezone e.g `Europe/Stockholm`.
+   * https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+   */
+  getTimezone(): string {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone
+  }
+
+  /**
+   * Returns true if passed IANA timezone is valid/supported.
+   * E.g `Europe/Stockholm` is valid, but `Europe/Stockholm2` is not.
+   *
+   * This implementation is not optimized for performance. If you need frequent validation -
+   * consider caching the Intl.supportedValuesOf values as Set and reuse that.
+   */
+  isTimezoneValid(tz: string): boolean {
+    return Intl.supportedValuesOf('timeZone').includes(tz)
+  }
+
   now(): LocalTime {
     return new LocalTime(new Date())
   }
@@ -692,7 +789,7 @@ class LocalTimeFactory {
     return d ? this.of(d) : this.now()
   }
 
-  fromComponents(c: { year: number; month: number } & Partial<LocalTimeComponents>): LocalTime {
+  fromComponents(c: { year: number; month: number } & Partial<DateTimeObject>): LocalTime {
     return new LocalTime(
       new Date(c.year, c.month - 1, c.day || 1, c.hour || 0, c.minute || 0, c.second || 0),
     )
@@ -857,27 +954,3 @@ Object.setPrototypeOf(localTime, localTimeFactory)
 export function nowUnix(): UnixTimestampNumber {
   return Math.floor(Date.now() / 1000)
 }
-
-/**
- * UTC offset is the opposite of "timezone offset" - it's the number of minutes to add
- * to the local time to get UTC time.
- *
- * E.g utcOffset for CEST is -120,
- * which means that you need to add -120 minutes to the local time to get UTC time.
- *
- * Instead of -0 it returns 0, for the peace of mind and less weird test/snapshot differences.
- */
-export function getUTCOffsetMinutes(): NumberOfMinutes {
-  return -new Date().getTimezoneOffset() || 0
-}
-
-/**
- * Same as getUTCOffsetMinutes, but rounded to hours.
- *
- * E.g for CEST it is -2.
- *
- * Instead of -0 it returns 0, for the peace of mind and less weird test/snapshot differences.
- */
-export function getUTCOffsetHours(): NumberOfHours {
-  return Math.round(getUTCOffsetMinutes() / 60)
-}

package/src/datetime/wallTime.ts

@@ -0,0 +1,56 @@
+import { DateTimeObject } from './localTime'
+
+/**
+ * Representation of a "time on the wall clock",
+ * which means "local time, regardless of timezone".
+ *
+ * Experimental simplified container object to hold
+ * date and time components as numbers.
+ * No math or manipulation is possible here.
+ * Can be pretty-printed as Date, Time or DateAndTime.
+ */
+export class WallTime implements DateTimeObject {
+  year!: number
+  month!: number
+  day!: number
+  hour!: number
+  minute!: number
+  second!: number
+
+  constructor(obj: DateTimeObject) {
+    Object.assign(this, obj)
+  }
+
+  /**
+   * Returns e.g: `1984-06-21 17:56:21`
+   * or (if seconds=false):
+   * `1984-06-21 17:56`
+   */
+  toPretty(seconds = true): string {
+    return this.toISODate() + ' ' + this.toISOTime(seconds)
+  }
+
+  /**
+   * Returns e.g: `1984-06-21`, only the date part of DateTime
+   */
+  toISODate(): string {
+    return [
+      String(this.year).padStart(4, '0'),
+      String(this.month).padStart(2, '0'),
+      String(this.day).padStart(2, '0'),
+    ].join('-')
+  }
+
+  /**
+   * Returns e.g: `17:03:15` (or `17:03` with seconds=false)
+   */
+  toISOTime(seconds = true): string {
+    return [
+      String(this.hour).padStart(2, '0'),
+      String(this.minute).padStart(2, '0'),
+      seconds && String(this.second).padStart(2, '0'),
+    ]
+      .filter(Boolean)
+      .join(':')
+  }
+}

package/src/index.ts

@@ -26,7 +26,6 @@ export * from './json-schema/jsonSchema.cnst'
 export * from './json-schema/jsonSchema.model'
 export * from './json-schema/jsonSchema.util'
 export * from './json-schema/jsonSchemaBuilder'
-export * from './json-schema/jsonSchemaBuilder'
 export * from './math/math.util'
 export * from './math/sma'
 export * from './number/createDeterministicRandom'
@@ -68,10 +67,7 @@ export * from './math/stack.util'
 export * from './string/leven'
 export * from './datetime/localDate'
 export * from './datetime/localTime'
-export * from './datetime/dateInterval'
-export * from './datetime/timeInterval'
-export * from './datetime/localDate'
-export * from './datetime/localTime'
+export * from './datetime/wallTime'
 export * from './datetime/dateInterval'
 export * from './datetime/timeInterval'
 export * from './env'