@naturalcycles/js-lib 14.237.0 → 14.239.0

package/dist/datetime/localDate.d.ts

@@ -57,6 +57,10 @@ export declare class LocalDate {
      * Checks if this localDate is same or younger (>=) than "today" by X units.
      */
     isSameOrYoungerThan(n: number, unit: LocalDateUnit, today?: LocalDateInput): boolean;
+    getAgeInYears(today?: LocalDateInput): number;
+    getAgeInMonths(today?: LocalDateInput): number;
+    getAgeInDays(today?: LocalDateInput): number;
+    getAgeIn(unit: LocalDateUnit, today?: LocalDateInput): number;
     /**
      * Returns 1 if this > d
      * returns 0 if they are equal

package/dist/datetime/localDate.js

@@ -108,6 +108,18 @@ class LocalDate {
     isSameOrYoungerThan(n, unit, today) {
         return this.isSameOrAfter(exports.localDate.of(today || new Date()).plus(-n, unit));
     }
+    getAgeInYears(today) {
+        return this.getAgeIn('year', today);
+    }
+    getAgeInMonths(today) {
+        return this.getAgeIn('month', today);
+    }
+    getAgeInDays(today) {
+        return this.getAgeIn('day', today);
+    }
+    getAgeIn(unit, today) {
+        return exports.localDate.of(today || new Date()).diff(this, unit);
+    }
     /**
      * Returns 1 if this > d
      * returns 0 if they are equal

package/dist/datetime/localTime.d.ts

@@ -163,6 +163,13 @@ export declare class LocalTime {
      * Checks if this localTime is same or younger (>=) than "now" by X units.
      */
     isSameOrYoungerThan(n: number, unit: LocalTimeUnit, now?: LocalTimeInput): boolean;
+    getAgeInYears(now?: LocalTimeInput): number;
+    getAgeInMonths(now?: LocalTimeInput): number;
+    getAgeInDays(now?: LocalTimeInput): number;
+    getAgeInHours(now?: LocalTimeInput): number;
+    getAgeInMinutes(now?: LocalTimeInput): number;
+    getAgeInSeconds(now?: LocalTimeInput): number;
+    getAgeIn(unit: LocalTimeUnit, now?: LocalTimeInput): number;
     /**
      * Returns 1 if this > d
      * returns 0 if they are equal

package/dist/datetime/localTime.js

@@ -418,6 +418,27 @@ class LocalTime {
     isSameOrYoungerThan(n, unit, now) {
         return this.isSameOrAfter(exports.localTime.of(now ?? new Date()).plus(-n, unit));
     }
+    getAgeInYears(now) {
+        return this.getAgeIn('year', now);
+    }
+    getAgeInMonths(now) {
+        return this.getAgeIn('month', now);
+    }
+    getAgeInDays(now) {
+        return this.getAgeIn('day', now);
+    }
+    getAgeInHours(now) {
+        return this.getAgeIn('hour', now);
+    }
+    getAgeInMinutes(now) {
+        return this.getAgeIn('minute', now);
+    }
+    getAgeInSeconds(now) {
+        return this.getAgeIn('second', now);
+    }
+    getAgeIn(unit, now) {
+        return exports.localTime.of(now ?? new Date()).diff(this, unit);
+    }
     /**
      * Returns 1 if this > d
      * returns 0 if they are equal

package/dist/semver.d.ts

@@ -18,12 +18,10 @@ export type SemverTokens = [major: number, minor: number, patch: number];
  */
 export declare class Semver {
     tokens: SemverTokens;
-    private constructor();
+    constructor(tokens: SemverTokens);
     get major(): number;
     get minor(): number;
     get patch(): number;
-    static of(input: SemverInput): Semver;
-    static parseOrNull(input: SemverInput | undefined | null): Semver | null;
     isAfter: (other: SemverInput) => boolean;
     isSameOrAfter: (other: SemverInput) => boolean;
     isBefore: (other: SemverInput) => boolean;
@@ -38,10 +36,32 @@ export declare class Semver {
     toJSON: () => string;
     toString(): string;
 }
-/**
- * Shortcut for Semver.of(input)
- */
-export declare function _semver(input: SemverInput): Semver;
+declare class SemverFactory {
+    of(input: SemverInput): Semver;
+    parseOrNull(input: SemverInput | undefined | null): Semver | null;
+    /**
+     * Returns the highest (max) Semver from the array, or undefined if the array is empty.
+     */
+    maxOrUndefined(items: SemverInput[]): Semver | undefined;
+    /**
+     * Returns the highest Semver from the array.
+     * Throws if the array is empty.
+     */
+    max(items: SemverInput[]): Semver;
+    /**
+     * Returns the lowest (min) Semver from the array, or undefined if the array is empty.
+     */
+    minOrUndefined(items: SemverInput[]): Semver | undefined;
+    /**
+     * Returns the lowest Semver from the array.
+     * Throws if the array is empty.
+     */
+    min(items: SemverInput[]): Semver;
+}
+interface SemverFn extends SemverFactory {
+    (input: SemverInput): Semver;
+}
+export declare const semver2: SemverFn;
 /**
  * Returns 1 if a > b
  * returns 0 if they are equal
@@ -51,4 +71,5 @@ export declare function _semver(input: SemverInput): Semver;
  *
  * Credit: https://stackoverflow.com/a/47159772/4919972
  */
-export declare function _semverCompare(a: string, b: string): -1 | 0 | 1;
+export declare function _quickSemverCompare(a: string, b: string): -1 | 0 | 1;
+export {};

package/dist/semver.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports._semverCompare = exports._semver = exports.Semver = void 0;
+exports._quickSemverCompare = exports.semver2 = exports.Semver = void 0;
 const range_1 = require("./array/range");
 const assert_1 = require("./error/assert");
 /**
@@ -38,29 +38,13 @@ class Semver {
     get patch() {
         return this.tokens[2];
     }
-    static of(input) {
-        const s = this.parseOrNull(input);
-        (0, assert_1._assert)(s !== null, `Cannot parse "${input}" into Semver`, {
-            userFriendly: true,
-            input,
-        });
-        return s;
-    }
-    static parseOrNull(input) {
-        if (!input)
-            return null;
-        if (input instanceof Semver)
-            return input;
-        const t = input.split('.');
-        return new Semver((0, range_1._range)(3).map(i => parseInt(t[i]) || 0));
-    }
     /**
      * Returns 1 if this > other
      * returns 0 if they are equal
      * returns -1 if this < other
      */
     cmp(other) {
-        const { tokens } = Semver.of(other);
+        const { tokens } = exports.semver2.of(other);
         for (let i = 0; i < 3; i++) {
             if (this.tokens[i] < tokens[i])
                 return -1;
@@ -74,13 +58,57 @@ class Semver {
     }
 }
 exports.Semver = Semver;
-/**
- * Shortcut for Semver.of(input)
- */
-function _semver(input) {
-    return Semver.of(input);
+class SemverFactory {
+    of(input) {
+        const s = this.parseOrNull(input);
+        (0, assert_1._assert)(s !== null, `Cannot parse "${input}" into Semver`, {
+            userFriendly: true,
+            input,
+        });
+        return s;
+    }
+    parseOrNull(input) {
+        if (!input)
+            return null;
+        if (input instanceof Semver)
+            return input;
+        const t = input.split('.');
+        return new Semver((0, range_1._range)(3).map(i => parseInt(t[i]) || 0));
+    }
+    /**
+     * Returns the highest (max) Semver from the array, or undefined if the array is empty.
+     */
+    maxOrUndefined(items) {
+        return items.length ? this.max(items) : undefined;
+    }
+    /**
+     * Returns the highest Semver from the array.
+     * Throws if the array is empty.
+     */
+    max(items) {
+        (0, assert_1._assert)(items.length, 'semver.max called on empty array');
+        return items.map(i => this.of(i)).reduce((max, item) => (max.isSameOrAfter(item) ? max : item));
+    }
+    /**
+     * Returns the lowest (min) Semver from the array, or undefined if the array is empty.
+     */
+    minOrUndefined(items) {
+        return items.length ? this.min(items) : undefined;
+    }
+    /**
+     * Returns the lowest Semver from the array.
+     * Throws if the array is empty.
+     */
+    min(items) {
+        (0, assert_1._assert)(items.length, 'semver.min called on empty array');
+        return items.map(i => this.of(i)).reduce((min, item) => (min.isSameOrBefore(item) ? min : item));
+    }
 }
-exports._semver = _semver;
+const semverFactory = new SemverFactory();
+exports.semver2 = semverFactory.of.bind(semverFactory);
+// The line below is the blackest of black magic I have ever written in 2024.
+// And probably 2023 as well.
+Object.setPrototypeOf(exports.semver2, semverFactory);
 /**
  * Returns 1 if a > b
  * returns 0 if they are equal
@@ -90,7 +118,7 @@ exports._semver = _semver;
  *
  * Credit: https://stackoverflow.com/a/47159772/4919972
  */
-function _semverCompare(a, b) {
+function _quickSemverCompare(a, b) {
     const t1 = a.split('.');
     const t2 = b.split('.');
     const s1 = (0, range_1._range)(3)
@@ -101,4 +129,4 @@ function _semverCompare(a, b) {
         .join('');
     return s1 < s2 ? -1 : s1 > s2 ? 1 : 0;
 }
-exports._semverCompare = _semverCompare;
+exports._quickSemverCompare = _quickSemverCompare;

package/dist-esm/datetime/localDate.js

@@ -105,6 +105,18 @@ export class LocalDate {
     isSameOrYoungerThan(n, unit, today) {
         return this.isSameOrAfter(localDate.of(today || new Date()).plus(-n, unit));
     }
+    getAgeInYears(today) {
+        return this.getAgeIn('year', today);
+    }
+    getAgeInMonths(today) {
+        return this.getAgeIn('month', today);
+    }
+    getAgeInDays(today) {
+        return this.getAgeIn('day', today);
+    }
+    getAgeIn(unit, today) {
+        return localDate.of(today || new Date()).diff(this, unit);
+    }
     /**
      * Returns 1 if this > d
      * returns 0 if they are equal

package/dist-esm/datetime/localTime.js

@@ -415,6 +415,27 @@ export class LocalTime {
     isSameOrYoungerThan(n, unit, now) {
         return this.isSameOrAfter(localTime.of(now ?? new Date()).plus(-n, unit));
     }
+    getAgeInYears(now) {
+        return this.getAgeIn('year', now);
+    }
+    getAgeInMonths(now) {
+        return this.getAgeIn('month', now);
+    }
+    getAgeInDays(now) {
+        return this.getAgeIn('day', now);
+    }
+    getAgeInHours(now) {
+        return this.getAgeIn('hour', now);
+    }
+    getAgeInMinutes(now) {
+        return this.getAgeIn('minute', now);
+    }
+    getAgeInSeconds(now) {
+        return this.getAgeIn('second', now);
+    }
+    getAgeIn(unit, now) {
+        return localTime.of(now ?? new Date()).diff(this, unit);
+    }
     /**
      * Returns 1 if this > d
      * returns 0 if they are equal

package/dist-esm/semver.js

@@ -35,29 +35,13 @@ export class Semver {
     get patch() {
         return this.tokens[2];
     }
-    static of(input) {
-        const s = this.parseOrNull(input);
-        _assert(s !== null, `Cannot parse "${input}" into Semver`, {
-            userFriendly: true,
-            input,
-        });
-        return s;
-    }
-    static parseOrNull(input) {
-        if (!input)
-            return null;
-        if (input instanceof Semver)
-            return input;
-        const t = input.split('.');
-        return new Semver(_range(3).map(i => parseInt(t[i]) || 0));
-    }
     /**
      * Returns 1 if this > other
      * returns 0 if they are equal
      * returns -1 if this < other
      */
     cmp(other) {
-        const { tokens } = Semver.of(other);
+        const { tokens } = semver2.of(other);
         for (let i = 0; i < 3; i++) {
             if (this.tokens[i] < tokens[i])
                 return -1;
@@ -70,12 +54,57 @@ export class Semver {
         return this.tokens.join('.');
     }
 }
-/**
- * Shortcut for Semver.of(input)
- */
-export function _semver(input) {
-    return Semver.of(input);
+class SemverFactory {
+    of(input) {
+        const s = this.parseOrNull(input);
+        _assert(s !== null, `Cannot parse "${input}" into Semver`, {
+            userFriendly: true,
+            input,
+        });
+        return s;
+    }
+    parseOrNull(input) {
+        if (!input)
+            return null;
+        if (input instanceof Semver)
+            return input;
+        const t = input.split('.');
+        return new Semver(_range(3).map(i => parseInt(t[i]) || 0));
+    }
+    /**
+     * Returns the highest (max) Semver from the array, or undefined if the array is empty.
+     */
+    maxOrUndefined(items) {
+        return items.length ? this.max(items) : undefined;
+    }
+    /**
+     * Returns the highest Semver from the array.
+     * Throws if the array is empty.
+     */
+    max(items) {
+        _assert(items.length, 'semver.max called on empty array');
+        return items.map(i => this.of(i)).reduce((max, item) => (max.isSameOrAfter(item) ? max : item));
+    }
+    /**
+     * Returns the lowest (min) Semver from the array, or undefined if the array is empty.
+     */
+    minOrUndefined(items) {
+        return items.length ? this.min(items) : undefined;
+    }
+    /**
+     * Returns the lowest Semver from the array.
+     * Throws if the array is empty.
+     */
+    min(items) {
+        _assert(items.length, 'semver.min called on empty array');
+        return items.map(i => this.of(i)).reduce((min, item) => (min.isSameOrBefore(item) ? min : item));
+    }
 }
+const semverFactory = new SemverFactory();
+export const semver2 = semverFactory.of.bind(semverFactory);
+// The line below is the blackest of black magic I have ever written in 2024.
+// And probably 2023 as well.
+Object.setPrototypeOf(semver2, semverFactory);
 /**
  * Returns 1 if a > b
  * returns 0 if they are equal
@@ -85,7 +114,7 @@ export function _semver(input) {
  *
  * Credit: https://stackoverflow.com/a/47159772/4919972
  */
-export function _semverCompare(a, b) {
+export function _quickSemverCompare(a, b) {
     const t1 = a.split('.');
     const t2 = b.split('.');
     const s1 = _range(3)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturalcycles/js-lib",
-  "version": "14.237.0",
+  "version": "14.239.0",
   "scripts": {
     "prepare": "husky",
     "build-prod": "build-prod-esm-cjs",
@@ -21,6 +21,7 @@
     "@naturalcycles/time-lib": "^3.5.1",
     "@types/crypto-js": "^4.1.1",
     "@types/node": "^20.1.0",
+    "@types/semver": "^7.5.8",
     "crypto-js": "^4.1.1",
     "jest": "^29.0.0",
     "prettier": "^3.0.0",

package/src/datetime/localDate.ts

@@ -141,6 +141,19 @@ export class LocalDate {
     return this.isSameOrAfter(localDate.of(today || new Date()).plus(-n, unit))
   }
 
+  getAgeInYears(today?: LocalDateInput): number {
+    return this.getAgeIn('year', today)
+  }
+  getAgeInMonths(today?: LocalDateInput): number {
+    return this.getAgeIn('month', today)
+  }
+  getAgeInDays(today?: LocalDateInput): number {
+    return this.getAgeIn('day', today)
+  }
+  getAgeIn(unit: LocalDateUnit, today?: LocalDateInput): number {
+    return localDate.of(today || new Date()).diff(this, unit)
+  }
+
   /**
    * Returns 1 if this > d
    * returns 0 if they are equal

package/src/datetime/localTime.ts

@@ -500,6 +500,28 @@ export class LocalTime {
     return this.isSameOrAfter(localTime.of(now ?? new Date()).plus(-n, unit))
   }
 
+  getAgeInYears(now?: LocalTimeInput): number {
+    return this.getAgeIn('year', now)
+  }
+  getAgeInMonths(now?: LocalTimeInput): number {
+    return this.getAgeIn('month', now)
+  }
+  getAgeInDays(now?: LocalTimeInput): number {
+    return this.getAgeIn('day', now)
+  }
+  getAgeInHours(now?: LocalTimeInput): number {
+    return this.getAgeIn('hour', now)
+  }
+  getAgeInMinutes(now?: LocalTimeInput): number {
+    return this.getAgeIn('minute', now)
+  }
+  getAgeInSeconds(now?: LocalTimeInput): number {
+    return this.getAgeIn('second', now)
+  }
+  getAgeIn(unit: LocalTimeUnit, now?: LocalTimeInput): number {
+    return localTime.of(now ?? new Date()).diff(this, unit)
+  }
+
   /**
    * Returns 1 if this > d
    * returns 0 if they are equal

package/src/semver.ts

@@ -21,7 +21,7 @@ export type SemverTokens = [major: number, minor: number, patch: number]
  * @experimental
  */
 export class Semver {
-  private constructor(public tokens: SemverTokens) {}
+  constructor(public tokens: SemverTokens) {}
 
   get major(): number {
     return this.tokens[0]
@@ -33,25 +33,6 @@ export class Semver {
     return this.tokens[2]
   }
 
-  static of(input: SemverInput): Semver {
-    const s = this.parseOrNull(input)
-
-    _assert(s !== null, `Cannot parse "${input}" into Semver`, {
-      userFriendly: true,
-      input,
-    })
-
-    return s
-  }
-
-  static parseOrNull(input: SemverInput | undefined | null): Semver | null {
-    if (!input) return null
-    if (input instanceof Semver) return input
-
-    const t = input.split('.')
-    return new Semver(_range(3).map(i => parseInt(t[i]!) || 0) as SemverTokens)
-  }
-
   isAfter = (other: SemverInput): boolean => this.cmp(other) > 0
   isSameOrAfter = (other: SemverInput): boolean => this.cmp(other) >= 0
   isBefore = (other: SemverInput): boolean => this.cmp(other) < 0
@@ -64,7 +45,7 @@ export class Semver {
    * returns -1 if this < other
    */
   cmp(other: SemverInput): -1 | 0 | 1 {
-    const { tokens } = Semver.of(other)
+    const { tokens } = semver2.of(other)
     for (let i = 0; i < 3; i++) {
       if (this.tokens[i]! < tokens[i]!) return -1
       if (this.tokens[i]! > tokens[i]!) return 1
@@ -79,13 +60,71 @@ export class Semver {
   }
 }
 
-/**
- * Shortcut for Semver.of(input)
- */
-export function _semver(input: SemverInput): Semver {
-  return Semver.of(input)
+class SemverFactory {
+  of(input: SemverInput): Semver {
+    const s = this.parseOrNull(input)
+
+    _assert(s !== null, `Cannot parse "${input}" into Semver`, {
+      userFriendly: true,
+      input,
+    })
+
+    return s
+  }
+
+  parseOrNull(input: SemverInput | undefined | null): Semver | null {
+    if (!input) return null
+    if (input instanceof Semver) return input
+
+    const t = input.split('.')
+    return new Semver(_range(3).map(i => parseInt(t[i]!) || 0) as SemverTokens)
+  }
+
+  /**
+   * Returns the highest (max) Semver from the array, or undefined if the array is empty.
+   */
+  maxOrUndefined(items: SemverInput[]): Semver | undefined {
+    return items.length ? this.max(items) : undefined
+  }
+
+  /**
+   * Returns the highest Semver from the array.
+   * Throws if the array is empty.
+   */
+  max(items: SemverInput[]): Semver {
+    _assert(items.length, 'semver.max called on empty array')
+    return items.map(i => this.of(i)).reduce((max, item) => (max.isSameOrAfter(item) ? max : item))
+  }
+
+  /**
+   * Returns the lowest (min) Semver from the array, or undefined if the array is empty.
+   */
+  minOrUndefined(items: SemverInput[]): Semver | undefined {
+    return items.length ? this.min(items) : undefined
+  }
+
+  /**
+   * Returns the lowest Semver from the array.
+   * Throws if the array is empty.
+   */
+  min(items: SemverInput[]): Semver {
+    _assert(items.length, 'semver.min called on empty array')
+    return items.map(i => this.of(i)).reduce((min, item) => (min.isSameOrBefore(item) ? min : item))
+  }
+}
+
+interface SemverFn extends SemverFactory {
+  (input: SemverInput): Semver
 }
 
+const semverFactory = new SemverFactory()
+
+export const semver2 = semverFactory.of.bind(semverFactory) as SemverFn
+
+// The line below is the blackest of black magic I have ever written in 2024.
+// And probably 2023 as well.
+Object.setPrototypeOf(semver2, semverFactory)
+
 /**
  * Returns 1 if a > b
  * returns 0 if they are equal
@@ -95,7 +134,7 @@ export function _semver(input: SemverInput): Semver {
  *
  * Credit: https://stackoverflow.com/a/47159772/4919972
  */
-export function _semverCompare(a: string, b: string): -1 | 0 | 1 {
+export function _quickSemverCompare(a: string, b: string): -1 | 0 | 1 {
   const t1 = a.split('.')
   const t2 = b.split('.')
   const s1 = _range(3)