@futdevpro/fsm-dynamo 1.14.10 → 1.14.11

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

@@ -30,6 +30,11 @@ export class DyFM_Log {
   /**
    * Sets the style of the console log.
    * @param styles - The styles to set.
+   * 
+   * @example
+   * ```ts
+   * DyFM_Log.setStyle([ DyFM_LogStyle.bold, DyFM_LogStyle.underline ]);
+   * ```
    */
   static setStyle(styles: DyFM_LogStyle[]): void {
     let styleSets = '';
@@ -43,6 +48,11 @@ export class DyFM_Log {
 
   /**
    * Resets the style of the console log.
+   * 
+   * @example
+   * ```ts
+   * DyFM_Log.resetStyle();
+   * ```
    */
   static resetStyle(): void {
     console.log(DyFM_LogStyle.reset);
@@ -54,6 +64,11 @@ export class DyFM_Log {
    * @param styles - The styles to add.
    * @param dontReset - Whether to not reset the style.
    * @returns The input with the style added.
+   * 
+   * @example
+   * ```ts
+   * const result = DyFM_Log.addStyle('Hello, world!', [ DyFM_LogStyle.bold, DyFM_LogStyle.underline ]);
+   * ```
    */
   static addStyle(input: string, styles: DyFM_LogStyle[], dontReset?: boolean): string {
     let result = '';
@@ -75,10 +90,11 @@ export class DyFM_Log {
    * 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.
+   *
+   * @example
+   * ```ts
+   * DyFM_Log.success('Hello, world!');
+   * ```
    */
   static success(message: string, ...optionalParams: any[]): void {
     if (0 < optionalParams.length) {
@@ -99,6 +115,11 @@ export class DyFM_Log {
    * Logs an error message.
    * @param message - The message to log.
    * @param optionalParams - The optional parameters to log.
+   * 
+   * @example
+   * ```ts
+   * DyFM_Log.error('An error occurred: {errorMessage}', errorMessage);
+   * ```
    */
   static error(message: string, ...optionalParams: any[]): void {
     if (0 < optionalParams.length) {
@@ -119,6 +140,11 @@ export class DyFM_Log {
    * Logs a warning message.
    * @param message - The message to log.
    * @param optionalParams - The optional parameters to log.
+   * 
+   * @example
+   * ```ts
+   * DyFM_Log.warn('A warning occurred: {warningMessage}', warningMessage);
+   * ```
    */
   static warn(message: string, ...optionalParams: any[]): void {
     if (0 < optionalParams.length) {
@@ -145,6 +171,11 @@ export class DyFM_Log {
    * Logs an info message.
    * @param message - The message to log.
    * @param optionalParams - The optional parameters to log.
+   * 
+   * @example
+   * ```ts
+   * DyFM_Log.info('An info message: {infoMessage}', infoMessage);
+   * ```
    */
   static info(message: string, ...optionalParams: any[]): void {
     if (0 < optionalParams.length) {
@@ -163,6 +194,11 @@ export class DyFM_Log {
    * Logs a log message.
    * @param message - The message to log.
    * @param optionalParams - The optional parameters to log.
+   * 
+   * @example
+   * ```ts
+   * DyFM_Log.log('A log message: {logMessage}', logMessage);
+   * ```
    */
   static log(message: string, ...optionalParams: any[]): void {
     console.log(message, ...optionalParams);
@@ -173,6 +209,12 @@ export class DyFM_Log {
    * @param message - The message to highlight.
    * @param optionalParams - The optional parameters to highlight.
    * @returns The highlighted message.
+   * 
+   * @example
+   * ```ts
+   * const highlightedMessage = DyFM_Log.getHighlighted('A highlighted message: {highlightedMessage}', highlightedMessage);
+   * console.log(highlightedMessage); // A highlighted message: {highlightedMessage}
+   * ```
    */
   static getHighlighted(message: string, ...optionalParams: any[]): string {
     return `${this.highlightedStyle}${message}${DyFM_LogStyle.reset}`;
@@ -182,6 +224,11 @@ export class DyFM_Log {
    * Logs a highlighted message.
    * @param message - The message to highlight.
    * @param optionalParams - The optional parameters to highlight.
+   * 
+   * @example
+   * ```ts
+   * DyFM_Log.highlighted('A highlighted message: {highlightedMessage}', highlightedMessage);
+   * ```
    */
   static highlighted(message: string, ...optionalParams: any[]): void {
     if (0 < optionalParams.length) {
@@ -196,6 +243,16 @@ export class DyFM_Log {
     }
   }
 
+  /**
+   * Logs a small log message.
+   * @param message - The message to log.
+   * @param optionalParams - The optional parameters to log.
+   * 
+   * @example
+   * ```ts
+   * DyFM_Log.smallLog('A small log message: {smallLogMessage}', smallLogMessage);
+   * ```
+   */
   static smallLog(message: string, ...optionalParams: any[]): void {
     console.log(
       this.h_small + 
@@ -209,6 +266,11 @@ export class DyFM_Log {
    * Tests a log message.
    * @param message - The message to test.
    * @param optionalParams - The optional parameters to test.
+   * 
+   * @example
+   * ```ts
+   * DyFM_Log.testLog('A test log message: {testLogMessage}', testLogMessage);
+   * ```
    */
   static testLog(message: string, ...optionalParams: any[]): void {
     this.log(
@@ -224,6 +286,11 @@ export class DyFM_Log {
    * Logs a highlighted log message.
    * @param message - The message to highlight.
    * @param optionalParams - The optional parameters to highlight.
+   * 
+   * @example
+   * ```ts
+   * DyFM_Log.highlightedLog('A highlighted log message: {highlightedLogMessage}', highlightedLogMessage);
+   * ```
    */
   static highlightedLog(message: string, ...optionalParams: any[]): void {
     this.log(
@@ -238,6 +305,16 @@ export class DyFM_Log {
   }  
   static readonly H_log = DyFM_Log.highlightedLog;
 
+  /**
+   * Logs a small info message.
+   * @param message - The message to log.
+   * @param optionalParams - The optional parameters to log.
+   * 
+   * @example
+   * ```ts
+   * DyFM_Log.smallInfo('A small info message: {smallInfoMessage}', smallInfoMessage);
+   * ```
+   */
   static smallInfo(message: string, ...optionalParams: any[]): void {
     this.info(
       this.h_small + 
@@ -251,6 +328,11 @@ export class DyFM_Log {
    * Tests an info message.
    * @param message - The message to test.
    * @param optionalParams - The optional parameters to test.
+   * 
+   * @example
+   * ```ts
+   * DyFM_Log.testInfo('A test info message: {testInfoMessage}', testInfoMessage);
+   * ```
    */
   static testInfo(message: string, ...optionalParams: any[]): void {
     this.info(
@@ -265,6 +347,11 @@ export class DyFM_Log {
    * Logs a highlighted info message.
    * @param message - The message to highlight.
    * @param optionalParams - The optional parameters to highlight.
+   * 
+   * @example
+   * ```ts
+   * DyFM_Log.highlightedInfo('A highlighted info message: {highlightedInfoMessage}', highlightedInfoMessage);
+   * ```
    */
   static highlightedInfo(message: string, ...optionalParams: any[]): void {
     this.info(
@@ -279,6 +366,16 @@ export class DyFM_Log {
   }
   static readonly H_info = DyFM_Log.highlightedInfo;
 
+  /**
+   * Logs a small error message.
+   * @param message - The message to log.
+   * @param optionalParams - The optional parameters to log.
+   * 
+   * @example
+   * ```ts
+   * DyFM_Log.smallError('A small error message: {smallErrorMessage}', smallErrorMessage);
+   * ```
+   */
   static smallError(message: string, ...optionalParams: any[]): void {
     this.error(
       this.h_small + 
@@ -292,6 +389,11 @@ export class DyFM_Log {
    * Tests an error message.
    * @param message - The message to test.
    * @param optionalParams - The optional parameters to test.
+   * 
+   * @example
+   * ```ts
+   * DyFM_Log.testError('A test error message: {testErrorMessage}', testErrorMessage);
+   * ```
    */
   static testError(message: string, ...optionalParams: any[]): void {
     this.error(
@@ -306,6 +408,11 @@ export class DyFM_Log {
    * Logs a highlighted error message.
    * @param message - The message to highlight.
    * @param optionalParams - The optional parameters to highlight.
+   * 
+   * @example
+   * ```ts
+   * DyFM_Log.highlightedError('A highlighted error message: {highlightedErrorMessage}', highlightedErrorMessage);
+   * ```
    */
   static highlightedError(message: string, ...optionalParams: any[]): void {
     this.error(
@@ -320,6 +427,16 @@ export class DyFM_Log {
   }
   static readonly H_error = DyFM_Log.highlightedError;
 
+  /**
+   * Logs a small warning message.
+   * @param message - The message to log.
+   * @param optionalParams - The optional parameters to log.
+   * 
+   * @example
+   * ```ts
+   * DyFM_Log.smallWarn('A small warning message: {smallWarnMessage}', smallWarnMessage);
+   * ```
+   */
   static smallWarn(message: string, ...optionalParams: any[]): void {
     this.warn(
       this.h_small + 
@@ -333,6 +450,11 @@ export class DyFM_Log {
    * Tests a warning message.
    * @param message - The message to test.
    * @param optionalParams - The optional parameters to test.
+   * 
+   * @example
+   * ```ts
+   * DyFM_Log.testWarn('A test warning message: {testWarnMessage}', testWarnMessage);
+   * ```
    */
   static testWarn(message: string, ...optionalParams: any[]): void {
     this.warn(
@@ -347,6 +469,11 @@ export class DyFM_Log {
    * Logs a highlighted warning message.
    * @param message - The message to highlight.
    * @param optionalParams - The optional parameters to highlight.
+   * 
+   * @example
+   * ```ts
+   * DyFM_Log.highlightedWarn('A highlighted warning message: {highlightedWarnMessage}', highlightedWarnMessage);
+   * ```
    */
   static highlightedWarn(message: string, ...optionalParams: any[]): void {
     this.warn(
@@ -361,6 +488,16 @@ export class DyFM_Log {
   }  
   static readonly H_warn = DyFM_Log.highlightedWarn;
 
+  /**
+   * Logs a small success message.
+   * @param message - The message to log.
+   * @param optionalParams - The optional parameters to log.
+   * 
+   * @example
+   * ```ts
+   * DyFM_Log.smallSuccess('A small success message: {smallSuccessMessage}', smallSuccessMessage);
+   * ```
+   */
   static smallSuccess(message: string, ...optionalParams: any[]): void {
     this.success(
       this.h_small + 
@@ -374,6 +511,11 @@ export class DyFM_Log {
    * Tests a success message.
    * @param message - The message to test.
    * @param optionalParams - The optional parameters to test.
+   * 
+   * @example
+   * ```ts
+   * DyFM_Log.testSuccess('A test success message: {testSuccessMessage}', testSuccessMessage);
+   * ```
    */
   static testSuccess(message: string, ...optionalParams: any[]): void {
     this.success(
@@ -417,6 +559,11 @@ export class DyFM_Log {
 
   /**
    * Silences all logs.
+   * 
+   * @example
+   * ```ts
+   * DyFM_Log.silenceLogs();
+   * ```
    */
   static silenceLogs(): void {
     console.log = (): void => {};
@@ -424,6 +571,11 @@ export class DyFM_Log {
 
   /**
    * Silences non-error logs.
+   * 
+   * @example
+   * ```ts
+   * DyFM_Log.silenceNonErrorLogs();
+   * ```
    */
   static silenceNonErrorLogs(): void {
     console.log = (): void => {};
@@ -433,6 +585,11 @@ export class DyFM_Log {
 
   /**
    * Silences all logs.
+   * 
+   * @example
+   * ```ts
+   * DyFM_Log.silenceConsole();
+   * ```
    */
   static silenceConsole(): void {
     console.log = (): void => {};
@@ -445,6 +602,13 @@ export class DyFM_Log {
    * 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.
+   * 
+   * @example
+   * ```ts
+   * const params = [ 'Hello, world!', 'Hello, world!', 'Hello, world!' ];
+   * const result = DyFM_Log.addBreaksAndTabsToStringParams(params);
+   * console.log(result); // [ 'Hello, world!', 'Hello, world!', 'Hello, world!' ]
+   * ```
    */
   static addBreaksAndTabsToStringParams(params: any[]): any[] {
     return params.map((param: any): string => {
@@ -456,11 +620,37 @@ export class DyFM_Log {
     });
   }
 
+  /**
+   * Adds spaces for each line.
+   * @param message - The message to add the spaces to.
+   * @param spaces - The number of spaces to add.
+   * @returns The message with the spaces added.
+   * 
+   * @example
+   * ```ts
+   * const message = 'Hello, world!\nHello, world!\nHello, world!';
+   * const result = DyFM_Log.addSpacesForEachLine(message, 2);
+   * console.log(result); // Hello, world!  Hello, world!  Hello, world!
+   * ```
+   */
   static addSpacesForEachLine(message: string, spaces: number): string {
     return message.replaceAll('\n', '\n' + ' '.repeat(spaces));
   }
   private static asfel = this.addSpacesForEachLine;
 
+  /**
+   * Adds spaces for each string optional parameter.
+   * @param params - The parameters to add the spaces to.
+   * @param spaces - The number of spaces to add.
+   * @returns The parameters with the spaces added.
+   * 
+   * @example
+   * ```ts
+   * const params = [ 'Hello, world!', 'Hello, world!', 'Hello, world!' ];
+   * const result = DyFM_Log.addSpacesForEachStringOptionalParam(params, 2);
+   * console.log(result); // [ 'Hello, world!  Hello, world!  Hello, world!' ]
+   * ```
+   */
   static addSpacesForEachStringOptionalParam(params: any[], spaces: number): any[] {
     return params.map((param: any): any => {
       if (typeof param === 'string') {

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

@@ -9,6 +9,13 @@ import { DyFM_Vector2_Util } from './vector2.util';
  * is that static functions return new BoxBounds, 
  * while instance functions change the current BoxBounds and returns itself.
  * (if this is not true, report it as a bug)
+ * 
+ * @example
+ * ```ts
+ * const boxBounds = new DyFM_BoxBounds_Util({ x: 0, y: 0 }, { x: 10, y: 10 });
+ * boxBounds.pos = { x: 5, y: 5 };
+ * console.log(boxBounds.pos);
+ * ```
  */
 export class DyFM_BoxBounds_Util {
   private readonly _pos: DyFM_Vector2_Util;
@@ -83,6 +90,12 @@ export class DyFM_BoxBounds_Util {
   /**
    * sets the position and size of the box bounds
    * (this will also recalculate the center and centerMargin)
+   * 
+   * @example
+   * ```ts
+   * const boxBounds = new DyFM_BoxBounds_Util({ x: 0, y: 0 }, { x: 10, y: 10 });
+   * boxBounds.newValues({ x: 5, y: 5 }, { x: 20, y: 20 });
+   * ```
    */
   newValues(position: DyFM_Vector2, size: DyFM_Vector2): void {
     if (position === undefined) {
@@ -101,6 +114,14 @@ export class DyFM_BoxBounds_Util {
 
   /**
    * returns true if the position is within the box bounds
+   * 
+   * @example
+   * ```ts
+   * const boxBounds = new DyFM_BoxBounds_Util({ x: 0, y: 0 }, { x: 10, y: 10 });
+   * const position = new DyFM_Vector2({ x: 5, y: 5 });
+   * const isWithinBounds = DyFM_BoxBounds_Util.bounds(boxBounds, position);
+   * console.log(isWithinBounds);
+   * ```
    */
   static bounds(box: DyFM_BoxBounds_Util, position: DyFM_Vector2): boolean {
     return  box.pos.x <= position.x && position.x <= box.pos.x + box.size.x && 
@@ -108,6 +129,13 @@ export class DyFM_BoxBounds_Util {
   }
   /**
    * returns true if the position is within the box bounds
+   * 
+   * @example
+   * ```ts
+   * const boxBounds = new DyFM_BoxBounds_Util({ x: 0, y: 0 }, { x: 10, y: 10 });
+   * const isWithinBounds = boxBounds.bounds(new DyFM_Vector2({ x: 5, y: 5 });
+   * console.log(isWithinBounds);
+   * ```
    */
   bounds(position: DyFM_Vector2): boolean {
     return DyFM_BoxBounds_Util.bounds(this, position);
@@ -115,6 +143,8 @@ export class DyFM_BoxBounds_Util {
 
   /**
    * calculates the center and centerMargin of the box bounds
+   * 
+   * only usable inside the class
    */
   private calcCenter(): void {
     const halfSize = DyFM_Vector2_Util.divide(this.size, 2);
@@ -139,6 +169,12 @@ export class DyFM_BoxBounds_Util {
 
   /**
    * returns a new DyFM_BoxBounds_Util with the same position and size
+   * 
+   * @example
+   * ```ts
+   * const boxBounds = new DyFM_BoxBounds_Util({ x: 0, y: 0 }, { x: 10, y: 10 });
+   * const clonedBoxBounds = boxBounds.clone();
+   * ```
    */
   clone(): DyFM_BoxBounds_Util {
     return new DyFM_BoxBounds_Util(this._pos.clone(), this._size.clone());

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

@@ -36,16 +36,6 @@ describe('| DyFM_Math', () => {
     });
   });
 
-  describe('| getRandomInt', () => {
-    it('| should return an integer within the specified range', () => {
-      const min = 1;
-      const max = 10;
-      const result = DyFM_Math.getRandomInt(min, max);
-      expect(result).toBeGreaterThanOrEqual(min);
-      expect(result).toBeLessThanOrEqual(max);
-    });
-  });
-
   describe('| round', () => {
     it('| should round a number to the specified number of decimals', () => {
       expect(DyFM_Math.round(1.2345, 2)).toBe(1.23);

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

@@ -8,6 +8,12 @@ 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: number, minExclusive: number, maxExclusive: number): boolean {
     return minExclusive < value && value < maxExclusive;
@@ -15,30 +21,26 @@ export class DyFM_Math {
 
   /**
    * 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: 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(
-    /**
-     * the minimum value (inclusive)
-     */
-    min: number, 
-    /**
-     * the maximum value (inclusive)
-     */
-    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
+   * 
+   * @example
+   * ```ts
+   * const roundedNumber = DyFM_Math.round(1.2345, 2);
+   * console.log(roundedNumber); // 1.23
+   * ```
    */
   static round(value: number, decimals: number = 2): number {
     if (0 <= decimals) {
@@ -52,6 +54,12 @@ export class DyFM_Math {
 
   /**
    * returns a number with spaces between the thousands
+   * 
+   * @example
+   * ```ts
+   * const numberWithSpaces = DyFM_Math.numberWithSpaces(1000);
+   * console.log(numberWithSpaces); // '1 000'
+   * ```
    */
   static numberWithSpaces(x: number): string {
     return x?.toString()?.replace(/\B(?=(\d{3})+(?!\d))/g, ' ');
@@ -59,6 +67,12 @@ export class DyFM_Math {
 
   /**
    * returns a number with shorter units
+   * 
+   * @example
+   * ```ts
+   * const numberWithShorters = DyFM_Math.numberWithShorters(1000);
+   * console.log(numberWithShorters); // '1.0k'
+   * ```
    */
   static numberWithShorters(x: number): string {
     if (x < 1000) {
@@ -74,6 +88,12 @@ export class DyFM_Math {
 
   /**
    * 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: number): string {
     return this.numberWithShorters(x)?.replace(/\B(?=(\d{3})+(?!\d))/g, ' ');
@@ -81,6 +101,12 @@ export class DyFM_Math {
 
   /**
    * 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: number): string {
     const parts: string[] = x?.toString()?.split('.');
@@ -92,6 +118,12 @@ export class DyFM_Math {
 
   /**
    * 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: number, useSpacer: string = ','): string {
     const parts: string[] = x?.toString()?.split('.');

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

@@ -9,6 +9,16 @@ import { DyFM_Log } from '../log.util';
 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: number, 
@@ -48,6 +58,12 @@ export class DyFM_Random {
    * @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: number, max: number): number {
     return min + Math.round((max - min) * Math.random());
@@ -57,6 +73,12 @@ export class DyFM_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<T>(list: T[]): T | null {
     if (0 < list.length) {
@@ -71,6 +93,14 @@ export class DyFM_Random {
    * (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<T>(weights: DyFM_RandomWeight<T>[]): T | null {
     if (!weights?.length) {