@futdevpro/fsm-dynamo 1.20.92 → 1.20.94

package/build-esm/_collections/utils/math/math.util.js

@@ -0,0 +1,183 @@
+/**
+ * this class is a collection of static methods for mathematical operations
+ */
+export class DyFM_Math {
+    /**
+     * returns true if the value is between the min and max
+     *
+     * @example
+     * ```ts
+     * const isBetween = DyFM_Math.between(5, 1, 10);
+     * console.log(isBetween);
+     * ```
+     */
+    static between(value, minExclusive, maxExclusive) {
+        return minExclusive < value && value < maxExclusive;
+    }
+    /**
+     * returns true if the value is between the target and the range
+     *
+     * @example
+     * ```ts
+     * const isAround = DyFM_Math.around(5, 5, 1);
+     * console.log(isAround);
+     * ```
+     */
+    static around(value, target, range) {
+        return this.between(value, target - range, target + range);
+    }
+    static toFixed = this.round;
+    /**
+     * returns a number rounded to the specified number of decimals
+     *
+     * @example
+     * ```ts
+     * const roundedNumber = DyFM_Math.round(1.2345, 2);
+     * console.log(roundedNumber); // 1.23
+     * ```
+     */
+    static round(value, decimals = 2) {
+        if (0 <= decimals) {
+            return Number(value.toFixed(decimals));
+        }
+        else {
+            const factor = Math.pow(10, -decimals);
+            return Math.round(value / factor) * factor;
+        }
+    }
+    /**
+     * returns a number with spaces between the thousands
+     *
+     * @example
+     * ```ts
+     * const numberWithSpaces = DyFM_Math.numberWithSpaces(1000);
+     * console.log(numberWithSpaces); // '1 000'
+     * ```
+     */
+    static numberWithSpaces(x) {
+        return x?.toString()?.replace(/\B(?=(\d{3})+(?!\d))/g, ' ');
+    }
+    /**
+     * returns a number with shorter units
+     *
+     * @example
+     * ```ts
+     * const numberWithShorters = DyFM_Math.numberWithShorters(1000);
+     * console.log(numberWithShorters); // '1.0k'
+     * ```
+     */
+    static numberWithShorters(x) {
+        if (x < 1000) {
+            return x?.toString();
+        }
+        else if (x < 1000000) {
+            return (x / 1000)?.toFixed(1) + 'k';
+        }
+        else if (x < 1000000000) {
+            return (x / 1000000)?.toFixed(2) + 'M';
+        }
+        else {
+            return (x / 1000000000)?.toFixed(3) + 'B';
+        }
+    }
+    /**
+     * returns a number with shorter units and spaces between the thousands
+     *
+     * @example
+     * ```ts
+     * const numberWithShortersAndSpaces = DyFM_Math.numberWithShortersAndSpaces(1000);
+     * console.log(numberWithShortersAndSpaces); // '1.0k'
+     * ```
+     */
+    static numberWithShortersAndSpaces(x) {
+        return this.numberWithShorters(x)?.replace(/\B(?=(\d{3})+(?!\d))/g, ' ');
+    }
+    /**
+     * BFR-WARFACTORY-018 — abbreviation that also works for NEGATIVE numbers.
+     *
+     * `numberWithShorters` tests `x < 1000` first, so every negative value falls into the pass-through
+     * branch and is never abbreviated (`-15000` -> `"-15000"`). Fixing that in place would silently
+     * change a money surface: `numberWithShortersAndSpaces` is what renders the user's token balance in
+     * `fdp-token-service` and in the `dynamo-builder-models` client template that every generated app
+     * inherits — `-15 000` would become `-15.0k`. Whether a negative balance should read that way is an
+     * OWNER decision, not a framework one, so the existing methods are left untouched and this is a new
+     * method the caller opts into.
+     *
+     * The two open formatting questions are PARAMETERS here rather than a unilateral choice:
+     * `decimals` ('increasing' reproduces the legacy 1/2/3 pattern; a number pins every unit to it) and
+     * `unitCase` ('lower' keeps the legacy `k`; 'upper' gives the game-HUD `K`). The defaults reproduce
+     * `numberWithShorters` exactly for positive input, so this is a strict superset.
+     *
+     * @example
+     * ```ts
+     * DyFM_Math.numberWithShortersSigned(-15000);                                  // '-15.0k'
+     * DyFM_Math.numberWithShortersSigned(-15000, { decimals: 1, unitCase: 'upper' }); // '-15.0K'
+     * DyFM_Math.numberWithShortersSigned(1500000000, { decimals: 1 });             // '1.5B'
+     * ```
+     */
+    static numberWithShortersSigned(x, options = {}) {
+        if (x === null || x === undefined || Number.isNaN(x)) {
+            return x?.toString();
+        }
+        const sign = x < 0 ? '-' : '';
+        const magnitude = Math.abs(x);
+        const decimals = options.decimals ?? 'increasing';
+        const upper = options.unitCase === 'upper';
+        if (magnitude < 1000) {
+            return x.toString();
+        }
+        const units = [
+            { limit: 1000000, divisor: 1000, letter: upper ? 'K' : 'k', legacyDecimals: 1 },
+            { limit: 1000000000, divisor: 1000000, letter: 'M', legacyDecimals: 2 },
+            { limit: Infinity, divisor: 1000000000, letter: 'B', legacyDecimals: 3 },
+        ];
+        for (const unit of units) {
+            if (magnitude < unit.limit) {
+                const used = decimals === 'increasing' ? unit.legacyDecimals : decimals;
+                return `${sign}${(magnitude / unit.divisor).toFixed(used)}${unit.letter}`;
+            }
+        }
+        return x.toString();
+    }
+    /**
+     * BFR-WARFACTORY-018 — the signed abbreviation with thousand-separator spaces, mirroring
+     * `numberWithShortersAndSpaces`. Only the digits before the unit letter are grouped, and the sign
+     * is never separated from the number.
+     *
+     * @example
+     * ```ts
+     * DyFM_Math.numberWithShortersSignedAndSpaces(-15000); // '-15.0k'
+     * ```
+     */
+    static numberWithShortersSignedAndSpaces(x, options = {}) {
+        return this.numberWithShortersSigned(x, options)?.replace(/\B(?=(\d{3})+(?!\d))/g, ' ');
+    }
+    /**
+     * returns a number with spaces between the thousands
+     *
+     * @example
+     * ```ts
+     * const floatingNumberWithSpaces = DyFM_Math.floatingNumberWithSpaces(1234.567);
+     * console.log(floatingNumberWithSpaces); // '1 234.567'
+     * ```
+     */
+    static floatingNumberWithSpaces(x) {
+        const parts = x?.toString()?.split('.');
+        parts[0] = parts?.[0]?.replace(/\B(?=(\d{3})+(?!\d))/g, ' ');
+        return parts?.join('.');
+    }
+    /**
+     * returns a number with spaces between the thousands
+     *
+     * @example
+     * ```ts
+     * const decimals = DyFM_Math.decimals(1234.567, ',');
+     * console.log(decimals); // '1,234.567'
+     * ```
+     */
+    static decimals(x, useSpacer = ',') {
+        const parts = x?.toString()?.split('.');
+        parts[0] = parts?.[0]?.replace(/\B(?=(\d{3})+(?!\d))/g, useSpacer);
+        return parts?.join('.');
+    }
+}

package/build-esm/_collections/utils/math/random.util.js

@@ -0,0 +1,117 @@
+import { DyFM_Log } from '../log.util';
+/**
+ * this class is a collection of static methods for random operations
+ */
+export class DyFM_Random {
+    /**
+     * returns a random weighted integer between the min and max
+     *
+     * @example
+     * ```ts
+     * const randomWeightedInt = DyFM_Random.getRandomWeightedInt(1, 10, [
+     *   { chance: 0.1, result: 1 },
+     *   { chance: 0.3, result: 2 },
+     *   { chance: 0.6, result: 3 }
+     * ]);
+     * console.log(randomWeightedInt);
+     * ```
+     */
+    static getRandomWeightedInt(min, max, weights) {
+        weights = weights.sort((a, b) => b.chance - a.chance);
+        let weightChanceSum = 0;
+        weights.forEach((weight) => { weightChanceSum += weight.chance; });
+        if (1 < weightChanceSum) {
+            weights.forEach((weights) => { weights.chance = weights.chance / weightChanceSum; });
+        }
+        const randomChance = Math.random();
+        let result;
+        let chancer = 0;
+        for (let i = 0; i < weights.length && result === undefined; i++) {
+            chancer += weights[i].chance;
+            if (randomChance < chancer) {
+                result = weights[i].result;
+            }
+        }
+        if (result !== undefined) {
+            return result;
+        }
+        else {
+            return this.getRandomInt(min, max);
+        }
+    }
+    /**
+     * returns a random integer between the min and max
+     * @param min - the minimum value (inclusive)
+     * @param max - the maximum value (inclusive)
+     * @returns a random integer between the min and max
+     *
+     * @example
+     * ```ts
+     * const randomInt = DyFM_Random.getRandomInt(1, 10);
+     * console.log(randomInt); // 5
+     * ```
+     */
+    static getRandomInt(min, max) {
+        return min + Math.round((max - min) * Math.random());
+    }
+    /**
+     * returns null if list is empty
+     * @param list
+     * @returns
+     *
+     * @example
+     * ```ts
+     * const randomListElement = DyFM_Random.getRandomListElement([1, 2, 3, 4, 5]);
+     * console.log(randomListElement); // 3
+     * ```
+     */
+    static getRandomListElement(list) {
+        if (0 < list.length) {
+            return list[this.getRandomInt(0, list.length - 1)];
+        }
+        else {
+            return null;
+        }
+    }
+    /**
+     * returns a random weighted element from the list
+     * (returns null if list is empty)
+     * @param weights
+     * @returns
+     *
+     * @example
+     * ```ts
+     * const randomWeightedElement = DyFM_Random.getRandomWeighted([
+     *   { chance: 0.1, result: '1' },
+     *   { chance: 0.3, result: '2' },
+     *   { chance: 0.6, result: '3' }
+     * ]);
+     */
+    static getRandomWeighted(weights) {
+        if (!weights?.length) {
+            return null;
+        }
+        weights = weights.sort((a, b) => b.chance - a.chance);
+        let weightChanceSum = 0;
+        weights.forEach((weight) => {
+            weightChanceSum += weight.chance;
+        });
+        weights.forEach((weights) => {
+            weights.chance = weights.chance / weightChanceSum;
+        });
+        const randomChance = Math.random();
+        let result;
+        let chancer = 0;
+        for (let i = 0; i < weights.length && result === undefined; i++) {
+            chancer += weights[i].chance;
+            if (randomChance < chancer) {
+                result = weights[i].result;
+            }
+        }
+        if (result === undefined) {
+            DyFM_Log.error('DyFM_Random failed to get a random weighted element from the list');
+            return null;
+        }
+        return result;
+    }
+}

package/build-esm/_collections/utils/math/trigonometry.util.js

@@ -0,0 +1,89 @@
+export class DyFM_Trigonometry {
+    /**
+     * Befogó
+     * a Befogó mérete az átfogó, és a befogóval szemközti szög alapján
+     * a szemközti szög értéke opcionális
+     * (amennyiben nem adjuk meg, 45 fokos szöggel számolunk)
+     * @param c átfogó
+     * @param angle a befogó oldallal szemközti szög (fokban)
+     * @returns befogó
+     *
+     * @example
+     * ```ts
+     * const clamp = DyFM_Trigonometry.getClamp(10, 30);
+     * console.log(clamp); // 5
+     * ```
+     */
+    static getClamp(c, angle) {
+        angle = angle !== undefined ? angle : 45;
+        return Math.sin(this.angleToRadians(angle)) * c;
+    }
+    /**
+     * Befogó
+     * a Befogó mérete az átfogó és a másik befogó alapján
+     * @param a befogó
+     * @param c átfogó
+     * @returns befogó
+     *
+     * @example
+     * ```ts
+     * const clamp = DyFM_Trigonometry.getClampByClampAndHypotenuse(6, 10);
+     * console.log(clamp); // 8
+     * ```
+     */
+    static getClampByClampAndHypotenuse(a, c) {
+        if (a > c) {
+            throw {
+                errorMessage: `getClampByClampAndHypotenuse error hypotenuse is smaller than clamp (a:${a} > c:${c})`
+            };
+        }
+        return Math.sqrt((c * c) - (a * a));
+    }
+    /**
+     * Átfogó
+     * az Átfogó mérete a befogók alapján
+     * a második befogó értéke opcionális
+     * (amennyiben nem adjuk meg, egyenlő szárú háromszöggel számolunk)
+     * @param a egyik befogó
+     * @param b másik befogó
+     * @returns átfogó
+     *
+     * @example
+     * ```ts
+     * const hypotenuse = DyFM_Trigonometry.getHypotenuse(3, 4);
+     * console.log(hypotenuse); // 5
+     * ```
+     */
+    static getHypotenuse(a, b) {
+        b = b !== undefined ? b : a;
+        return Math.sqrt((a * a) + (b * b));
+    }
+    /**
+     * Szög fokmértéket átalakítja radiánsra
+     * @param angle szög fok
+     * @returns szög radiáns
+     *
+     * @example
+     * ```ts
+     * const radians = DyFM_Trigonometry.angleToRadians(180);
+     * console.log(radians); // 3.141592653589793
+     * ```
+     */
+    static angleToRadians(angle) {
+        return angle * Math.PI / 180;
+    }
+    /**
+     * Szög radiáns mértéket átalakítja fokra
+     * @param radians szög radiáns
+     * @returns szög fok
+     *
+     * @example
+     * ```ts
+     * const angle = DyFM_Trigonometry.radiansToAngle(3.141592653589793);
+     * console.log(angle); // 180
+     * ```
+     */
+    static radiansToAngle(radians) {
+        return radians / Math.PI * 180;
+    }
+}