@naturalcycles/js-lib 14.235.0 → 14.237.0

package/dist-esm/string/safeJsonStringify.js

@@ -8,7 +8,7 @@ export function _safeJsonStringify(obj, replacer, spaces, cycleReplacer) {
         // Try native first (as it's ~3 times faster)
         return JSON.stringify(obj, replacer, spaces);
     }
-    catch (_a) {
+    catch {
         // Native failed - resort to the "safe" serializer
         return JSON.stringify(obj, serializer(replacer, cycleReplacer), spaces);
     }
@@ -17,7 +17,7 @@ export function _safeJsonStringify(obj, replacer, spaces, cycleReplacer) {
 function serializer(replacer, cycleReplacer) {
     const stack = [];
     const keys = [];
-    cycleReplacer !== null && cycleReplacer !== void 0 ? cycleReplacer : (cycleReplacer = function (key, value) {
+    cycleReplacer ?? (cycleReplacer = function (key, value) {
         if (stack[0] === value)
             return '[Circular ~]';
         return '[Circular ~.' + keys.slice(0, stack.indexOf(value)).join('.') + ']';

package/dist-esm/string/stringify.js

@@ -117,7 +117,7 @@ export function _stringify(obj, opt = {}) {
             const { stringifyFn = globalStringifyFunction } = opt;
             s = stringifyFn(obj, undefined, 2);
         }
-        catch (_a) {
+        catch {
             s = String(obj); // fallback
         }
     }

package/dist-esm/web.js

@@ -14,8 +14,7 @@ export class InMemoryWebStorage {
     // but can be implemented with Proxy
     // [ name: string ]: any
     getItem(key) {
-        var _a;
-        return (_a = this.data[key]) !== null && _a !== void 0 ? _a : null;
+        return this.data[key] ?? null;
     }
     setItem(key, value) {
         this.data[key] = String(value);
@@ -24,8 +23,7 @@ export class InMemoryWebStorage {
         delete this.data[key];
     }
     key(index) {
-        var _a;
-        return (_a = Object.keys(this.data)[index]) !== null && _a !== void 0 ? _a : null;
+        return Object.keys(this.data)[index] ?? null;
     }
     clear() {
         this.data = {};

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

@@ -31,10 +31,9 @@ export class ZodValidationError extends ZodError {
         return this.annotate();
     }
     annotate() {
-        var _a;
         let objectTitle = this.schema.description;
         if (typeof this.value === 'object' && this.value) {
-            const objectName = this.schema.description || ((_a = this.value.constructor) === null || _a === void 0 ? void 0 : _a.name);
+            const objectName = this.schema.description || this.value.constructor?.name;
             const objectId = this.value['id'];
             objectTitle = [objectName, objectId].filter(Boolean).join('.');
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturalcycles/js-lib",
-  "version": "14.235.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'