@naturalcycles/js-lib 14.271.2 → 14.273.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;
@@ -304,7 +304,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

@@ -853,6 +853,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/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/string/string.util.d.ts

@@ -1,9 +1,18 @@
 /**
  * Converts the first character of string to upper case and the remaining to lower case.
+ * Returns a type-safe capitalized string.
  */
-export declare function _capitalize(s?: string): string;
-export declare function _upperFirst(s?: string): string;
-export declare function _lowerFirst(s: string): string;
+export declare function _capitalize(s?: string): Capitalize<string>;
+/**
+ * Convert a string to a type-safe uppercase string.
+ */
+export declare function _toUpperCase(s: string): Uppercase<string>;
+/**
+ * Convert a string to a type-safe lowercase string.
+ */
+export declare function _toLowercase(s: string): Lowercase<string>;
+export declare function _upperFirst(s?: string): Capitalize<string>;
+export declare function _lowerFirst(s: string): Uncapitalize<string>;
 /**
  * Like String.split(), but with limit, returning the tail together with last element.
  *

package/dist/string/string.util.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports._capitalize = _capitalize;
+exports._toUpperCase = _toUpperCase;
+exports._toLowercase = _toLowercase;
 exports._upperFirst = _upperFirst;
 exports._lowerFirst = _lowerFirst;
 exports._split = _split;
@@ -15,15 +17,28 @@ exports._substringBetweenLast = _substringBetweenLast;
 exports._nl2br = _nl2br;
 /**
  * Converts the first character of string to upper case and the remaining to lower case.
+ * Returns a type-safe capitalized string.
  */
 function _capitalize(s = '') {
-    return s.charAt(0).toUpperCase() + s.slice(1).toLowerCase();
+    return (s.charAt(0).toUpperCase() + s.slice(1).toLowerCase());
+}
+/**
+ * Convert a string to a type-safe uppercase string.
+ */
+function _toUpperCase(s) {
+    return s.toUpperCase();
+}
+/**
+ * Convert a string to a type-safe lowercase string.
+ */
+function _toLowercase(s) {
+    return s.toLowerCase();
 }
 function _upperFirst(s = '') {
-    return s.charAt(0).toUpperCase() + s.slice(1);
+    return (s.charAt(0).toUpperCase() + s.slice(1));
 }
 function _lowerFirst(s) {
-    return s.charAt(0).toLowerCase() + s.slice(1);
+    return (s.charAt(0).toLowerCase() + s.slice(1));
 }
 /**
  * Like String.split(), but with limit, returning the tail together with last element.

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

@@ -849,6 +849,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/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/dist-esm/string/string.util.js

@@ -1,14 +1,27 @@
 /**
  * Converts the first character of string to upper case and the remaining to lower case.
+ * Returns a type-safe capitalized string.
  */
 export function _capitalize(s = '') {
-    return s.charAt(0).toUpperCase() + s.slice(1).toLowerCase();
+    return (s.charAt(0).toUpperCase() + s.slice(1).toLowerCase());
+}
+/**
+ * Convert a string to a type-safe uppercase string.
+ */
+export function _toUpperCase(s) {
+    return s.toUpperCase();
+}
+/**
+ * Convert a string to a type-safe lowercase string.
+ */
+export function _toLowercase(s) {
+    return s.toLowerCase();
 }
 export function _upperFirst(s = '') {
-    return s.charAt(0).toUpperCase() + s.slice(1);
+    return (s.charAt(0).toUpperCase() + s.slice(1));
 }
 export function _lowerFirst(s) {
-    return s.charAt(0).toLowerCase() + s.slice(1);
+    return (s.charAt(0).toLowerCase() + s.slice(1));
 }
 /**
  * Like String.split(), but with limit, returning the tail together with last element.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturalcycles/js-lib",
-  "version": "14.271.2",
+  "version": "14.273.0",
   "scripts": {
     "prepare": "husky",
     "build": "dev-lib build-esm-cjs",

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 ? '-' : '+'
@@ -982,8 +983,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 +995,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/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/string/string.util.ts

@@ -1,16 +1,31 @@
 /**
  * Converts the first character of string to upper case and the remaining to lower case.
+ * Returns a type-safe capitalized string.
  */
-export function _capitalize(s = ''): string {
-  return s.charAt(0).toUpperCase() + s.slice(1).toLowerCase()
+export function _capitalize(s = ''): Capitalize<string> {
+  return (s.charAt(0).toUpperCase() + s.slice(1).toLowerCase()) as Capitalize<string>
 }
 
-export function _upperFirst(s = ''): string {
-  return s.charAt(0).toUpperCase() + s.slice(1)
+/**
+ * Convert a string to a type-safe uppercase string.
+ */
+export function _toUpperCase(s: string): Uppercase<string> {
+  return s.toUpperCase() as Uppercase<string>
+}
+
+/**
+ * Convert a string to a type-safe lowercase string.
+ */
+export function _toLowercase(s: string): Lowercase<string> {
+  return s.toLowerCase() as Lowercase<string>
+}
+
+export function _upperFirst(s = ''): Capitalize<string> {
+  return (s.charAt(0).toUpperCase() + s.slice(1)) as Capitalize<string>
 }
 
-export function _lowerFirst(s: string): string {
-  return s.charAt(0).toLowerCase() + s.slice(1)
+export function _lowerFirst(s: string): Uncapitalize<string> {
+  return (s.charAt(0).toLowerCase() + s.slice(1)) as Uncapitalize<string>
 }
 
 /**

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.