@futdevpro/fsm-dynamo 1.10.37 → 1.10.39

package/src/_collections/utils/log.util.ts

@@ -11,6 +11,10 @@ export type DyFM_L = DyFM_Log;
  */
 export class DyFM_Log {
 
+  /**
+   * Sets the style of the console log.
+   * @param styles - The styles to set.
+   */
   static setStyle(styles: DyFM_LogStyle[]): void {
     let styleSets = '';
 
@@ -20,10 +24,21 @@ export class DyFM_Log {
     
     console.log(styleSets);
   }
+
+  /**
+   * Resets the style of the console log.
+   */
   static resetStyle(): void {
     console.log(DyFM_LogStyle.reset);
   }
 
+  /**
+   * Adds a style to the console log.
+   * @param input - The input to add the style to.
+   * @param styles - The styles to add.
+   * @param dontReset - Whether to not reset the style.
+   * @returns The input with the style added.
+   */
   static addStyle(input: string, styles: DyFM_LogStyle[], dontReset?: boolean): string {
     let result = '';
 
@@ -40,6 +55,15 @@ export class DyFM_Log {
     return result;
   }
 
+  /**
+   * Logs a success message.
+   * @param message - The message to log.
+   * @param optionalParams - The optional parameters to log.
+   *//**
+   * Logs a success message.
+   * @param message - The message to log.
+   * @param optionalParams - The optional parameters to log.
+   */
   static success(message: string, ...optionalParams: any[]): void {
     if (0 < optionalParams.length) {
       console.log(
@@ -55,6 +79,11 @@ export class DyFM_Log {
    */
   static readonly logSuccess = this.success;
 
+  /**
+   * Logs an error message.
+   * @param message - The message to log.
+   * @param optionalParams - The optional parameters to log.
+   */
   static error(message: string, ...optionalParams: any[]): void {
     if (0 < optionalParams.length) {
       console.error(
@@ -70,6 +99,11 @@ export class DyFM_Log {
    */
   static readonly logError = this.error;
 
+  /**
+   * Logs a warning message.
+   * @param message - The message to log.
+   * @param optionalParams - The optional parameters to log.
+   */
   static warn(message: string, ...optionalParams: any[]): void {
     if (0 < optionalParams.length) {
       console.warn(
@@ -91,20 +125,41 @@ export class DyFM_Log {
 
   // ez azért nem egy sima "static readonly info = console.info;", 
   // mert azon nincs rajta az első input típusa, ami csak string lehet
+  /**
+   * Logs an info message.
+   * @param message - The message to log.
+   * @param optionalParams - The optional parameters to log.
+   */
   static info(message: string, ...optionalParams: any[]): void {
     console.info(message, ...optionalParams);
   }
 
   // ez azért nem egy sima "static readonly log = console.log;", 
   // mert azon nincs rajta az első input típusa, ami csak string lehet
+  /**
+   * Logs a log message.
+   * @param message - The message to log.
+   * @param optionalParams - The optional parameters to log.
+   */
   static log(message: string, ...optionalParams: any[]): void {
     console.log(message, ...optionalParams);
   }
 
+  /**
+   * Gets a highlighted message.
+   * @param message - The message to highlight.
+   * @param optionalParams - The optional parameters to highlight.
+   * @returns The highlighted message.
+   */
   static getHighlighted(message: string, ...optionalParams: any[]): string {
     return `${DyFM_LogStyle.white}${DyFM_LogStyle.bright}${message}${DyFM_LogStyle.reset}`;
   }
 
+  /**
+   * Logs a highlighted message.
+   * @param message - The message to highlight.
+   * @param optionalParams - The optional parameters to highlight.
+   */
   static highlighted(message: string, ...optionalParams: any[]): void {
     if (0 < optionalParams.length) {
       console.log(
@@ -117,6 +172,11 @@ export class DyFM_Log {
       );
     }
   }
+  /**
+   * Tests a log message.
+   * @param message - The message to test.
+   * @param optionalParams - The optional parameters to test.
+   */
   static testLog(message: string, ...optionalParams: any[]): void {
     this.log('\n\n' + this.h_solid + '\n');
     this.log(message, ...optionalParams);
@@ -124,6 +184,11 @@ export class DyFM_Log {
   }  
   static readonly test = DyFM_Log.testLog;
   
+  /**
+   * Logs a highlighted log message.
+   * @param message - The message to highlight.
+   * @param optionalParams - The optional parameters to highlight.
+   */
   static highlightedLog(message: string, ...optionalParams: any[]): void {
     this.log('\n\n' + this.h_before);
     this.log(' ' + this.h_before);
@@ -135,12 +200,22 @@ export class DyFM_Log {
   }  
   static readonly H_log = DyFM_Log.highlightedLog;
 
+  /**
+   * Tests an info message.
+   * @param message - The message to test.
+   * @param optionalParams - The optional parameters to test.
+   */
   static testInfo(message: string, ...optionalParams: any[]): void {
     this.info('\n\n' + this.h_solid + '\n');
     this.info(message, ...optionalParams);
     this.info('\n' + this.h_solid + '\n\n');
   }
 
+  /**
+   * Logs a highlighted info message.
+   * @param message - The message to highlight.
+   * @param optionalParams - The optional parameters to highlight.
+   */
   static highlightedInfo(message: string, ...optionalParams: any[]): void {
     this.info('\n\n' + this.h_before);
     this.info(' ' + this.h_before);
@@ -152,12 +227,22 @@ export class DyFM_Log {
   }
   static readonly H_info = DyFM_Log.highlightedInfo;
 
+  /**
+   * Tests an error message.
+   * @param message - The message to test.
+   * @param optionalParams - The optional parameters to test.
+   */
   static testError(message: string, ...optionalParams: any[]): void {
     this.error('\n\n' + this.h_solid + '\n');
     this.error(message, ...optionalParams);
     this.error('\n' + this.h_solid + '\n\n');
   }
 
+  /**
+   * Logs a highlighted error message.
+   * @param message - The message to highlight.
+   * @param optionalParams - The optional parameters to highlight.
+   */
   static highlightedError(message: string, ...optionalParams: any[]): void {
     this.error('\n\n' + this.h_before);
     this.error(' ' + this.h_before);
@@ -169,12 +254,22 @@ export class DyFM_Log {
   }
   static readonly H_error = DyFM_Log.highlightedError;
 
+  /**
+   * Tests a warning message.
+   * @param message - The message to test.
+   * @param optionalParams - The optional parameters to test.
+   */
   static testWarn(message: string, ...optionalParams: any[]): void {
     this.warn('\n\n' + this.h_solid + '\n');
     this.warn(message, ...optionalParams);
     this.warn('\n' + this.h_solid + '\n\n');
   }
 
+  /**
+   * Logs a highlighted warning message.
+   * @param message - The message to highlight.
+   * @param optionalParams - The optional parameters to highlight.
+   */
   static highlightedWarn(message: string, ...optionalParams: any[]): void {
     this.warn('\n\n' + this.h_before);
     this.warn(' ' + this.h_before);
@@ -186,12 +281,22 @@ export class DyFM_Log {
   }  
   static readonly H_warn = DyFM_Log.highlightedWarn;
 
+  /**
+   * Tests a success message.
+   * @param message - The message to test.
+   * @param optionalParams - The optional parameters to test.
+   */
   static testSuccess(message: string, ...optionalParams: any[]): void {
     this.success('\n\n' + this.h_solid + '\n');
     this.success(message, ...optionalParams);
     this.success('\n' + this.h_solid + '\n\n');
   }
 
+  /**
+   * Logs a highlighted success message.
+   * @param message - The message to highlight.
+   * @param optionalParams - The optional parameters to highlight.
+   */
   static highlightedSuccess(message: string, ...optionalParams: any[]): void {
     this.success('\n\n' + this.h_before);
     this.success(' ' + this.h_before);
@@ -210,24 +315,38 @@ export class DyFM_Log {
   // eslint-disable-next-line max-len
   private static readonly h_after: string =  '/////////////////////////////////////////////////////////////////////////////';
 
+  /**
+   * Removes the log styles from a message.
+   * @param message - The message to remove the styles from.
+   * @returns The message without the styles.
+   */
   static removeLogStyles(message: string): string {
     for (const styleKey of Object(DyFM_LogStyle)) {
-      message = message.replace(new RegExp(DyFM_LogStyle[styleKey], 'g'), '');
+      message = message.replace(new RegExp(DyFM_LogStyle[styleKey as keyof typeof DyFM_LogStyle], 'g'), '');
     }
 
     return message;
   }
 
+  /**
+   * Silences all logs.
+   */
   static silenceLogs(): void {
     console.log = (): void => {};
   }
 
+  /**
+   * Silences non-error logs.
+   */
   static silenceNonErrorLogs(): void {
     console.log = (): void => {};
     console.info = (): void => {};
     console.warn = (): void => {};
   }
-  
+
+  /**
+   * Silences all logs.
+   */
   static silenceConsole(): void {
     console.log = (): void => {};
     console.info = (): void => {};
@@ -235,6 +354,11 @@ export class DyFM_Log {
     console.error = (): void => {};
   }
 
+  /**
+   * Adds breaks and tabs to the string parameters.
+   * @param params - The parameters to add the breaks and tabs to.
+   * @returns The parameters with the breaks and tabs added.
+   */
   static addBreaksAndTabsToStringParams(params: any[]): any[] {
     return params.map((param: any): string => {
       if (typeof param === 'string') {

package/src/_collections/utils/math/box-bounds.spec.ts

@@ -1,14 +1,13 @@
-
-import { DyFM_BoxBounds } from './box-bounds.util';
+import { DyFM_BoxBounds_Util } from './box-bounds.util';
 import { DyFM_Vector2_Util } from './vector2.util';
 
 xdescribe('| DyFM_BoxBounds', () => {
-  let boxBounds: DyFM_BoxBounds;
+  let boxBounds: DyFM_BoxBounds_Util;
   const mockPosition = new DyFM_Vector2_Util({ x: 0, y: 0 });
   const mockSize = new DyFM_Vector2_Util({ x: 10, y: 10 });
 
   beforeEach(() => {
-    boxBounds = new DyFM_BoxBounds(mockPosition, mockSize);
+    boxBounds = new DyFM_BoxBounds_Util(mockPosition, mockSize);
   });
 
   it('| should set position correctly ()', () => {
@@ -39,15 +38,11 @@ xdescribe('| DyFM_BoxBounds', () => {
 
   it('| should calculate center correctly', () => {
     const expectedCenter = new DyFM_Vector2_Util({ x: 10, y: 10 });
-
-    boxBounds['calcCenter']();
     expect(boxBounds.center).toEqual(expectedCenter);
   });
 
   it('| should calculate center margin correctly', () => {
     const expectedCenterMargin = new DyFM_Vector2_Util({ x: -5, y: -5 });
-
-    boxBounds['calcCenter']();
     expect(boxBounds.centerMargin).toEqual(expectedCenterMargin);
   });
 
@@ -57,23 +52,23 @@ xdescribe('| DyFM_BoxBounds', () => {
 
   it('| should throw error when newValues has undefined position', () => {
     expect(() => {
-      boxBounds.newValues(undefined, { x: 10, y: 10 });
+      boxBounds.newValues(undefined as any, { x: 10, y: 10 });
     }).toThrow(Error);
   });
 
   it('| should throw error when newValues has undefined size', () => {
     expect(() => {
-      boxBounds.newValues({ x: 0, y: 0 }, undefined);
+      boxBounds.newValues({ x: 0, y: 0 }, undefined as any);
     }).toThrow(Error);
   });
 
   it('| should clone and return a new instance', () => {
     const clonedBoxBounds = boxBounds.clone();
 
-    expect(clonedBoxBounds).toBeInstanceOf(DyFM_BoxBounds);
+    expect(clonedBoxBounds).toBeInstanceOf(DyFM_BoxBounds_Util);
     expect(clonedBoxBounds).toEqual(boxBounds);
   });
-
-  // Add more test cases as needed
+  
+  
 
 });

package/src/_collections/utils/math/box-bounds.util.spec.ts

@@ -1,15 +1,15 @@
 
-import { DyFM_BoxBounds } from './box-bounds.util';
+import { DyFM_BoxBounds_Util } from './box-bounds.util';
 import { DyFM_Vector2_Util } from './vector2.util';
 import { DyFM_Vector2 } from '../../../_models/interfaces/vector2.interface';
 
 describe('| DyFM_BoxBounds', () => {
-  let boxBounds: DyFM_BoxBounds;
+  let boxBounds: DyFM_BoxBounds_Util;
   const position: DyFM_Vector2 = { x: 10, y: 20 };
   const size: DyFM_Vector2 = { x: 30, y: 40 };
 
   beforeEach(() => {
-    boxBounds = new DyFM_BoxBounds(position, size);
+    boxBounds = new DyFM_BoxBounds_Util(position, size);
   });
 
   it('| should initialize with given position and size', () => {

package/src/_collections/utils/math/box-bounds.util.ts

@@ -1,5 +1,6 @@
 
 
+import { DyFM_BoxBounds } from '../../../_models/interfaces/box-bounds.interface';
 import { DyFM_Vector2 } from '../../../_models/interfaces/vector2.interface';
 import { DyFM_Vector2_Util } from './vector2.util';
 
@@ -9,33 +10,53 @@ import { DyFM_Vector2_Util } from './vector2.util';
  * while instance functions change the current BoxBounds and returns itself.
  * (if this is not true, report it as a bug)
  */
-export class DyFM_BoxBounds {
+export class DyFM_BoxBounds_Util {
   private readonly _pos: DyFM_Vector2_Util;
+  /**
+   * setting the position will also recalculate the center and centerMargin
+   */
   set pos(value: DyFM_Vector2) {
     this._pos.newValues(value);
 
     this.calcCenter();
   }
+  /**
+   * getting the position will return the position as a DyFM_Vector2_Util
+   */
   get pos(): DyFM_Vector2_Util { 
     return this._pos;
   }
 
   private readonly _size: DyFM_Vector2_Util;
+  /**
+   * setting the size will also recalculate the center and centerMargin
+   */
   set size(value: DyFM_Vector2) {
     this._size.newValues(value);
     
     this.calcCenter();
   }
+  /**
+   * getting the size will return the size as a DyFM_Vector2_Util
+   */
   get size(): DyFM_Vector2_Util { 
     return this._size;
   }
 
-  private _center: DyFM_Vector2_Util;
+  private _center!: DyFM_Vector2_Util;
+  /**
+   * getting the center will return the center as a DyFM_Vector2_Util
+   * (this is calculated from the position and size every time they are set)
+   */
   get center(): DyFM_Vector2_Util {
     return this._center;
   }
 
-  private _centerMargin: DyFM_Vector2_Util;
+  private _centerMargin!: DyFM_Vector2_Util;
+  /**
+   * getting the centerMargin will return the centerMargin as a DyFM_Vector2_Util
+   * (this is calculated from the size every time it is set)
+   */
   get centerMargin(): DyFM_Vector2_Util {
     return this._centerMargin;
   }
@@ -52,11 +73,18 @@ export class DyFM_BoxBounds {
     this.calcCenter();
   }
 
-  constructed?(): boolean { 
+  /**
+   * returns true if the box bounds has been constructed
+   */
+  constructed(): boolean { 
     return true; 
   }
 
-  newValues?(position: DyFM_Vector2, size: DyFM_Vector2): void {
+  /**
+   * sets the position and size of the box bounds
+   * (this will also recalculate the center and centerMargin)
+   */
+  newValues(position: DyFM_Vector2, size: DyFM_Vector2): void {
     if (position === undefined) {
       throw new Error('new position is undefined!');
     }
@@ -71,24 +99,49 @@ export class DyFM_BoxBounds {
     this.calcCenter();
   }
 
-  static bounds(box: DyFM_BoxBounds, position: DyFM_Vector2): boolean {
+  /**
+   * returns true if the position is within the box bounds
+   */
+  static bounds(box: DyFM_BoxBounds_Util, position: DyFM_Vector2): boolean {
     return  box.pos.x <= position.x && position.x <= box.pos.x + box.size.x && 
             box.pos.y <= position.y && position.y <= box.pos.y + box.size.y;
   }
-  bounds?(position: DyFM_Vector2): boolean {
-    return DyFM_BoxBounds.bounds(this, position);
+  /**
+   * returns true if the position is within the box bounds
+   */
+  bounds(position: DyFM_Vector2): boolean {
+    return DyFM_BoxBounds_Util.bounds(this, position);
   }
 
-  private calcCenter?(): void {
+  /**
+   * calculates the center and centerMargin of the box bounds
+   */
+  private calcCenter(): void {
     const halfSize = DyFM_Vector2_Util.divide(this.size, 2);
 
     this._center = DyFM_Vector2_Util.plus(this.pos, halfSize);
     this._centerMargin = DyFM_Vector2_Util.negative(halfSize);
   }
 
-  clone?(): DyFM_BoxBounds {
-    return new DyFM_BoxBounds(this._pos.clone(), this._size.clone());
+  /**
+   * returns the box bounds as a DyFM_BoxBounds
+   */
+  get(): DyFM_BoxBounds {
+    return {
+      pos: this._pos.get(),
+      size: this._size.get(),
+      center: this._center.get(),
+      centerMargin: this._centerMargin.get()
+    };
+  }
+  getBoxBounds = this.get;
+  toBoxBounds = this.get;
+
+  /**
+   * returns a new DyFM_BoxBounds_Util with the same position and size
+   */
+  clone(): DyFM_BoxBounds_Util {
+    return new DyFM_BoxBounds_Util(this._pos.clone(), this._size.clone());
   }
 }
 
-

package/src/_collections/utils/math/math.util.ts

@@ -1,27 +1,36 @@
 
 
 
-
-
-
-
-
-
+/**
+ * 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
+   */
   static between(value: number, minExclusive: number, maxExclusive: number): boolean {
     return minExclusive < value && value < maxExclusive;
   }
 
+  /**
+   * returns true if the value is between the target and the range
+   */
   static around(value: number, target: number, range: number): boolean {
     return this.between(value, target - range, target + range);
   }
 
+  /**
+   * returns a random integer between the min and max
+   */
   static getRandomInt(min: number, max: number): number {
     return min + Math.round((max - min) * Math.random());
   }
 
   static readonly toFixed = this.round;
+  /**
+   * returns a number rounded to the specified number of decimals
+   */
   static round(value: number, decimals: number = 2): number {
     if (0 <= decimals) {
       return Number(value.toFixed(decimals));
@@ -32,10 +41,16 @@ export class DyFM_Math {
     }
   }
 
+  /**
+   * returns a number with spaces between the thousands
+   */
   static numberWithSpaces(x: number): string {
     return x?.toString()?.replace(/\B(?=(\d{3})+(?!\d))/g, ' ');
   }
 
+  /**
+   * returns a number with shorter units
+   */
   static numberWithShorters(x: number): string {
     if (x < 1000) {
       return x?.toString();
@@ -48,10 +63,16 @@ export class DyFM_Math {
     }
   }
 
+  /**
+   * returns a number with shorter units and spaces between the thousands
+   */
   static numberWithShortersAndSpaces(x: number): string {
     return this.numberWithShorters(x)?.replace(/\B(?=(\d{3})+(?!\d))/g, ' ');
   }
 
+  /**
+   * returns a number with spaces between the thousands
+   */
   static floatingNumberWithSpaces(x: number): string {
     const parts: string[] = x?.toString()?.split('.');
 
@@ -60,6 +81,9 @@ export class DyFM_Math {
     return parts?.join('.');
   }
 
+  /**
+   * returns a number with spaces between the thousands
+   */
   static decimals(x: number, useSpacer: string = ','): string {
     const parts: string[] = x?.toString()?.split('.');
 

package/src/_collections/utils/math/random.util.spec.ts

@@ -50,14 +50,14 @@ describe('| DyFM_Random', () => {
 
   describe('| getRandomListElement', () => {
     it('| should return a random element from the list', () => {
-      const list = [1, 2, 3, 4, 5];
-      const result = DyFM_Random.getRandomListElement(list);
-      expect(list).toContain(result);
+      const list: number[] = [1, 2, 3, 4, 5];
+      const result: number | null = DyFM_Random.getRandomListElement(list);
+      expect(list).toContain(result as number);
     });
 
     it('| should return null if the list is empty', () => {
       const list: number[] = [];
-      const result = DyFM_Random.getRandomListElement(list);
+      const result: number | null = DyFM_Random.getRandomListElement(list);
       expect(result).toBeNull();
     });
   });
@@ -69,13 +69,13 @@ describe('| DyFM_Random', () => {
         { chance: 0.5, result: 'b' },
         { chance: 0.3, result: 'c' }
       ];
-      const result = DyFM_Random.getRandomWeighted(weights);
-      expect(['a', 'b', 'c']).toContain(result);
+      const result: string | null = DyFM_Random.getRandomWeighted(weights);
+      expect(['a', 'b', 'c']).toContain(result as string);
     });
 
     it('| should return null if weights array is empty', () => {
       const weights: DyFM_RandomWeight<string>[] = [];
-      const result = DyFM_Random.getRandomWeighted(weights);
+      const result: string | null = DyFM_Random.getRandomWeighted(weights);
       expect(result).toBeNull();
     });
   });

package/src/_collections/utils/math/random.util.ts

@@ -1,8 +1,15 @@
 
 
 import { DyFM_RandomWeight } from '../../../_models/interfaces/random-weight.interface';
+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
+   */
   static getRandomWeightedInt(
     min: number, 
     max: number, 
@@ -18,7 +25,7 @@ export class DyFM_Random {
     }
   
     const randomChance: number = Math.random();
-    let result: number;
+    let result: number | undefined;
     let chancer = 0;
 
     for (let i = 0; i < weights.length && result === undefined; i++) {
@@ -40,7 +47,12 @@ export class DyFM_Random {
     return min + Math.round((max - min) * Math.random());
   }
   
-  static getRandomListElement<T>(list: T[]): T {
+  /**
+   * returns null if list is empty
+   * @param list 
+   * @returns 
+   */
+  static getRandomListElement<T>(list: T[]): T | null {
     if (0 < list.length) {
       return list[this.getRandomInt(0, list.length - 1)];
     } else {
@@ -48,7 +60,13 @@ export class DyFM_Random {
     }
   }
   
-  static getRandomWeighted<T>(weights: DyFM_RandomWeight<T>[]): T {
+  /**
+   * returns a random weighted element from the list
+   * (returns null if list is empty)
+   * @param weights 
+   * @returns 
+   */
+  static getRandomWeighted<T>(weights: DyFM_RandomWeight<T>[]): T | null {
     if (!weights?.length) {
       return null;
     }
@@ -64,7 +82,7 @@ export class DyFM_Random {
     });
   
     const randomChance: number = Math.random();
-    let result: T;
+    let result: T | undefined;
     let chancer = 0;
 
     for (let i = 0; i < weights.length && result === undefined; i++) {
@@ -74,6 +92,11 @@ export class DyFM_Random {
         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;
   }