@futdevpro/fsm-dynamo 1.16.38 → 1.16.40

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

@@ -1,739 +1,739 @@
-
-import { DyFM_Log } from './log.util';
-import { DyFM_JsonErrorHelper } from './json-error-helper.util';
-import { DyFM_String } from './string.util';
-
-export interface DyFM_Object_ParseResult {
-  unparsableResult: string;
-}
-
-export class DyFM_Object {
-
-  static readonly defaultErrorMsg = 
-    ' failed. ' +
-    '\nThis might be happening because the object you trying to clone, ' +
-    'contains object hooks for its own objects, therefore its creating an object loop. ' +
-    'See further information in the detailed error:\n\n';
-
-  /**
-   * returns remapped object list by path list
-   * @param objList object list to map
-   * @param paths string list of path etc.:
-   * ```ts
-   * [ [ 'first', 'sub', 'label' ], [ 'first', 'dif', 'name' ] ] 
-   * ``` 
-   * will be...
-   * from
-   * ```ts
-   * {
-   *   first: {
-   *     sub: {
-   *       label: 'vlmi'
-   *     },
-   *     dif: {
-   *       name: 'asd'
-   *     }
-   *   }
-   * }[]
-   * ```
-   * to
-   * ```
-   * { label: 'vlmi', name: 'asd' }[]
-   * ```
-   * @returns remapped object list (the final obj will use the deepest keys)
-   */
-  static mapObjList(objList: object[], paths: string[][]): object[] {
-    let newObjList: object[] = [ ...objList ];
-
-    newObjList = newObjList.map((obj): any => {
-      const newObj: any = {};
-
-      paths.forEach((path: string[]): void => {
-        newObj[path[path.length - 1]] = this.getNestedData(obj, path);
-      });
-
-      return newObj;
-    });
-
-    return newObjList;
-  }
-
-  /**
-   * returns nested value from object
-   * @param parentObj data source object
-   * @param nestedDataKeys path of value as string list
-   * etc.: ['nestLvl1', 'nestLvl2', 'nestLvl3'] as parentObj.nestLvl1.nestLvl2.nestLvl3
-   * @returns data from object by path
-   */
-  static getNestedData(parentObj: object, nestedDataKeys: string[]): any {
-    let newData: any = this.clone(parentObj); // {...parentObj};
-
-    nestedDataKeys.forEach((dk: string): void => {
-      if (newData) {
-        newData = newData[dk];
-      }
-    });
-
-    return newData;
-  }
-
-  /**
-   * recursive function that nests data
-   * @param newData the object that that is needed to be updated
-   * @param nestKeys the path where the data should be updated
-   * @param dataToSet the actual value that will be setted
-   * @returns modified data
-   */
-  static nestData(parentObj: object, nestKeys: string[], dataToSet: any): object {
-    const newData: any = this.clone(parentObj); // {...parentObj};
-
-    if (nestKeys.length > 1) {
-      const keys: string[] = [ ...nestKeys ];
-      const nextNestKey: string = keys.shift() as string;
-
-      newData[nextNestKey] = this.nestData(newData[nextNestKey], keys, dataToSet);
-    } else {
-      newData[nestKeys[0]] = dataToSet;
-    }
-
-    return newData;
-  }
-
-  /**
-   * recursive function that adds to nested data
-   * @param newData the object that that is needed to be updated
-   * @param nestKeys the path where the data should be updated
-   * @param dataToAdd the actual value that will be setted
-   * @returns modified data
-   */
-  static addToNestedData(parentObj: object, nestKeys: string[], dataToAdd: any): object {
-    const newData: any = this.clone(parentObj); // {...parentObj};
-
-    if (nestKeys.length > 1) {
-      const keys: string[] = [ ...nestKeys ];
-      const nextNestKey: string = keys.shift() as string;
-
-      newData[nextNestKey] = this.addToNestedData(newData[nextNestKey], keys, dataToAdd);
-    } else {
-      newData[nestKeys[0]] += dataToAdd;
-    }
-
-    return newData;
-  }
-
-  /**
-   * recursive function that pushes to nested data
-   * @param newData the object that that is needed to be updated
-   * @param nestKeys the path where the data should be updated
-   * @param dataToPush the actual value that will be setted
-   * @returns modified data
-   */
-  static pushToNestedData(parentObj: object, nestKeys: string[], dataToPush: any): object {
-    const newData: any = this.clone(parentObj); // {...parentObj};
-
-    if (nestKeys.length > 1) {
-      const keys: string[] = [ ...nestKeys ];
-      const nextNestKey: string = keys.shift() as string;
-
-      newData[nextNestKey] = this.pushToNestedData(newData[nextNestKey], keys, dataToPush);
-    } else {
-      if (Array.isArray(newData[nestKeys[0]])) {
-        newData[nestKeys[0]].push(dataToPush);
-      } else {
-        newData[nestKeys[0]] = [ dataToPush ];
-      }
-    }
-
-    return newData;
-  }
-
-  /**
-   * recursive function that nests data on recursive data structure etc.: xData: { ..., 'nestedListKey': xData[] }
-   * @param newData the object that that is needed to be updated
-   * @param nestedListKey the location of nested dataList
-   * @param nestIndexes path to the subject ect.: xData.listKey[1].listKey[4].listKey[0] will be [1, 4, 0]
-   * @param dataToSet the actual value that will be seted on location
-   * @returns modified data
-   */
-  static nestRecursiveListedData<T>(
-    parentObj: T, 
-    nestedListKey: string, 
-    nestIndexes: number[], 
-    dataToSet: any
-  ): T {
-    const newData: any = this.clone(parentObj); // parentObj; // {...parentObj};
-
-    if (nestIndexes.length > 1) {
-      const indexes: number[] = [ ...nestIndexes ];
-      const nextLevelKey: number = indexes.shift() as number;
-
-      newData[nestedListKey][nextLevelKey] = this.nestRecursiveListedData(
-        newData[nestedListKey][nextLevelKey], nestedListKey, indexes, dataToSet
-      );
-    } else {
-      newData[nestedListKey][nestIndexes[0]] = dataToSet;
-    }
-
-    return newData;
-  }
-
-  static readonly removeCirculation = this.resolveCirculation;
-  /**
-   * THIS STILL NOT WORKING AS IT SHOULD
-   * 
-   * recursive function that returns mutated data structure, 
-   * with locations at which circular references are found
-   */
-  static resolveCirculation<T>(
-    data: T, 
-    location: string[] = [ ('ROOT;' + data?.constructor?.name) ], 
-    objs: any[] = [],
-    /* arrs: any[] = [] */
-  ): any {
-    if (!data || typeof data !== 'object') {
-      return data;
-    } else if (objs.includes(data)) {
-      return 'CIRCULATION:' + location.join('.');
-    }
-    
-    let newData: any;
-
-    if (Array.isArray(data)) {
-      newData = [];
-    } else {
-      newData = {};
-    }
-
-    // using the utility that Object.keys will return array keys if the data is an array
-    Object.keys(data).forEach((key: string): void => {
-      newData[key] = this.resolveCirculation(
-        data[key as keyof typeof data], 
-        [ ...location, key ], 
-        [ ...objs, data ]
-      );
-    });
-
-    return newData;
-  }
-
-
-  /**
-   * looks for circular references in object
-   * returns duplicated object's all location paths and the object itself
-   *  
-   *  { 
-   *    object: any,
-   *    pathsOfAllDuplications: string[],
-   *  }[]
-   * 
-   * paths are in a single string, separated by '.'
-   */
-  static findCirculations(
-    data: any, 
-    location: string[] = [ ('ROOT;' + data?.constructor?.name) ], 
-    objs: any[] = [],
-    duplications: { object: any, pathsOfAllDuplications: string[] }[] = []
-  ): { object: any, pathsOfAllDuplications: string[] }[] {
-    if (!data || typeof data !== 'object') {
-      return duplications;
-    } else if (objs.includes(data)) {
-      duplications.push({
-        object: data,
-        pathsOfAllDuplications: location,
-      });
-    }
-
-    Object.keys(data).forEach((key: string): void => {
-      this.findCirculations(
-        data[key], 
-        [ ...location, key ], 
-        [ ...objs, data ],
-        duplications
-      );
-    });
-
-    return duplications;
-  }
-
-  /**
-   * removes all undefined (will keep all null, false, 0, '', NaN etc.)
-   * 
-   * (not supports lists in lists!)
-   * 
-   * (this also modifies the original object in place)
-   */
-  static safeCleanObject<T>(obj: T): T {
-    try {
-      return this.cleanObject<T>(obj);
-    } catch (error) {
-      DyFM_Log.error('Error cleaning object:', error);
-      return obj;
-    }
-  }
-
-  /**
-   * cleans the object, by removing all undefined values (but keeps all null, false, 0, '', NaN etc.)
-   * (this is a deep clean)
-   * 
-   * (this also modifies the original object in place)
-   */
-  static cleanObject<T>(obj: T, cleanings: any[] = []): T {
-    if (!obj || typeof obj !== 'object' || cleanings.includes(obj)) {
-      return obj;
-    }
-
-    cleanings.push(obj);
-
-    Object.keys(obj).forEach((key: string): void => {
-      if (obj[key] === undefined) {
-        delete obj[key];
-      } else if (Array.isArray(obj[key])) {
-        obj[key].forEach((item: any): void => {
-          if (typeof item === 'object') {
-            this.cleanObject(item, cleanings);
-          }
-        });
-      } else if (typeof obj[key] === 'object') {
-        this.cleanObject(obj[key], cleanings);
-      }
-    });
-
-    return obj;
-  }
-
-  /** 
-   * merges two objects, if the target object is not an object, it will be replaced by the source object
-   * it will iterate through the source object 
-   *   and will set the values to the target object
-   * (like a patch, with deep merge)
-   * 
-   * (this also modifies the original target object in place)
-   */
-  static mergeObjects<T>(target: T, source: T): T {  
-    if (typeof source === 'object') {
-      target ??= {} as T;
-  
-      for (const key in source) {
-        if (source[key] instanceof Object) {
-          target[key] = this.mergeObjects(target[key], source[key]);
-        } else if (Array.isArray(source[key])) {
-          target[key] ??= [] as T[Extract<keyof T, string>];
-          source[key].forEach(item => {
-            if (
-              !(target[key] as Array<any>).includes(item) &&
-              !((target[key] as Array<any>).some(targetItem => this.sameObjects(item, targetItem)))
-            ) {
-              (target[key] as Array<any>).push(item);
-            }
-          });
-        } else {
-          target[key] = source[key];
-        }
-      }
-    }
-  
-    return target;
-  }
-  
-  /**
-   * cleans the source object and merges it to the target object
-   * 
-   * (this also modifies the original objects in place! (source AND target))
-   */
-  static patchObject<T>(target: T, source: T): T {
-    this.cleanObject<T>(source);
-    return this.mergeObjects<T>(target, source);
-  }
-
-  /**
-   * parses the JSON list, if it fails, it returns the answer as a single item in an array
-   * 
-   * (uses {@link DyFM_safeParseJSON})
-   */
-  static safeParseList<T extends Array<any>>(
-    textedJSON: string, 
-    disableErrorLog?: boolean
-  ): T {
-    const parsed = this.safeParseJSON<T>(textedJSON, true);
-
-    if (Array.isArray(parsed)) {
-      return parsed;
-    } else if (typeof parsed === 'object') {
-      if (!disableErrorLog) {
-        DyFM_Log.warn(
-          'DyFM_Object.safeParseList result is an object, returning its values', 
-          {
-            parsed: parsed,
-          }
-        );
-      }
-
-      return Object.values(parsed) as T;
-    } else {
-
-      if (!disableErrorLog) {
-        DyFM_Log.warn(
-          'DyFM_Object.safeParseList result is not an array or object, returning it as a single item', 
-          {
-            parsed: parsed,
-          }
-        );
-      }
-
-      return [ parsed ] as string[] as T;
-    }
-  }
-
-  /**
-   * parses the JSON, if it fails, it returns { unparsableResult: textedJSON }
-   * 
-   * (uses {@link DyFM_failableSafeParseJSON})
-   */
-  static safeParseJSON<T = any>(
-    textedJSON: string,
-    disableErrorLog?: boolean
-  ): T | DyFM_Object_ParseResult {
-    try {
-      return this.failableSafeParseJSON(textedJSON);
-    } catch (error) {
-      if (!disableErrorLog) {
-        DyFM_Log.error(
-          'Unable to parse JSON answer:', 
-          {
-            unparsedJSON: textedJSON,
-            error: error,
-          }
-        );
-      }
-
-      return { unparsableResult: textedJSON };
-    }
-  }
-
-  /**
-   * parses the JSON, if it fails, it throws an error
-   * (also will extract the JSON from "```json ... ```" wrapper)
-   * Uses enhanced error reporting with line context
-   */
-  static failableSafeParseJSON_old<T = any>(textedJSON: string): T {
-    if (!textedJSON) {
-      throw new Error(`No content provided to JSON parse ("${textedJSON}")`);
-    }
-
-    const match = textedJSON.match(/```json(.*)```/s);
-    // TODO; ez nem lesz az igazi, mert kiszedi a tartalmakból is a sortöréseket!!! (ugyan ez pár sorral lejjebb)
-    const cleanedTextedJSON = textedJSON.replaceAll('\n', '');
-
-    if (match) {
-      return DyFM_JsonErrorHelper.parseJsonWithEnhancedError(match[1].replaceAll('\n', ''));
-    } else {
-      return DyFM_JsonErrorHelper.parseJsonWithEnhancedError(
-        cleanedTextedJSON.replaceAll('```json', '').replaceAll('```', '')
-      );
-    }
-  }
-
-
-
-  /**
-   * parses the JSON, if it fails, it throws an error
-   * (also will extract the JSON from "```json ... ```" wrapper)
-   * Uses enhanced error reporting with line context
-   */
-  static failableSafeParseJSON<T = any>(textedJSON: string): T {
-    if (!textedJSON) {
-      throw new Error(`No content provided to JSON parse ("${textedJSON}")`);
-    }
-    
-    if (textedJSON.includes('```json')) {
-      // Extract content from code block, preserving newlines for error context
-      /* const extractedJson = match[1].trim(); */
-      const extractedJson = DyFM_String.multiBracketSplitDetailed(
-        textedJSON, 
-        [
-          { opening: '```json', closing: '```' },
-          { opening: '{', closing: '}' },
-          { opening: '[', closing: ']' },
-        ],
-        1,
-      )
-
-      // Check if we have extracted content and handle undefined cases
-      if (extractedJson.length > 1 && extractedJson[1] && extractedJson[1].brackets?.opening === '```json') {
-        return DyFM_JsonErrorHelper.parseJsonWithEnhancedError(extractedJson[1].content);
-      } else if (extractedJson.length > 0 && extractedJson[0]) {
-        return DyFM_JsonErrorHelper.parseJsonWithEnhancedError(extractedJson[0].content);
-      } else {
-        // Fallback if extraction fails - use original text minus markdown wrapper
-        const cleanedText = textedJSON.replace(/```json\s*/, '').replace(/\s*```$/, '').trim();
-        return DyFM_JsonErrorHelper.parseJsonWithEnhancedError(cleanedText);
-      }
-    } else {      
-      return DyFM_JsonErrorHelper.parseJsonWithEnhancedError(textedJSON.trim());
-    }
-  }
-
-  
-  /**
-   * Clone an object
-   * @param object - The object to clone
-   * @returns The cloned object
-   */
-  static clone<T>(object: T): T {
-    try {
-      return object ? JSON.parse(JSON.stringify(object)) as T : object;
-    } catch (error) {
-      DyFM_Log.error(
-        'clone()' + this.defaultErrorMsg,
-        error
-      );
-
-      throw error;
-    }
-  }
-  static readonly copy: typeof this.clone = this.clone;
-
-  /**
-   * Surface clone an object
-   * @param object - The object to surface clone
-   * @returns The surface cloned object
-   */
-  static surfaceClone<T extends Record<string, any>>(object: T): T {
-    try {
-      const result: Record<string, any> = {};
-
-      Object.keys(object).forEach((key: string): void => {
-        result[key] = object[key];
-      });
-
-      return result as T;
-    } catch (error) {
-      DyFM_Log.error(
-        'surfaceClone()' + this.defaultErrorMsg,
-        error
-      );
-
-      throw error;
-    }
-  }
-  static readonly surfaceCopy: typeof this.surfaceClone = this.surfaceClone;
-
-  /**
-   * Deep clone an object
-   * @param object - The object to deep clone
-   * @returns The deep cloned object
-   */
-  static deepClone<T extends Record<string, any>>(object: T): T {
-    try {
-      const result: Record<string, any> = {};
-
-      if (!object) {
-        return result as T;
-      }
-
-      Object.keys(object).forEach((key: string): void => {
-        if (typeof object[key] === 'object') {
-          result[key] = this.deepClone(object[key]);
-        } else if (Array.isArray(object[key])) {
-          result[key] = object[key].map((item: any): any => this.deepClone(item));
-        } else {
-          result[key] = object[key];
-        }
-      });
-
-      return result as T;
-    } catch (error) {
-      DyFM_Log.error(
-        'deepClone()' + this.defaultErrorMsg,
-        error
-      );
-
-      throw error;
-    }
-  }
-
-  /**
-   * A simple object comparison function that uses JSON.stringify() to compare objects.
-   * 
-   * We experienced that sameObjects() function is not working properly for cases when 
-   * deleting a key from the objects (to prevent strict results).
-   * So, we created orderedSameObject() function to prevent that issue.
-   * But be aware that, that function is not as fast as sameObjects() function.
-   */
-  static sameObjects<T>(objA: T, objB: T): boolean {
-    try {
-      return JSON.stringify(objA) === JSON.stringify(objB);
-    } catch (error) {
-      DyFM_Log.error(
-        'sameObjects()' + this.defaultErrorMsg,
-        error
-      );
-
-      throw error;
-    }
-  }
-
-  /**
-   * We experienced that sameObjects() function is not working properly for cases when 
-   * deleting a key from the objects (to prevent strict results).
-   * 
-   * This function is created to prevent that issue.
-   * But be aware that this function is not as fast as sameObjects() function.
-   */
-  static orderedSameObject<T>(objA: T, objB: T): boolean {
-    try {
-      if (
-        typeof objA !== 'object' || 
-        typeof objB !== 'object' ||
-        Array.isArray(objA) ||
-        Array.isArray(objB) ||
-        objA === null ||
-        objB === null ||
-        objA === undefined ||
-        objB === undefined
-      ) {
-        return JSON.stringify(objA) === JSON.stringify(objB);
-      }
-
-      const keysA = Object.keys(objA);
-      const keysB = Object.keys(objB);
-
-      if (keysA.length !== keysB.length) {
-        return false;
-      }
-
-      keysA.sort();
-      keysB.sort();
-
-      for (let i = 0; i < keysA.length; i++) {
-        if (JSON.stringify(keysA[i]) !== JSON.stringify(keysB[i])) {
-          return false;
-        }
-      }
-
-      return true;
-    } catch (error) {
-      /* try {
-        return DyFM_Object.orderedSameObject2(objA, objB);
-      } catch (error) { */
-        DyFM_Log.error(
-          'orderedSameObject()' + this.defaultErrorMsg,
-          error
-        );
-
-        throw error;
-      /* } */
-    }
-  }
-
-  /**
-   * We experienced that sameObjects() function is not working properly for cases when 
-   * deleting a key from the objects (to prevent strict results).
-   * 
-   * This function is created to prevent that issue.
-   * But be aware that this function is not as fast as sameObjects() function.
-   */
-  static orderedSameObject2<T>(objA: T, objB: T): boolean {
-    try {
-      console.log('using orderedSameObject2');
-      
-      if (
-        typeof objA !== 'object' || 
-        typeof objB !== 'object' ||
-        Array.isArray(objA) ||
-        Array.isArray(objB) ||
-        objA === null ||
-        objB === null ||
-        objA === undefined ||
-        objB === undefined
-      ) {
-        return JSON.stringify(objA) === JSON.stringify(objB);
-      } 
-      
-      return JSON.stringify(
-        objA, 
-        Object.keys(objA).sort()
-      ) === JSON.stringify(
-        objB, 
-        Object.keys(objB).sort()
-      );
-    } catch (error) {
-      DyFM_Log.error(
-        'sameObjects()' + this.defaultErrorMsg,
-        error
-      );
-
-      throw error;
-    }
-  }
-
-  /**
-   * compares the surface of two objects
-   * @param objA 
-   * @param objB 
-   * @returns 
-   */
-  static sameObjectSurface<T>(objA: T, objB: T): boolean {
-    let result = true;
-
-    for (const key in objA) {
-      if (objA[key] !== objB[key]) {
-        result = false;
-        break;
-      }
-    }
-
-    return result;
-  }
-
-  /**
-   * sets values if its existing on To, even if its null (but if undefined)
-   * @param setOn
-   * @param setTo 
-   */
-  static setExistingValuesOnly(setOn: any, setTo: any): void {
-    for (const key in setTo) {
-      if (setTo[key] != undefined) {
-        setOn[key] = setTo[key];
-      }
-    }
-  }
-
-  /**
-   * converts a JSONList to an array
-   * @param JSONList 
-   * @returns 
-   */
-  static JSONListify<T>(JSONList: any): T[] {
-    const result: T[] = [];
-
-    for (let i = 0; JSONList[i]; i++) {
-      result.push(JSONList[i]);
-    }
-
-    return result; 
-  }
-
-  static cleanAssign<T>(target: T, source: T): T {
-    source = this.cleanObject<T>(source);
-    return Object.assign<T, T>(target, source);
-  }
-
-  static hardParseJSON<T>(input: string): T | string {
-    try {
-      return JSON.parse(input);
-    } catch (error) {
-      try {
-        return this.failableSafeParseJSON(input);
-      } catch (error) {
-        const result: T | DyFM_Object_ParseResult = this.safeParseJSON(input);
-        
-        if ((result as DyFM_Object_ParseResult).unparsableResult) {
-          return (result as DyFM_Object_ParseResult).unparsableResult;
-        }
-        return result as T;
-      }
-    }
-  }
-
-}
+
+import { DyFM_Log } from './log.util';
+import { DyFM_JsonErrorHelper } from './json-error-helper.util';
+import { DyFM_String } from './string.util';
+
+export interface DyFM_Object_ParseResult {
+  unparsableResult: string;
+}
+
+export class DyFM_Object {
+
+  static readonly defaultErrorMsg = 
+    ' failed. ' +
+    '\nThis might be happening because the object you trying to clone, ' +
+    'contains object hooks for its own objects, therefore its creating an object loop. ' +
+    'See further information in the detailed error:\n\n';
+
+  /**
+   * returns remapped object list by path list
+   * @param objList object list to map
+   * @param paths string list of path etc.:
+   * ```ts
+   * [ [ 'first', 'sub', 'label' ], [ 'first', 'dif', 'name' ] ] 
+   * ``` 
+   * will be...
+   * from
+   * ```ts
+   * {
+   *   first: {
+   *     sub: {
+   *       label: 'vlmi'
+   *     },
+   *     dif: {
+   *       name: 'asd'
+   *     }
+   *   }
+   * }[]
+   * ```
+   * to
+   * ```
+   * { label: 'vlmi', name: 'asd' }[]
+   * ```
+   * @returns remapped object list (the final obj will use the deepest keys)
+   */
+  static mapObjList(objList: object[], paths: string[][]): object[] {
+    let newObjList: object[] = [ ...objList ];
+
+    newObjList = newObjList.map((obj): any => {
+      const newObj: any = {};
+
+      paths.forEach((path: string[]): void => {
+        newObj[path[path.length - 1]] = this.getNestedData(obj, path);
+      });
+
+      return newObj;
+    });
+
+    return newObjList;
+  }
+
+  /**
+   * returns nested value from object
+   * @param parentObj data source object
+   * @param nestedDataKeys path of value as string list
+   * etc.: ['nestLvl1', 'nestLvl2', 'nestLvl3'] as parentObj.nestLvl1.nestLvl2.nestLvl3
+   * @returns data from object by path
+   */
+  static getNestedData(parentObj: object, nestedDataKeys: string[]): any {
+    let newData: any = this.clone(parentObj); // {...parentObj};
+
+    nestedDataKeys.forEach((dk: string): void => {
+      if (newData) {
+        newData = newData[dk];
+      }
+    });
+
+    return newData;
+  }
+
+  /**
+   * recursive function that nests data
+   * @param newData the object that that is needed to be updated
+   * @param nestKeys the path where the data should be updated
+   * @param dataToSet the actual value that will be setted
+   * @returns modified data
+   */
+  static nestData(parentObj: object, nestKeys: string[], dataToSet: any): object {
+    const newData: any = this.clone(parentObj); // {...parentObj};
+
+    if (nestKeys.length > 1) {
+      const keys: string[] = [ ...nestKeys ];
+      const nextNestKey: string = keys.shift() as string;
+
+      newData[nextNestKey] = this.nestData(newData[nextNestKey], keys, dataToSet);
+    } else {
+      newData[nestKeys[0]] = dataToSet;
+    }
+
+    return newData;
+  }
+
+  /**
+   * recursive function that adds to nested data
+   * @param newData the object that that is needed to be updated
+   * @param nestKeys the path where the data should be updated
+   * @param dataToAdd the actual value that will be setted
+   * @returns modified data
+   */
+  static addToNestedData(parentObj: object, nestKeys: string[], dataToAdd: any): object {
+    const newData: any = this.clone(parentObj); // {...parentObj};
+
+    if (nestKeys.length > 1) {
+      const keys: string[] = [ ...nestKeys ];
+      const nextNestKey: string = keys.shift() as string;
+
+      newData[nextNestKey] = this.addToNestedData(newData[nextNestKey], keys, dataToAdd);
+    } else {
+      newData[nestKeys[0]] += dataToAdd;
+    }
+
+    return newData;
+  }
+
+  /**
+   * recursive function that pushes to nested data
+   * @param newData the object that that is needed to be updated
+   * @param nestKeys the path where the data should be updated
+   * @param dataToPush the actual value that will be setted
+   * @returns modified data
+   */
+  static pushToNestedData(parentObj: object, nestKeys: string[], dataToPush: any): object {
+    const newData: any = this.clone(parentObj); // {...parentObj};
+
+    if (nestKeys.length > 1) {
+      const keys: string[] = [ ...nestKeys ];
+      const nextNestKey: string = keys.shift() as string;
+
+      newData[nextNestKey] = this.pushToNestedData(newData[nextNestKey], keys, dataToPush);
+    } else {
+      if (Array.isArray(newData[nestKeys[0]])) {
+        newData[nestKeys[0]].push(dataToPush);
+      } else {
+        newData[nestKeys[0]] = [ dataToPush ];
+      }
+    }
+
+    return newData;
+  }
+
+  /**
+   * recursive function that nests data on recursive data structure etc.: xData: { ..., 'nestedListKey': xData[] }
+   * @param newData the object that that is needed to be updated
+   * @param nestedListKey the location of nested dataList
+   * @param nestIndexes path to the subject ect.: xData.listKey[1].listKey[4].listKey[0] will be [1, 4, 0]
+   * @param dataToSet the actual value that will be seted on location
+   * @returns modified data
+   */
+  static nestRecursiveListedData<T>(
+    parentObj: T, 
+    nestedListKey: string, 
+    nestIndexes: number[], 
+    dataToSet: any
+  ): T {
+    const newData: any = this.clone(parentObj); // parentObj; // {...parentObj};
+
+    if (nestIndexes.length > 1) {
+      const indexes: number[] = [ ...nestIndexes ];
+      const nextLevelKey: number = indexes.shift() as number;
+
+      newData[nestedListKey][nextLevelKey] = this.nestRecursiveListedData(
+        newData[nestedListKey][nextLevelKey], nestedListKey, indexes, dataToSet
+      );
+    } else {
+      newData[nestedListKey][nestIndexes[0]] = dataToSet;
+    }
+
+    return newData;
+  }
+
+  static readonly removeCirculation = this.resolveCirculation;
+  /**
+   * THIS STILL NOT WORKING AS IT SHOULD
+   * 
+   * recursive function that returns mutated data structure, 
+   * with locations at which circular references are found
+   */
+  static resolveCirculation<T>(
+    data: T, 
+    location: string[] = [ ('ROOT;' + data?.constructor?.name) ], 
+    objs: any[] = [],
+    /* arrs: any[] = [] */
+  ): any {
+    if (!data || typeof data !== 'object') {
+      return data;
+    } else if (objs.includes(data)) {
+      return 'CIRCULATION:' + location.join('.');
+    }
+    
+    let newData: any;
+
+    if (Array.isArray(data)) {
+      newData = [];
+    } else {
+      newData = {};
+    }
+
+    // using the utility that Object.keys will return array keys if the data is an array
+    Object.keys(data).forEach((key: string): void => {
+      newData[key] = this.resolveCirculation(
+        data[key as keyof typeof data], 
+        [ ...location, key ], 
+        [ ...objs, data ]
+      );
+    });
+
+    return newData;
+  }
+
+
+  /**
+   * looks for circular references in object
+   * returns duplicated object's all location paths and the object itself
+   *  
+   *  { 
+   *    object: any,
+   *    pathsOfAllDuplications: string[],
+   *  }[]
+   * 
+   * paths are in a single string, separated by '.'
+   */
+  static findCirculations(
+    data: any, 
+    location: string[] = [ ('ROOT;' + data?.constructor?.name) ], 
+    objs: any[] = [],
+    duplications: { object: any, pathsOfAllDuplications: string[] }[] = []
+  ): { object: any, pathsOfAllDuplications: string[] }[] {
+    if (!data || typeof data !== 'object') {
+      return duplications;
+    } else if (objs.includes(data)) {
+      duplications.push({
+        object: data,
+        pathsOfAllDuplications: location,
+      });
+    }
+
+    Object.keys(data).forEach((key: string): void => {
+      this.findCirculations(
+        data[key], 
+        [ ...location, key ], 
+        [ ...objs, data ],
+        duplications
+      );
+    });
+
+    return duplications;
+  }
+
+  /**
+   * removes all undefined (will keep all null, false, 0, '', NaN etc.)
+   * 
+   * (not supports lists in lists!)
+   * 
+   * (this also modifies the original object in place)
+   */
+  static safeCleanObject<T>(obj: T): T {
+    try {
+      return this.cleanObject<T>(obj);
+    } catch (error) {
+      DyFM_Log.error('Error cleaning object:', error);
+      return obj;
+    }
+  }
+
+  /**
+   * cleans the object, by removing all undefined values (but keeps all null, false, 0, '', NaN etc.)
+   * (this is a deep clean)
+   * 
+   * (this also modifies the original object in place)
+   */
+  static cleanObject<T>(obj: T, cleanings: any[] = []): T {
+    if (!obj || typeof obj !== 'object' || cleanings.includes(obj)) {
+      return obj;
+    }
+
+    cleanings.push(obj);
+
+    Object.keys(obj).forEach((key: string): void => {
+      if (obj[key] === undefined) {
+        delete obj[key];
+      } else if (Array.isArray(obj[key])) {
+        obj[key].forEach((item: any): void => {
+          if (typeof item === 'object') {
+            this.cleanObject(item, cleanings);
+          }
+        });
+      } else if (typeof obj[key] === 'object') {
+        this.cleanObject(obj[key], cleanings);
+      }
+    });
+
+    return obj;
+  }
+
+  /** 
+   * merges two objects, if the target object is not an object, it will be replaced by the source object
+   * it will iterate through the source object 
+   *   and will set the values to the target object
+   * (like a patch, with deep merge)
+   * 
+   * (this also modifies the original target object in place)
+   */
+  static mergeObjects<T>(target: T, source: T): T {  
+    if (typeof source === 'object') {
+      target ??= {} as T;
+  
+      for (const key in source) {
+        if (source[key] instanceof Object) {
+          target[key] = this.mergeObjects(target[key], source[key]);
+        } else if (Array.isArray(source[key])) {
+          target[key] ??= [] as T[Extract<keyof T, string>];
+          source[key].forEach(item => {
+            if (
+              !(target[key] as Array<any>).includes(item) &&
+              !((target[key] as Array<any>).some(targetItem => this.sameObjects(item, targetItem)))
+            ) {
+              (target[key] as Array<any>).push(item);
+            }
+          });
+        } else {
+          target[key] = source[key];
+        }
+      }
+    }
+  
+    return target;
+  }
+  
+  /**
+   * cleans the source object and merges it to the target object
+   * 
+   * (this also modifies the original objects in place! (source AND target))
+   */
+  static patchObject<T>(target: T, source: T): T {
+    this.cleanObject<T>(source);
+    return this.mergeObjects<T>(target, source);
+  }
+
+  /**
+   * parses the JSON list, if it fails, it returns the answer as a single item in an array
+   * 
+   * (uses {@link DyFM_safeParseJSON})
+   */
+  static safeParseList<T extends Array<any>>(
+    textedJSON: string, 
+    disableErrorLog?: boolean
+  ): T {
+    const parsed = this.safeParseJSON<T>(textedJSON, true);
+
+    if (Array.isArray(parsed)) {
+      return parsed;
+    } else if (typeof parsed === 'object') {
+      if (!disableErrorLog) {
+        DyFM_Log.warn(
+          'DyFM_Object.safeParseList result is an object, returning its values', 
+          {
+            parsed: parsed,
+          }
+        );
+      }
+
+      return Object.values(parsed) as T;
+    } else {
+
+      if (!disableErrorLog) {
+        DyFM_Log.warn(
+          'DyFM_Object.safeParseList result is not an array or object, returning it as a single item', 
+          {
+            parsed: parsed,
+          }
+        );
+      }
+
+      return [ parsed ] as string[] as T;
+    }
+  }
+
+  /**
+   * parses the JSON, if it fails, it returns { unparsableResult: textedJSON }
+   * 
+   * (uses {@link DyFM_failableSafeParseJSON})
+   */
+  static safeParseJSON<T = any>(
+    textedJSON: string,
+    disableErrorLog?: boolean
+  ): T | DyFM_Object_ParseResult {
+    try {
+      return this.failableSafeParseJSON(textedJSON);
+    } catch (error) {
+      if (!disableErrorLog) {
+        DyFM_Log.error(
+          'Unable to parse JSON answer:', 
+          {
+            unparsedJSON: textedJSON,
+            error: error,
+          }
+        );
+      }
+
+      return { unparsableResult: textedJSON };
+    }
+  }
+
+  /**
+   * parses the JSON, if it fails, it throws an error
+   * (also will extract the JSON from "```json ... ```" wrapper)
+   * Uses enhanced error reporting with line context
+   */
+  static failableSafeParseJSON_old<T = any>(textedJSON: string): T {
+    if (!textedJSON) {
+      throw new Error(`No content provided to JSON parse ("${textedJSON}")`);
+    }
+
+    const match = textedJSON.match(/```json(.*)```/s);
+    // TODO; ez nem lesz az igazi, mert kiszedi a tartalmakból is a sortöréseket!!! (ugyan ez pár sorral lejjebb)
+    const cleanedTextedJSON = textedJSON.replaceAll('\n', '');
+
+    if (match) {
+      return DyFM_JsonErrorHelper.parseJsonWithEnhancedError(match[1].replaceAll('\n', ''));
+    } else {
+      return DyFM_JsonErrorHelper.parseJsonWithEnhancedError(
+        cleanedTextedJSON.replaceAll('```json', '').replaceAll('```', '')
+      );
+    }
+  }
+
+
+
+  /**
+   * parses the JSON, if it fails, it throws an error
+   * (also will extract the JSON from "```json ... ```" wrapper)
+   * Uses enhanced error reporting with line context
+   */
+  static failableSafeParseJSON<T = any>(textedJSON: string): T {
+    if (!textedJSON) {
+      throw new Error(`No content provided to JSON parse ("${textedJSON}")`);
+    }
+    
+    if (textedJSON.includes('```json')) {
+      // Extract content from code block, preserving newlines for error context
+      /* const extractedJson = match[1].trim(); */
+      const extractedJson = DyFM_String.multiBracketSplitDetailed(
+        textedJSON, 
+        [
+          { opening: '```json', closing: '```' },
+          { opening: '{', closing: '}' },
+          { opening: '[', closing: ']' },
+        ],
+        1,
+      )
+
+      // Check if we have extracted content and handle undefined cases
+      if (extractedJson.length > 1 && extractedJson[1] && extractedJson[1].brackets?.opening === '```json') {
+        return DyFM_JsonErrorHelper.parseJsonWithEnhancedError(extractedJson[1].content);
+      } else if (extractedJson.length > 0 && extractedJson[0]) {
+        return DyFM_JsonErrorHelper.parseJsonWithEnhancedError(extractedJson[0].content);
+      } else {
+        // Fallback if extraction fails - use original text minus markdown wrapper
+        const cleanedText = textedJSON.replace(/```json\s*/, '').replace(/\s*```$/, '').trim();
+        return DyFM_JsonErrorHelper.parseJsonWithEnhancedError(cleanedText);
+      }
+    } else {      
+      return DyFM_JsonErrorHelper.parseJsonWithEnhancedError(textedJSON.trim());
+    }
+  }
+
+  
+  /**
+   * Clone an object
+   * @param object - The object to clone
+   * @returns The cloned object
+   */
+  static clone<T>(object: T): T {
+    try {
+      return object ? JSON.parse(JSON.stringify(object)) as T : object;
+    } catch (error) {
+      DyFM_Log.error(
+        'clone()' + this.defaultErrorMsg,
+        error
+      );
+
+      throw error;
+    }
+  }
+  static readonly copy: typeof this.clone = this.clone;
+
+  /**
+   * Surface clone an object
+   * @param object - The object to surface clone
+   * @returns The surface cloned object
+   */
+  static surfaceClone<T extends Record<string, any>>(object: T): T {
+    try {
+      const result: Record<string, any> = {};
+
+      Object.keys(object).forEach((key: string): void => {
+        result[key] = object[key];
+      });
+
+      return result as T;
+    } catch (error) {
+      DyFM_Log.error(
+        'surfaceClone()' + this.defaultErrorMsg,
+        error
+      );
+
+      throw error;
+    }
+  }
+  static readonly surfaceCopy: typeof this.surfaceClone = this.surfaceClone;
+
+  /**
+   * Deep clone an object
+   * @param object - The object to deep clone
+   * @returns The deep cloned object
+   */
+  static deepClone<T extends Record<string, any>>(object: T): T {
+    try {
+      const result: Record<string, any> = {};
+
+      if (!object) {
+        return result as T;
+      }
+
+      Object.keys(object).forEach((key: string): void => {
+        if (typeof object[key] === 'object') {
+          result[key] = this.deepClone(object[key]);
+        } else if (Array.isArray(object[key])) {
+          result[key] = object[key].map((item: any): any => this.deepClone(item));
+        } else {
+          result[key] = object[key];
+        }
+      });
+
+      return result as T;
+    } catch (error) {
+      DyFM_Log.error(
+        'deepClone()' + this.defaultErrorMsg,
+        error
+      );
+
+      throw error;
+    }
+  }
+
+  /**
+   * A simple object comparison function that uses JSON.stringify() to compare objects.
+   * 
+   * We experienced that sameObjects() function is not working properly for cases when 
+   * deleting a key from the objects (to prevent strict results).
+   * So, we created orderedSameObject() function to prevent that issue.
+   * But be aware that, that function is not as fast as sameObjects() function.
+   */
+  static sameObjects<T>(objA: T, objB: T): boolean {
+    try {
+      return JSON.stringify(objA) === JSON.stringify(objB);
+    } catch (error) {
+      DyFM_Log.error(
+        'sameObjects()' + this.defaultErrorMsg,
+        error
+      );
+
+      throw error;
+    }
+  }
+
+  /**
+   * We experienced that sameObjects() function is not working properly for cases when 
+   * deleting a key from the objects (to prevent strict results).
+   * 
+   * This function is created to prevent that issue.
+   * But be aware that this function is not as fast as sameObjects() function.
+   */
+  static orderedSameObject<T>(objA: T, objB: T): boolean {
+    try {
+      if (
+        typeof objA !== 'object' || 
+        typeof objB !== 'object' ||
+        Array.isArray(objA) ||
+        Array.isArray(objB) ||
+        objA === null ||
+        objB === null ||
+        objA === undefined ||
+        objB === undefined
+      ) {
+        return JSON.stringify(objA) === JSON.stringify(objB);
+      }
+
+      const keysA = Object.keys(objA);
+      const keysB = Object.keys(objB);
+
+      if (keysA.length !== keysB.length) {
+        return false;
+      }
+
+      keysA.sort();
+      keysB.sort();
+
+      for (let i = 0; i < keysA.length; i++) {
+        if (JSON.stringify(keysA[i]) !== JSON.stringify(keysB[i])) {
+          return false;
+        }
+      }
+
+      return true;
+    } catch (error) {
+      /* try {
+        return DyFM_Object.orderedSameObject2(objA, objB);
+      } catch (error) { */
+        DyFM_Log.error(
+          'orderedSameObject()' + this.defaultErrorMsg,
+          error
+        );
+
+        throw error;
+      /* } */
+    }
+  }
+
+  /**
+   * We experienced that sameObjects() function is not working properly for cases when 
+   * deleting a key from the objects (to prevent strict results).
+   * 
+   * This function is created to prevent that issue.
+   * But be aware that this function is not as fast as sameObjects() function.
+   */
+  static orderedSameObject2<T>(objA: T, objB: T): boolean {
+    try {
+      console.log('using orderedSameObject2');
+      
+      if (
+        typeof objA !== 'object' || 
+        typeof objB !== 'object' ||
+        Array.isArray(objA) ||
+        Array.isArray(objB) ||
+        objA === null ||
+        objB === null ||
+        objA === undefined ||
+        objB === undefined
+      ) {
+        return JSON.stringify(objA) === JSON.stringify(objB);
+      } 
+      
+      return JSON.stringify(
+        objA, 
+        Object.keys(objA).sort()
+      ) === JSON.stringify(
+        objB, 
+        Object.keys(objB).sort()
+      );
+    } catch (error) {
+      DyFM_Log.error(
+        'sameObjects()' + this.defaultErrorMsg,
+        error
+      );
+
+      throw error;
+    }
+  }
+
+  /**
+   * compares the surface of two objects
+   * @param objA 
+   * @param objB 
+   * @returns 
+   */
+  static sameObjectSurface<T>(objA: T, objB: T): boolean {
+    let result = true;
+
+    for (const key in objA) {
+      if (objA[key] !== objB[key]) {
+        result = false;
+        break;
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * sets values if its existing on To, even if its null (but if undefined)
+   * @param setOn
+   * @param setTo 
+   */
+  static setExistingValuesOnly(setOn: any, setTo: any): void {
+    for (const key in setTo) {
+      if (setTo[key] != undefined) {
+        setOn[key] = setTo[key];
+      }
+    }
+  }
+
+  /**
+   * converts a JSONList to an array
+   * @param JSONList 
+   * @returns 
+   */
+  static JSONListify<T>(JSONList: any): T[] {
+    const result: T[] = [];
+
+    for (let i = 0; JSONList[i]; i++) {
+      result.push(JSONList[i]);
+    }
+
+    return result; 
+  }
+
+  static cleanAssign<T>(target: T, source: T): T {
+    source = this.cleanObject<T>(source);
+    return Object.assign<T, T>(target, source);
+  }
+
+  static hardParseJSON<T>(input: string): T | string {
+    try {
+      return JSON.parse(input);
+    } catch (error) {
+      try {
+        return this.failableSafeParseJSON(input);
+      } catch (error) {
+        const result: T | DyFM_Object_ParseResult = this.safeParseJSON(input);
+        
+        if ((result as DyFM_Object_ParseResult).unparsableResult) {
+          return (result as DyFM_Object_ParseResult).unparsableResult;
+        }
+        return result as T;
+      }
+    }
+  }
+
+}