@naturalcycles/js-lib 14.272.0 → 14.274.0

package/dist/datetime/localTime.d.ts

@@ -1,4 +1,4 @@
-import type { Inclusiveness, IsoDate, IsoDateTime, MonthId, NumberOfHours, NumberOfMinutes, SortDirection, UnixTimestamp, UnixTimestampMillis } from '../types';
+import type { IANATimezone, Inclusiveness, IsoDate, IsoDateTime, MonthId, NumberOfHours, NumberOfMinutes, SortDirection, UnixTimestamp, UnixTimestampMillis } from '../types';
 import { LocalDate } from './localDate';
 import { WallTime } from './wallTime';
 export type LocalTimeUnit = 'year' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second';
@@ -54,7 +54,7 @@ export declare class LocalTime {
      *
      * @experimental
      */
-    inTimezone(tz: string): WallTime;
+    inTimezone(tz: IANATimezone): 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.
@@ -69,7 +69,7 @@ export declare class LocalTime {
      *
      * https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
      */
-    getUTCOffsetMinutes(tz?: string): NumberOfMinutes;
+    getUTCOffsetMinutes(tz?: IANATimezone): NumberOfMinutes;
     /**
      * Same as getUTCOffsetMinutes, but rounded to hours.
      *
@@ -80,11 +80,11 @@ export declare class LocalTime {
      * If timezone (tz) is specified, e.g `America/New_York`,
      * it will return the UTC offset for that timezone.
      */
-    getUTCOffsetHours(tz?: string): NumberOfHours;
+    getUTCOffsetHours(tz?: IANATimezone): NumberOfHours;
     /**
      * Returns e.g `-05:00` for New_York winter time.
      */
-    getUTCOffsetString(tz: string): string;
+    getUTCOffsetString(tz: IANATimezone): string;
     get(unit: LocalTimeUnit): number;
     set(unit: LocalTimeUnit, v: number, mutate?: boolean): LocalTime;
     get year(): number;
@@ -220,6 +220,7 @@ export declare class LocalTime {
      * Returns e.g: `17:03:15` (or `17:03` with seconds=false)
      */
     toISOTime(seconds?: boolean): string;
+    toWallTime(): WallTime;
     /**
      * Returns e.g: `19840621_1705`
      */
@@ -304,7 +305,7 @@ declare class LocalTimeFactory {
      * Returns the IANA timezone e.g `Europe/Stockholm`.
      * https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
      */
-    getTimezone(): string;
+    getTimezone(): IANATimezone;
     /**
      * Returns true if passed IANA timezone is valid/supported.
      * E.g `Europe/Stockholm` is valid, but `Europe/Stockholm2` is not.

package/dist/datetime/localTime.js

@@ -607,6 +607,9 @@ class LocalTime {
         // !! Not using toISOString(), as it returns time in UTC, not in local timezone (unexpected!)
         // return this.$date.toISOString().slice(11, seconds ? 19 : 16)
     }
+    toWallTime() {
+        return new wallTime_1.WallTime(this.toDateTimeObject());
+    }
     /**
      * Returns e.g: `19840621_1705`
      */
@@ -853,6 +856,8 @@ class LocalTimeFactory {
      * consider caching the Intl.supportedValuesOf values as Set and reuse that.
      */
     isTimezoneValid(tz) {
+        if (tz === 'UTC')
+            return true; // we deliberately consider UTC a valid timezone, while it's mostly used in testing
         return Intl.supportedValuesOf('timeZone').includes(tz);
     }
     sort(items, dir = 'asc', mutate = false) {

package/dist/datetime/wallTime.d.ts

@@ -1,5 +1,6 @@
-import { IsoDate } from '../types';
-import { DateTimeObject } from './localTime';
+import { IsoDate, IsoDateTime } from '../types';
+import { LocalDate } from './localDate';
+import { DateTimeObject, LocalTime } from './localTime';
 /**
  * Representation of a "time on the wall clock",
  * which means "local time, regardless of timezone".
@@ -17,12 +18,26 @@ export declare class WallTime implements DateTimeObject {
     minute: number;
     second: number;
     constructor(obj: DateTimeObject);
+    toLocalDate(): LocalDate;
+    /**
+     * Example:
+     * WallTime is 1984-06-21 17:56:21
+     * .toLocalTime() will return a LocalTime Date instance
+     * holding that time in the local timezone.
+     */
+    toLocalTime(): LocalTime;
+    toJSON(): IsoDateTime;
+    toString(): IsoDateTime;
     /**
      * 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-21T17:56:21`
+     */
+    toISODateTime(): IsoDateTime;
     /**
      * Returns e.g: `1984-06-21`, only the date part of DateTime
      */

package/dist/datetime/wallTime.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WallTime = void 0;
+const localDate_1 = require("./localDate");
+const localTime_1 = require("./localTime");
 /**
  * Representation of a "time on the wall clock",
  * which means "local time, regardless of timezone".
@@ -14,6 +16,24 @@ class WallTime {
     constructor(obj) {
         Object.assign(this, obj);
     }
+    toLocalDate() {
+        return new localDate_1.LocalDate(this.year, this.month, this.day);
+    }
+    /**
+     * Example:
+     * WallTime is 1984-06-21 17:56:21
+     * .toLocalTime() will return a LocalTime Date instance
+     * holding that time in the local timezone.
+     */
+    toLocalTime() {
+        return localTime_1.localTime.fromDateTimeObject(this);
+    }
+    toJSON() {
+        return this.toISODateTime();
+    }
+    toString() {
+        return this.toISODateTime();
+    }
     /**
      * Returns e.g: `1984-06-21 17:56:21`
      * or (if seconds=false):
@@ -22,6 +42,12 @@ class WallTime {
     toPretty(seconds = true) {
         return this.toISODate() + ' ' + this.toISOTime(seconds);
     }
+    /**
+     * Returns e.g: `1984-06-21T17:56:21`
+     */
+    toISODateTime() {
+        return (this.toISODate() + 'T' + this.toISOTime());
+    }
     /**
      * Returns e.g: `1984-06-21`, only the date part of DateTime
      */

package/dist/index.d.ts

@@ -50,6 +50,7 @@ export * from './json-schema/jsonSchema.model';
 export * from './json-schema/jsonSchema.util';
 export * from './json-schema/jsonSchemaBuilder';
 export * from './log/commonLogger';
+export * from './math/accumulatingAverage';
 export * from './math/math.util';
 export * from './math/sma';
 export * from './math/stack.util';

package/dist/index.js

@@ -54,6 +54,7 @@ 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("./log/commonLogger"), exports);
+tslib_1.__exportStar(require("./math/accumulatingAverage"), exports);
 tslib_1.__exportStar(require("./math/math.util"), exports);
 tslib_1.__exportStar(require("./math/sma"), exports);
 tslib_1.__exportStar(require("./math/stack.util"), exports);

package/dist/math/accumulatingAverage.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Container that allows to accumulate average of a set of numbers,
+ * without the need to store all of them in memory.
+ *
+ * @experimental
+ */
+export declare class AccumulatingAverage {
+    total: number;
+    count: number;
+    /**
+     * Returns the current average.
+     * Returns 0 if no values have been added.
+     */
+    get average(): number;
+    /**
+     * Adds a new value.
+     */
+    add(value: number): void;
+    reset(): void;
+}

package/dist/math/accumulatingAverage.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccumulatingAverage = void 0;
+/**
+ * Container that allows to accumulate average of a set of numbers,
+ * without the need to store all of them in memory.
+ *
+ * @experimental
+ */
+class AccumulatingAverage {
+    constructor() {
+        this.total = 0;
+        this.count = 0;
+    }
+    /**
+     * Returns the current average.
+     * Returns 0 if no values have been added.
+     */
+    get average() {
+        if (this.count === 0)
+            return 0;
+        return this.total / this.count;
+    }
+    /**
+     * Adds a new value.
+     */
+    add(value) {
+        this.total += value;
+        this.count++;
+    }
+    reset() {
+        this.total = 0;
+        this.count = 0;
+    }
+}
+exports.AccumulatingAverage = AccumulatingAverage;

package/dist/types.d.ts

@@ -202,7 +202,7 @@ export type MonthId = string;
  *
  * @example 'America/New_York'
  */
-export type IanaTimezone = Branded<string, 'IanaTimezone'>;
+export type IANATimezone = Branded<string, 'IANATimezone'>;
 /**
  * Branded UnixTimestamp in seconds.
  * Extends (compatible with) `number`.

package/dist-esm/datetime/localTime.js

@@ -604,6 +604,9 @@ export class LocalTime {
         // !! Not using toISOString(), as it returns time in UTC, not in local timezone (unexpected!)
         // return this.$date.toISOString().slice(11, seconds ? 19 : 16)
     }
+    toWallTime() {
+        return new WallTime(this.toDateTimeObject());
+    }
     /**
      * Returns e.g: `19840621_1705`
      */
@@ -849,6 +852,8 @@ class LocalTimeFactory {
      * consider caching the Intl.supportedValuesOf values as Set and reuse that.
      */
     isTimezoneValid(tz) {
+        if (tz === 'UTC')
+            return true; // we deliberately consider UTC a valid timezone, while it's mostly used in testing
         return Intl.supportedValuesOf('timeZone').includes(tz);
     }
     sort(items, dir = 'asc', mutate = false) {

package/dist-esm/datetime/wallTime.js

@@ -1,3 +1,5 @@
+import { LocalDate } from './localDate';
+import { localTime } from './localTime';
 /**
  * Representation of a "time on the wall clock",
  * which means "local time, regardless of timezone".
@@ -11,6 +13,24 @@ export class WallTime {
     constructor(obj) {
         Object.assign(this, obj);
     }
+    toLocalDate() {
+        return new LocalDate(this.year, this.month, this.day);
+    }
+    /**
+     * Example:
+     * WallTime is 1984-06-21 17:56:21
+     * .toLocalTime() will return a LocalTime Date instance
+     * holding that time in the local timezone.
+     */
+    toLocalTime() {
+        return localTime.fromDateTimeObject(this);
+    }
+    toJSON() {
+        return this.toISODateTime();
+    }
+    toString() {
+        return this.toISODateTime();
+    }
     /**
      * Returns e.g: `1984-06-21 17:56:21`
      * or (if seconds=false):
@@ -19,6 +39,12 @@ export class WallTime {
     toPretty(seconds = true) {
         return this.toISODate() + ' ' + this.toISOTime(seconds);
     }
+    /**
+     * Returns e.g: `1984-06-21T17:56:21`
+     */
+    toISODateTime() {
+        return (this.toISODate() + 'T' + this.toISOTime());
+    }
     /**
      * Returns e.g: `1984-06-21`, only the date part of DateTime
      */

package/dist-esm/index.js

@@ -50,6 +50,7 @@ export * from './json-schema/jsonSchema.model';
 export * from './json-schema/jsonSchema.util';
 export * from './json-schema/jsonSchemaBuilder';
 export * from './log/commonLogger';
+export * from './math/accumulatingAverage';
 export * from './math/math.util';
 export * from './math/sma';
 export * from './math/stack.util';

package/dist-esm/math/accumulatingAverage.js

@@ -0,0 +1,32 @@
+/**
+ * Container that allows to accumulate average of a set of numbers,
+ * without the need to store all of them in memory.
+ *
+ * @experimental
+ */
+export class AccumulatingAverage {
+    constructor() {
+        this.total = 0;
+        this.count = 0;
+    }
+    /**
+     * Returns the current average.
+     * Returns 0 if no values have been added.
+     */
+    get average() {
+        if (this.count === 0)
+            return 0;
+        return this.total / this.count;
+    }
+    /**
+     * Adds a new value.
+     */
+    add(value) {
+        this.total += value;
+        this.count++;
+    }
+    reset() {
+        this.total = 0;
+        this.count = 0;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturalcycles/js-lib",
-  "version": "14.272.0",
+  "version": "14.274.0",
   "scripts": {
     "prepare": "husky",
     "build": "dev-lib build-esm-cjs",
@@ -21,16 +21,17 @@
   },
   "devDependencies": {
     "@naturalcycles/bench-lib": "^3",
-    "@naturalcycles/dev-lib": "^15",
+    "@naturalcycles/dev-lib": "^17",
     "@naturalcycles/nodejs-lib": "^13",
     "@naturalcycles/time-lib": "^3",
     "@types/crypto-js": "^4",
     "@types/node": "^22",
     "@types/semver": "^7",
+    "@vitest/coverage-v8": "^3",
     "crypto-js": "^4",
-    "jest": "^29",
-    "prettier": "^3",
+    "tsx": "^4.19.3",
     "vitepress": "^1",
+    "vitest": "^3",
     "vue": "^3"
   },
   "files": [

package/src/datetime/localTime.ts

@@ -1,6 +1,7 @@
 import { _assert } from '../error/assert'
 import { _ms } from '../time/time.util'
 import type {
+  IANATimezone,
   Inclusiveness,
   IsoDate,
   IsoDateTime,
@@ -101,7 +102,7 @@ export class LocalTime {
    *
    * @experimental
    */
-  inTimezone(tz: string): WallTime {
+  inTimezone(tz: IANATimezone): WallTime {
     const d = new Date(this.$date.toLocaleString('en-US', { timeZone: tz }))
     return new WallTime({
       year: d.getFullYear(),
@@ -127,7 +128,7 @@ export class LocalTime {
    *
    * https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
    */
-  getUTCOffsetMinutes(tz?: string): NumberOfMinutes {
+  getUTCOffsetMinutes(tz?: IANATimezone): NumberOfMinutes {
     if (tz) {
       // based on: https://stackoverflow.com/a/53652131/4919972
       const nowTime = this.$date.getTime()
@@ -148,14 +149,14 @@ export class LocalTime {
    * If timezone (tz) is specified, e.g `America/New_York`,
    * it will return the UTC offset for that timezone.
    */
-  getUTCOffsetHours(tz?: string): NumberOfHours {
+  getUTCOffsetHours(tz?: IANATimezone): NumberOfHours {
     return Math.round(this.getUTCOffsetMinutes(tz) / 60)
   }
 
   /**
    * Returns e.g `-05:00` for New_York winter time.
    */
-  getUTCOffsetString(tz: string): string {
+  getUTCOffsetString(tz: IANATimezone): string {
     const minutes = this.getUTCOffsetMinutes(tz)
     const hours = Math.trunc(minutes / 60)
     const sign = hours < 0 ? '-' : '+'
@@ -726,6 +727,10 @@ export class LocalTime {
     // return this.$date.toISOString().slice(11, seconds ? 19 : 16)
   }
 
+  toWallTime(): WallTime {
+    return new WallTime(this.toDateTimeObject())
+  }
+
   /**
    * Returns e.g: `19840621_1705`
    */
@@ -982,8 +987,8 @@ class LocalTimeFactory {
    * 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
+  getTimezone(): IANATimezone {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone as IANATimezone
   }
 
   /**
@@ -994,6 +999,7 @@ class LocalTimeFactory {
    * consider caching the Intl.supportedValuesOf values as Set and reuse that.
    */
   isTimezoneValid(tz: string): boolean {
+    if (tz === 'UTC') return true // we deliberately consider UTC a valid timezone, while it's mostly used in testing
     return Intl.supportedValuesOf('timeZone').includes(tz)
   }
 

package/src/datetime/wallTime.ts

@@ -1,5 +1,6 @@
-import { IsoDate } from '../types'
-import { DateTimeObject } from './localTime'
+import { IsoDate, IsoDateTime } from '../types'
+import { LocalDate } from './localDate'
+import { DateTimeObject, LocalTime, localTime } from './localTime'
 
 /**
  * Representation of a "time on the wall clock",
@@ -22,6 +23,28 @@ export class WallTime implements DateTimeObject {
     Object.assign(this, obj)
   }
 
+  toLocalDate(): LocalDate {
+    return new LocalDate(this.year, this.month, this.day)
+  }
+
+  /**
+   * Example:
+   * WallTime is 1984-06-21 17:56:21
+   * .toLocalTime() will return a LocalTime Date instance
+   * holding that time in the local timezone.
+   */
+  toLocalTime(): LocalTime {
+    return localTime.fromDateTimeObject(this)
+  }
+
+  toJSON(): IsoDateTime {
+    return this.toISODateTime()
+  }
+
+  toString(): IsoDateTime {
+    return this.toISODateTime()
+  }
+
   /**
    * Returns e.g: `1984-06-21 17:56:21`
    * or (if seconds=false):
@@ -31,6 +54,13 @@ export class WallTime implements DateTimeObject {
     return this.toISODate() + ' ' + this.toISOTime(seconds)
   }
 
+  /**
+   * Returns e.g: `1984-06-21T17:56:21`
+   */
+  toISODateTime(): IsoDateTime {
+    return (this.toISODate() + 'T' + this.toISOTime()) as IsoDateTime
+  }
+
   /**
    * Returns e.g: `1984-06-21`, only the date part of DateTime
    */

package/src/index.ts

@@ -50,6 +50,7 @@ export * from './json-schema/jsonSchema.model'
 export * from './json-schema/jsonSchema.util'
 export * from './json-schema/jsonSchemaBuilder'
 export * from './log/commonLogger'
+export * from './math/accumulatingAverage'
 export * from './math/math.util'
 export * from './math/sma'
 export * from './math/stack.util'

package/src/math/accumulatingAverage.ts

@@ -0,0 +1,32 @@
+/**
+ * Container that allows to accumulate average of a set of numbers,
+ * without the need to store all of them in memory.
+ *
+ * @experimental
+ */
+export class AccumulatingAverage {
+  total = 0
+  count = 0
+
+  /**
+   * Returns the current average.
+   * Returns 0 if no values have been added.
+   */
+  get average(): number {
+    if (this.count === 0) return 0
+    return this.total / this.count
+  }
+
+  /**
+   * Adds a new value.
+   */
+  add(value: number): void {
+    this.total += value
+    this.count++
+  }
+
+  reset(): void {
+    this.total = 0
+    this.count = 0
+  }
+}

package/src/types.ts

@@ -260,7 +260,7 @@ export type MonthId = string
  *
  * @example 'America/New_York'
  */
-export type IanaTimezone = Branded<string, 'IanaTimezone'>
+export type IANATimezone = Branded<string, 'IANATimezone'>
 
 /**
  * Branded UnixTimestamp in seconds.