@naturalcycles/js-lib 14.235.0 → 14.237.0

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();
@@ -112,11 +185,10 @@ 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);
         // 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());
+            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);
@@ -317,13 +389,13 @@ export class LocalTime {
      * Third argument allows to override "now".
      */
     isOlderThan(n, unit, now) {
-        return this.isBefore(localTime.of(now !== null && now !== void 0 ? now : new Date()).plus(-n, unit));
+        return this.isBefore(localTime.of(now ?? new Date()).plus(-n, unit));
     }
     /**
      * Checks if this localTime is same or older (<=) than "now" by X units.
      */
     isSameOrOlderThan(n, unit, now) {
-        return this.isSameOrBefore(localTime.of(now !== null && now !== void 0 ? now : new Date()).plus(-n, unit));
+        return this.isSameOrBefore(localTime.of(now ?? new Date()).plus(-n, unit));
     }
     /**
      * Checks if this localTime is younger (>) than "now" by X units.
@@ -335,13 +407,13 @@ export class LocalTime {
      * Third argument allows to override "now".
      */
     isYoungerThan(n, unit, now) {
-        return this.isAfter(localTime.of(now !== null && now !== void 0 ? now : new Date()).plus(-n, unit));
+        return this.isAfter(localTime.of(now ?? new Date()).plus(-n, unit));
     }
     /**
      * Checks if this localTime is same or younger (>=) than "now" by X units.
      */
     isSameOrYoungerThan(n, unit, now) {
-        return this.isSameOrAfter(localTime.of(now !== null && now !== void 0 ? now : new Date()).plus(-n, unit));
+        return this.isSameOrAfter(localTime.of(now ?? new Date()).plus(-n, unit));
     }
     /**
      * Returns 1 if this > d
@@ -355,17 +427,20 @@ export class LocalTime {
             return 0;
         return t1 < t2 ? -1 : 1;
     }
-    components() {
-        return Object.assign(Object.assign({}, this.dateComponents()), this.timeComponents());
+    getDateTimeObject() {
+        return {
+            ...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(),
@@ -422,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'),
@@ -435,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'),
@@ -450,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'),
@@ -554,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());
     }
@@ -703,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/decorators/asyncMemo.decorator.js

@@ -108,6 +108,6 @@ export const _AsyncMemo = (opt) => (target, key, descriptor) => {
  e.g `clear` to clear the cache, or get its underlying data.
  */
 export function _getAsyncMemo(method) {
-    _assert(typeof (method === null || method === void 0 ? void 0 : method.getInstanceCache) === 'function', 'method is not an AsyncMemo instance');
+    _assert(typeof method?.getInstanceCache === 'function', 'method is not an AsyncMemo instance');
     return method;
 }

package/dist-esm/decorators/createPromiseDecorator.js

@@ -18,7 +18,6 @@ export function _createPromiseDecorator(cfg, decoratorParams = {}) {
         const key = String(propertyKey);
         const methodSignature = _getTargetMethodSignature(target, key);
         pd.value = async function (...args) {
-            var _a, _b;
             // console.log(`@${cfg.decoratorName} called inside function`)
             const started = Date.now();
             try {
@@ -46,9 +45,12 @@ export function _createPromiseDecorator(cfg, decoratorParams = {}) {
                     started,
                 };
                 if (cfg.thenFn) {
-                    res = cfg.thenFn(Object.assign(Object.assign({}, resp), { res }));
+                    res = cfg.thenFn({
+                        ...resp,
+                        res,
+                    });
                 }
-                (_a = cfg.finallyFn) === null || _a === void 0 ? void 0 : _a.call(cfg, resp);
+                cfg.finallyFn?.(resp);
                 return res;
             }
             catch (err) {
@@ -63,10 +65,13 @@ export function _createPromiseDecorator(cfg, decoratorParams = {}) {
                 };
                 let handled = false;
                 if (cfg.catchFn) {
-                    cfg.catchFn(Object.assign(Object.assign({}, resp), { err }));
+                    cfg.catchFn({
+                        ...resp,
+                        err,
+                    });
                     handled = true;
                 }
-                (_b = cfg.finallyFn) === null || _b === void 0 ? void 0 : _b.call(cfg, resp);
+                cfg.finallyFn?.(resp);
                 if (!handled) {
                     throw err; // rethrow
                 }

package/dist-esm/decorators/debounce.js

@@ -105,5 +105,10 @@ export function _debounce(func, wait, opt = {}) {
     return debounced;
 }
 export function _throttle(func, wait, opt = {}) {
-    return _debounce(func, wait, Object.assign(Object.assign({ leading: true, trailing: true }, opt), { maxWait: wait }));
+    return _debounce(func, wait, {
+        leading: true,
+        trailing: true,
+        ...opt,
+        maxWait: wait,
+    });
 }

package/dist-esm/decorators/memo.decorator.js

@@ -77,6 +77,6 @@ export const _Memo = (opt = {}) => (target, key, descriptor) => {
  e.g `clear` to clear the cache, or get its underlying data.
  */
 export function _getMemo(method) {
-    _assert(typeof (method === null || method === void 0 ? void 0 : method.getInstanceCache) === 'function', 'method is not a Memo instance');
+    _assert(typeof method?.getInstanceCache === 'function', 'method is not a Memo instance');
     return method;
 }

package/dist-esm/define.js

@@ -76,14 +76,26 @@ export function _defineLazyProps(obj, props) {
  *
  */
 export function _defineProperty(obj, prop, pd) {
-    return Object.defineProperty(obj, prop, Object.assign({ writable: true, configurable: true, enumerable: true }, pd));
+    return Object.defineProperty(obj, prop, {
+        writable: true,
+        configurable: true,
+        enumerable: true,
+        // value: obj[prop], // existing value is already kept by default
+        ...pd,
+    });
 }
 /**
  * Object.defineProperties with better defaults.
  * See _defineProperty for exact defaults definition.
  */
 export function _defineProps(obj, props) {
-    return Object.defineProperties(obj, _mapValues(props, (k, pd) => (Object.assign({ writable: true, configurable: true, enumerable: true }, pd))));
+    return Object.defineProperties(obj, _mapValues(props, (k, pd) => ({
+        writable: true,
+        configurable: true,
+        enumerable: true,
+        // value: obj[k], // existing value is already kept by default
+        ...pd,
+    })));
 }
 /**
  * Like _defineProps, but skips props with nullish values.

package/dist-esm/enum.util.js

@@ -147,8 +147,7 @@ export function _numberEnumKey(en, v) {
 export function _stringEnumKeyOrUndefined(en, 
 // v: T[keyof T] | undefined | null, // cannot make it type-safe :(
 v) {
-    var _a;
-    return (_a = Object.entries(en).find(([_, v2]) => v2 === v)) === null || _a === void 0 ? void 0 : _a[0];
+    return Object.entries(en).find(([_, v2]) => v2 === v)?.[0];
 }
 export function _stringEnumKey(en, v) {
     const r = _stringEnumKeyOrUndefined(en, v);

package/dist-esm/error/assert.js

@@ -17,7 +17,10 @@ import { _deepEquals, _isErrorObject, _stringify, AssertionError } from '..';
 export function _assert(condition, // will be evaluated as Boolean
 message, errorData) {
     if (!condition) {
-        throw new AssertionError(message || 'condition failed', Object.assign({ userFriendly: true }, errorData));
+        throw new AssertionError(message || 'condition failed', {
+            userFriendly: true,
+            ...errorData,
+        });
     }
 }
 /**
@@ -32,7 +35,10 @@ export function _assertEquals(actual, expected, message, errorData) {
             ['not equal', `expected: ${_stringify(expected)}`, `got     : ${_stringify(actual)}`]
                 .filter(Boolean)
                 .join('\n');
-        throw new AssertionError(msg, Object.assign({ userFriendly: true }, errorData));
+        throw new AssertionError(msg, {
+            userFriendly: true,
+            ...errorData,
+        });
     }
 }
 /**
@@ -47,7 +53,10 @@ export function _assertDeepEquals(actual, expected, message, errorData) {
             [`not deeply equal`, `expected: ${_stringify(expected)}`, `got     : ${_stringify(actual)}`]
                 .filter(Boolean)
                 .join('\n');
-        throw new AssertionError(msg, Object.assign({ userFriendly: true }, errorData));
+        throw new AssertionError(msg, {
+            userFriendly: true,
+            ...errorData,
+        });
     }
 }
 export function _assertIsError(err, errorClass = Error) {

package/dist-esm/error/error.util.js

@@ -19,7 +19,10 @@ export function _anyToError(o, errorClass = Error, errorData) {
     }
     if (errorData) {
         ;
-        e.data = Object.assign(Object.assign({}, e.data), errorData);
+        e.data = {
+            ...e.data,
+            ...errorData,
+        };
     }
     return e;
 }
@@ -73,7 +76,7 @@ export function _errorLikeToErrorObject(e) {
     const obj = {
         name: e.name,
         message: e.message,
-        data: Object.assign({}, e.data), // empty by default
+        data: { ...e.data }, // empty by default
     };
     if (e.stack)
         obj.stack = e.stack;
@@ -168,11 +171,10 @@ export function _errorSnippet(err, opt = {}) {
     }
 }
 export function _isBackendErrorResponseObject(o) {
-    return _isErrorObject(o === null || o === void 0 ? void 0 : o.error);
+    return _isErrorObject(o?.error);
 }
 export function _isHttpRequestErrorObject(o) {
-    var _a;
-    return !!o && o.name === 'HttpRequestError' && typeof ((_a = o.data) === null || _a === void 0 ? void 0 : _a.requestUrl) === 'string';
+    return !!o && o.name === 'HttpRequestError' && typeof o.data?.requestUrl === 'string';
 }
 /**
  * Note: any instance of AppError is also automatically an ErrorObject
@@ -204,7 +206,10 @@ export function _isErrorLike(o) {
 export function _errorDataAppend(err, data) {
     if (!data)
         return err;
-    err.data = Object.assign(Object.assign({}, err.data), data);
+    err.data = {
+        ...err.data,
+        ...data,
+    };
     return err;
 }
 /**
@@ -294,7 +299,7 @@ export class HttpRequestError extends AppError {
                 enumerable: false,
             });
         }
-        super(message, data, Object.assign(Object.assign({}, opt), { name: 'HttpRequestError' }));
+        super(message, data, { ...opt, name: 'HttpRequestError' });
     }
 }
 export class AssertionError extends AppError {
@@ -312,7 +317,7 @@ export class JsonParseError extends AppError {
 }
 export class TimeoutError extends AppError {
     constructor(message, data, opt) {
-        super(message, data, Object.assign(Object.assign({}, opt), { name: 'TimeoutError' }));
+        super(message, data, { ...opt, name: 'TimeoutError' });
     }
 }
 /**

package/dist-esm/error/tryCatch.js

@@ -27,7 +27,7 @@ export function _tryCatch(fn, opt = {}) {
                 try {
                     return await onError(_anyToError(err)); // eslint-disable-line @typescript-eslint/return-await
                 }
-                catch (_a) { }
+                catch { }
             }
             // returns undefined, but doesn't rethrow
         }