@naturalcycles/js-lib 14.235.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/array/range.js

@@ -1,4 +1,3 @@
-import { __asyncGenerator, __await } from "tslib";
 import { AsyncIterable2 } from '../iter/asyncIterable2';
 import { Iterable2 } from '../iter/iterable2';
 export function _range(fromIncl, toExcl, step = 1) {
@@ -26,12 +25,10 @@ export function _rangeAsyncIterable(fromIncl, toExcl, step = 1) {
         fromIncl = 0;
     }
     return AsyncIterable2.of({
-        [Symbol.asyncIterator]() {
-            return __asyncGenerator(this, arguments, function* _a() {
-                for (let i = fromIncl; i < toExcl; i += step) {
-                    yield yield __await(i);
-                }
-            });
+        async *[Symbol.asyncIterator]() {
+            for (let i = fromIncl; i < toExcl; i += step) {
+                yield i;
+            }
         },
     });
 }

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.