@futdevpro/fsm-dynamo 1.16.38 → 1.16.40

package/src/_modules/data-handler/_models/data-handler.control-model.ts

@@ -1,486 +1,486 @@
-import { DyFM_Log, DyFM_Metadata, DyFM_SearchQuery, DyFM_SearchResult } from '../../..';
-import { BehaviorSubject, Observable } from 'rxjs';
-
-import { DyFM_DataHandler_Settings } from './data-handler-settings.control-model';
-
-/**
- * DyFM_DataHandlerDataLoadInProgress
- */
-export interface DyFM_DataHandlerDataLoadInProgress<T_LoadBy> {
-  loadBy: T_LoadBy;
-  progress: Promise<any>;
-}
-
-/**
- * DyFM_DataHandlerDataPostProcess
- */
-export type DyFM_DataHandlerDataLoadPostProcess<T_LoadBy> = (data: any, loadedBy: T_LoadBy) => Promise<any> | any;
-
-/**
- * DynamoDataHandler is used to create application wide data handling
- * used to create subscribeAble data handler
- *
- * this implements data reload function that uses predefined apiService,
- * using previous or given id,
- * prevents multiple load calls and triggers data change subscriptions when done
- *
- * load post processes can be implemented to ensure special conditions
- *
- * @example
- * personalInformationDH = new DynamoDataHandler<PersonalInformation>({
- *   apiService: this.accountApiService,
- *   getDataFunctionName: 'getPersonalInformation',
- * });
- */
-export abstract class DyFM_DataHandler<
-  T extends DyFM_Metadata | DyFM_Metadata[],
-  T_Dependency extends DyFM_Metadata = any,
-  T_LoadBy = string
-> {
-  name: string;
-
-  /**
-   * BehaviorSubject that holds the current data value.
-   * This is the source of truth for data in DyFM.
-   */
-  protected readonly data_BS: BehaviorSubject<T>;
-
-  /**
-   * Observable that emits the current data value.
-   * Derived from the BehaviorSubject.
-   */
-  readonly data$: Observable<T>;
-
-  /**
-   * BehaviorSubject that indicates whether the data has been loaded.
-   * True when data is loaded, false otherwise.
-   */
-  protected readonly loaded_BS: BehaviorSubject<boolean>;
-
-  /**
-   * Observable that indicates whether the data has been loaded.
-   */
-  readonly loaded$: Observable<boolean>;
-
-  /**
-   * BehaviorSubject that tracks the current loading operation.
-   * Contains information about the ongoing data load operation or false if no load is in progress.
-   */
-  protected readonly loadInProgress_BS: BehaviorSubject<DyFM_DataHandlerDataLoadInProgress<T_LoadBy> | false>;
-
-  /**
-   * Observable that tracks the current loading operation.
-   */
-  readonly loadInProgress$: Observable<DyFM_DataHandlerDataLoadInProgress<T_LoadBy> | false>;
-
-  /**
-   * Gets the current data value.
-   * @returns The current data value
-   */
-  abstract get data(): T;
-
-  /**
-   * last loaded by will work properly only if you use the Dynamo form of "_id" for loading
-   */
-  lastLoadedBy: T_LoadBy; // for lists
-  defaultLoadBy: T_LoadBy; // for lists
-
-  /** this will handle the data loading from the api */
-  protected readonly get: (loadBy?: T_LoadBy) => Promise<any>;
-  /** this will handle the data setting to the data handler */
-  protected readonly set: (data: T) => Promise<T>;
-  /** this will handle the data patching to the data handler */
-  /* patch: (data: T) => Promise<T>; */
-
-  // TODO
-  /* directApiSetup: any; */
-
-  /**
-   * post processes will be called as pipes after data is loaded by get function,
-   * but before data is set to data handler by data_$.set (after get, before Signal triggers)
-   */
-  protected readonly getPostProcesses: DyFM_DataHandlerDataLoadPostProcess<T_LoadBy>[] = [];
-
-  noId?: boolean;
-
-  waitsOnLoad: {
-    promise: Promise<void>;
-    resolve: () => void;
-  }[] = [];
-
-  protected readonly dependentDataHandlers?: DyFM_DataHandler<any>[] = [];
-
-  debugLog?: boolean;
-
-  /**
-   * DynamoDataHandler
-   * @param apiService any service can be used as apiService
-   * as long as the function, you pass in getDataFunctionName exists,
-   * uses (or not uses an ID as input) and returns the data as Promise<Type>
-   * @param getDataFunctionName the function name on the apiService,
-   * that will be used as get api call
-   *
-   * @param successfulReloadCallBack you can create direct callback for successful reloads
-   * by passing it here
-   *
-   * @param getPostPreprocessLoad post processes can be implemented to ensure special conditions on data
-   *
-   * @param defaultValue you can set default value that will be used before any load
-   * @param noId this flag needs to be true, when using api function without id
-   *
-   * @example
-   * personalInformationDH = new DynamoDataHandler<PersonalInformation>({
-   *   apiService: this.accountApiService,
-   *   getDataFunctionName: 'getPersonalInformation',
-   * });
-   */
-  constructor(
-    set: DyFM_DataHandler_Settings<T, T_Dependency, T_LoadBy>,
-    /** is in construct? 
-     * so the dependent data handlers are not added here, but in the extended class */
-    skipDependencyConnections?: boolean
-  ) {
-    // TODO: + TRYTOGETTYPE(this.data);
-    if (!set.name) {
-      set.name = 'Unnamed DataHandler ' + (+new Date());
-
-      DyFM_Log.warn(
-        `DYNAMO DH.constructor (${this.name}) WARN: ` +
-        `\n  Name is not set!`,
-        '\n\n', new Error()
-      );
-    }
-
-    this.name = set.name; 
-    this.debugLog = set?.debugLog;
-
-    // Initialize BehaviorSubjects
-    this.data_BS = new BehaviorSubject<T>(set.defaultValue);
-    this.data$ = this.data_BS.asObservable();
-    
-    this.loaded_BS = new BehaviorSubject<boolean>(false);
-    this.loaded$ = this.loaded_BS.asObservable();
-    
-    this.loadInProgress_BS = new BehaviorSubject<DyFM_DataHandlerDataLoadInProgress<T_LoadBy> | false>(false);
-    this.loadInProgress$ = this.loadInProgress_BS.asObservable();
-
-    if (set.get) {
-      this.get = set.get;
-    }
-
-    if (set.set) {
-      this.set = set.set;
-    }
-
-    this.noId = !!set.noId;
-
-    if (set.defaultLoadBy) {
-      this.defaultLoadBy = set.defaultLoadBy;
-    }
-
-    if (!skipDependencyConnections) {
-      if (set.dependencyDataHandler) {
-        this.addDependencyDataHandler(set.dependencyDataHandler);
-      }
-  
-      if (set.dependentDataHandlers) {
-        this.addDependentDataHandlers(set.dependentDataHandlers, true);
-      }
-    }
-
-    if (set.getPostProcess) {
-      this.getPostProcesses.push(set.getPostProcess);
-    }
-  }
-
-  addDependencyDataHandler(dependencyDataHandler: DyFM_DataHandler<any>): void {
-    try {
-      if (!dependencyDataHandler) {
-        throw new Error(
-          `DYNAMO DH.addDependencyDataHandler (${this.name}) ERROR: ` +
-          `\n  Dependent DataHandler is null or undefined! (${this.name})`
-        );
-      }
-  
-      if (!(dependencyDataHandler instanceof DyFM_DataHandler)) {
-        throw new Error(
-          `DYNAMO DH.addDependencyDataHandler (${this.name}) ERROR: ` +
-          `\n  Dependent DataHandler is not instance of DyFM_DataHandler! (${this.name})`
-        );
-      }
-  
-      dependencyDataHandler.addDependentDataHandlers([ this ]);
-    } catch (error) {
-      console.error(
-        `DYNAMO DH.addDependencyDataHandler (${this.name}) ERROR: ` +
-        `\n  Failed to add dependency data handler! ("${this.name}": "${this.constructor.name}")`,
-        '\n\n', error,
-        '\n\n', new Error()
-      );
-    }
-  }
-
-  addDependentDataHandlers(
-    dependentDataHandlers: DyFM_DataHandler<any, any, any>[],
-    isInConstruct?: boolean
-  ): void {
-    dependentDataHandlers.forEach((dependent_DH: DyFM_DataHandler<any>): void => {
-      if (!dependent_DH) {
-        throw new Error(
-          `DYNAMO DH.addDependentDataHandlers (${this.name}) ERROR: ` +
-          `\n  Dependent DataHandler is null or undefined! (${this.name})`
-        );
-      }
-
-      if (!(dependent_DH instanceof DyFM_DataHandler)) {
-        throw new Error(
-          `DYNAMO DH.addDependentDataHandlers (${this.name}) ERROR: ` +
-          `\n  Dependent DataHandler is not instance of DyFM_DataHandler! (${this.name})`
-        );
-      }
-
-      if (dependent_DH.name === this.name) {
-        throw new Error(
-          `DYNAMO DH.addDependentDataHandlers (${this.name}) ERROR: ` +
-          `\n  Dependent DataHandler has the same name as the current DataHandler! (${this.name})`
-        );
-      }
-
-      if (!dependent_DH.data_BS) {
-        throw new Error(
-          `DYNAMO DH.addDependentDataHandlers (${this.name}) ERROR: ` +
-          `\n  Dependent DataHandler has not been set up yet! ` +
-          `(this: "${this.name}", dependent: "${dependent_DH.name}")` +
-          `\n    Try the opposite direction of dependency!\n\n`
-        );
-      }
-
-      if (!dependentDataHandlers.includes(dependent_DH)) {
-        dependentDataHandlers.push(dependent_DH);
-      }
-
-      if (this.debugLog) {
-        this.getPostProcesses.push(async (newData: T): Promise<T> => {
-          console.log(
-            `DYNAMO DH.addDependentDataHandlers (${this.name}) DEBUG:` +
-            `\nDataHandler triggering dependent dataHandler (${dependent_DH.name}) to reload... ` +
-            `\n(using id: ${newData && (newData as DyFM_Metadata)._id ? (newData as DyFM_Metadata)._id : ''})`
-          );
-
-          return newData;
-        });
-      }
-
-      this.getPostProcesses.push(
-        async (newData: T): Promise<T> => {
-          if (newData && (newData as DyFM_Metadata)._id && (newData as DyFM_Metadata)._id !== dependent_DH.lastLoadedBy) {
-            dependent_DH.reloadData((newData as DyFM_Metadata)._id);
-          } else if (!newData) {
-            dependent_DH.clear();
-          }
-
-          return newData;
-        }
-      );
-
-      if (!isInConstruct && this.data) {
-        dependent_DH.reloadData((this.data as DyFM_Metadata)._id);
-      }
-    });
-  }
-
-  /**
-   * reloads data on DynamoDataHandler using predefined apiservice,
-   * using previous or given id,
-   * prevents multiple load calls and triggers data change subscriptions when done
-   * @param loadBy previous or given id (or can be disabled trough setup by: { noId: true })
-   * @returns the data as Promise<T>, finishes when the call ends (throws error on fail)
-   */
-  async reloadData(loadBy?: T_LoadBy, opts?: { silentMissingId?: boolean }): Promise<T> {
-    try {
-      const loadInProgress = this.loadInProgress_BS.value;
-      const useLoadBy: T_LoadBy = loadBy ??
-        ((this.data as DyFM_Metadata)?._id as T_LoadBy) ??
-        this.lastLoadedBy ??
-        this.defaultLoadBy;
-
-      if (!useLoadBy && !this.noId) {
-        // BFR-MASTERPROMPTER-024: a getData not-loaded-yet útján (silentMissingId) a console.error
-        // kimarad — a boot-race ID-hiány nem caller-hiba; a throw változatlanul megy.
-        if (!opts?.silentMissingId) {
-          console.error(
-            `DynamoERROR (DH.reloadData): Missing ID! (${this.name})`,
-            this.data,
-            '\n\n', new Error()
-          );
-        }
-
-        throw new Error(`DynamoERROR (DH.reloadData): Missing ID! (${this.name})`);
-      }
-
-      if (loadInProgress && loadInProgress.loadBy === useLoadBy) {
-        if (this.debugLog) {
-          console.log(
-            `DYNAMO DH.reloadData (${this.name}) DEBUG:` +
-            `\n  DataHandler reloadData... (using id: ${useLoadBy})` +
-            `\n  DataHandler is already loading data...`
-          );
-        }
-
-        return this.data;
-      }
-
-      if (this.debugLog) {
-        console.log(
-          `DYNAMO DH.reloadData (${this.name}) DEBUG:` +
-          `\n  DataHandler reloadData... (using id: ${useLoadBy})`
-        );
-      }
-
-      const loadProgress = this.doReloadDataBy(useLoadBy);
-      this.loadInProgress_BS.next({ 
-        loadBy: useLoadBy,
-        progress: loadProgress
-      });
-      loadProgress.finally(() => {
-        this.loadInProgress_BS.next(false);
-      });
-
-      return await loadProgress;      
-    } catch (error) {
-      this.loadInProgress_BS.next(false);
-      this.loaded_BS.next(false);
-
-      if (!error?.error?.handled) {
-        console.error(
-          `DYNAMO DH.reloadData (${this.name}) ERROR: ` +
-          `\n  reloadData was UNSUCCESSFUL`,
-          '\n\n', error,
-          '\n\n', new Error()
-        );
-
-        if (error?.error?.flag?.includes('DYNAMO')) {
-          error.error.handled = true;
-        }
-      }
-
-      throw error;
-    }
-  }
-
-  async getData(): Promise<T> {
-    if (!this.data) {
-      const loadProgress = this.loadInProgress_BS.value;
-      if (loadProgress) {
-        return await loadProgress.progress;
-      } else {
-        // BFR-MASTERPROMPTER-024: not-loaded-yet út → silent missing-ID (a throw marad).
-        return await this.reloadData(undefined, { silentMissingId: true });
-      }
-    } else {
-      return this.data;
-    }
-  }
-
-  protected async doReloadDataBy(loadedBy: T_LoadBy): Promise<T> {
-    try {
-      this.lastLoadedBy = loadedBy;
-
-      return await this.processLoadResult(await this.get(loadedBy), loadedBy);
-    } catch (error) {
-      this.resolveWaitsOnLoad();
-      throw error;
-    }
-  }
-
-  /**
-   * A DataHandler adatának közvetlen frissítése egy már ismert value-val, szerver-round-trip NÉLKÜL
-   * (pl. login-response → user_DH.updateData). Alapból CSAK a saját data_BS-t frissíti.
-   *
-   * @param reloadDependents opt-in (BFR-MASTERPROMPTER-013): ha true, a `reloadData` post-process
-   *   dependent-reload-láncát is meghajtja — a függő DataHandler-ek (pl. token-balance) újratöltődnek
-   *   az új adat `_id`-jével. A `reloadData` (hard-nav boot) útján ez a lánc automatikus, de az
-   *   `updateData` (round-trip-mentes) útján eddig NEM futott → a friss SPA-login után a dependent-DH
-   *   adatok üresek maradtak hard-reload-ig. DEFAULT false (backward-safe): az `updateData` fő szándéka
-   *   ÉPP a szerver-hívás elkerülése, ezért a vak dependent-reload nem kívánt HTTP-flood-ot okozhatna.
-   */
-  async updateData(data: T, dontSendUpdate?: boolean, reloadDependents?: boolean): Promise<void> {
-    if (this.set && !dontSendUpdate) {
-      this.data_BS.next(await this.set(data));
-    } else {
-      this.data_BS.next(data);
-    }
-
-    if (reloadDependents) {
-      // ugyanaz a reload-vagy-clear logika, mint a reloadData post-process-e (dependent-lánc)
-      this.dependentDataHandlers?.forEach((dependent_DH: DyFM_DataHandler<any>): void => {
-        if (data && (data as DyFM_Metadata)._id && (data as DyFM_Metadata)._id !== dependent_DH.lastLoadedBy) {
-          dependent_DH.reloadData((data as DyFM_Metadata)._id);
-        } else if (!data) {
-          dependent_DH.clear();
-        }
-      });
-    }
-  }
-
-  clear(dontClearDependents?: boolean): void {
-    this.data_BS.next(undefined);
-    this.lastLoadedBy = undefined;
-    if (!dontClearDependents) {
-      this.dependentDataHandlers.forEach((ddh: DyFM_DataHandler<any>): void => {
-        ddh.clear();
-      });
-    }
-  }
-
-  protected async processLoadResult(result: any, loadedBy: T_LoadBy): Promise<T> {
-    if (this.debugLog) {
-      console.log(
-        `DYNAMO DH.processLoadResult (${this.name}) DEBUG:` +
-        `\n  DataHandler processLoadResult... (using id: ${loadedBy})` +
-        `\n  Result:`, result
-      );
-    }
-
-    for (const postProcess of this.getPostProcesses) {
-      if (this.debugLog) {
-        console.log(
-          `DYNAMO DH.processLoadResult (${this.name}) DEBUG:` +
-          `\n  Post process:`, postProcess
-        );
-      }
-      
-      result = await postProcess(result, loadedBy);
-
-      if (!result) {
-        DyFM_Log.warn(
-          `DYNAMO DH.processLoadResult (${this.name}) WARN: ` +
-          `\nPost process returned null or undefined!`,
-          '\n\n', new Error()
-        );
-      }
-    }
-    this.data_BS.next(result);
-    this.loaded_BS.next(true);
-    this.resolveWaitsOnLoad();
-    return result;
-  }
-
-  private resolveWaitsOnLoad(): void {
-    this.waitsOnLoad.forEach(({ promise, resolve }) => {
-      resolve();
-    });
-    this.waitsOnLoad = [];
-  }
-
-  /**
-   * waits for the first load to finish
-   * @returns a promise that resolves when the first load finishes after this "subscription"
-   */
-  waitForLoad(): Promise<void> {
-    let resolve: (value: void) => void;
-    const promise = new Promise<void>((r) => { resolve = r; });
-    this.waitsOnLoad.push({ promise, resolve });
-    return promise;
-  }
-}
+import { DyFM_Log, DyFM_Metadata, DyFM_SearchQuery, DyFM_SearchResult } from '../../..';
+import { BehaviorSubject, Observable } from 'rxjs';
+
+import { DyFM_DataHandler_Settings } from './data-handler-settings.control-model';
+
+/**
+ * DyFM_DataHandlerDataLoadInProgress
+ */
+export interface DyFM_DataHandlerDataLoadInProgress<T_LoadBy> {
+  loadBy: T_LoadBy;
+  progress: Promise<any>;
+}
+
+/**
+ * DyFM_DataHandlerDataPostProcess
+ */
+export type DyFM_DataHandlerDataLoadPostProcess<T_LoadBy> = (data: any, loadedBy: T_LoadBy) => Promise<any> | any;
+
+/**
+ * DynamoDataHandler is used to create application wide data handling
+ * used to create subscribeAble data handler
+ *
+ * this implements data reload function that uses predefined apiService,
+ * using previous or given id,
+ * prevents multiple load calls and triggers data change subscriptions when done
+ *
+ * load post processes can be implemented to ensure special conditions
+ *
+ * @example
+ * personalInformationDH = new DynamoDataHandler<PersonalInformation>({
+ *   apiService: this.accountApiService,
+ *   getDataFunctionName: 'getPersonalInformation',
+ * });
+ */
+export abstract class DyFM_DataHandler<
+  T extends DyFM_Metadata | DyFM_Metadata[],
+  T_Dependency extends DyFM_Metadata = any,
+  T_LoadBy = string
+> {
+  name: string;
+
+  /**
+   * BehaviorSubject that holds the current data value.
+   * This is the source of truth for data in DyFM.
+   */
+  protected readonly data_BS: BehaviorSubject<T>;
+
+  /**
+   * Observable that emits the current data value.
+   * Derived from the BehaviorSubject.
+   */
+  readonly data$: Observable<T>;
+
+  /**
+   * BehaviorSubject that indicates whether the data has been loaded.
+   * True when data is loaded, false otherwise.
+   */
+  protected readonly loaded_BS: BehaviorSubject<boolean>;
+
+  /**
+   * Observable that indicates whether the data has been loaded.
+   */
+  readonly loaded$: Observable<boolean>;
+
+  /**
+   * BehaviorSubject that tracks the current loading operation.
+   * Contains information about the ongoing data load operation or false if no load is in progress.
+   */
+  protected readonly loadInProgress_BS: BehaviorSubject<DyFM_DataHandlerDataLoadInProgress<T_LoadBy> | false>;
+
+  /**
+   * Observable that tracks the current loading operation.
+   */
+  readonly loadInProgress$: Observable<DyFM_DataHandlerDataLoadInProgress<T_LoadBy> | false>;
+
+  /**
+   * Gets the current data value.
+   * @returns The current data value
+   */
+  abstract get data(): T;
+
+  /**
+   * last loaded by will work properly only if you use the Dynamo form of "_id" for loading
+   */
+  lastLoadedBy: T_LoadBy; // for lists
+  defaultLoadBy: T_LoadBy; // for lists
+
+  /** this will handle the data loading from the api */
+  protected readonly get: (loadBy?: T_LoadBy) => Promise<any>;
+  /** this will handle the data setting to the data handler */
+  protected readonly set: (data: T) => Promise<T>;
+  /** this will handle the data patching to the data handler */
+  /* patch: (data: T) => Promise<T>; */
+
+  // TODO
+  /* directApiSetup: any; */
+
+  /**
+   * post processes will be called as pipes after data is loaded by get function,
+   * but before data is set to data handler by data_$.set (after get, before Signal triggers)
+   */
+  protected readonly getPostProcesses: DyFM_DataHandlerDataLoadPostProcess<T_LoadBy>[] = [];
+
+  noId?: boolean;
+
+  waitsOnLoad: {
+    promise: Promise<void>;
+    resolve: () => void;
+  }[] = [];
+
+  protected readonly dependentDataHandlers?: DyFM_DataHandler<any>[] = [];
+
+  debugLog?: boolean;
+
+  /**
+   * DynamoDataHandler
+   * @param apiService any service can be used as apiService
+   * as long as the function, you pass in getDataFunctionName exists,
+   * uses (or not uses an ID as input) and returns the data as Promise<Type>
+   * @param getDataFunctionName the function name on the apiService,
+   * that will be used as get api call
+   *
+   * @param successfulReloadCallBack you can create direct callback for successful reloads
+   * by passing it here
+   *
+   * @param getPostPreprocessLoad post processes can be implemented to ensure special conditions on data
+   *
+   * @param defaultValue you can set default value that will be used before any load
+   * @param noId this flag needs to be true, when using api function without id
+   *
+   * @example
+   * personalInformationDH = new DynamoDataHandler<PersonalInformation>({
+   *   apiService: this.accountApiService,
+   *   getDataFunctionName: 'getPersonalInformation',
+   * });
+   */
+  constructor(
+    set: DyFM_DataHandler_Settings<T, T_Dependency, T_LoadBy>,
+    /** is in construct? 
+     * so the dependent data handlers are not added here, but in the extended class */
+    skipDependencyConnections?: boolean
+  ) {
+    // TODO: + TRYTOGETTYPE(this.data);
+    if (!set.name) {
+      set.name = 'Unnamed DataHandler ' + (+new Date());
+
+      DyFM_Log.warn(
+        `DYNAMO DH.constructor (${this.name}) WARN: ` +
+        `\n  Name is not set!`,
+        '\n\n', new Error()
+      );
+    }
+
+    this.name = set.name; 
+    this.debugLog = set?.debugLog;
+
+    // Initialize BehaviorSubjects
+    this.data_BS = new BehaviorSubject<T>(set.defaultValue);
+    this.data$ = this.data_BS.asObservable();
+    
+    this.loaded_BS = new BehaviorSubject<boolean>(false);
+    this.loaded$ = this.loaded_BS.asObservable();
+    
+    this.loadInProgress_BS = new BehaviorSubject<DyFM_DataHandlerDataLoadInProgress<T_LoadBy> | false>(false);
+    this.loadInProgress$ = this.loadInProgress_BS.asObservable();
+
+    if (set.get) {
+      this.get = set.get;
+    }
+
+    if (set.set) {
+      this.set = set.set;
+    }
+
+    this.noId = !!set.noId;
+
+    if (set.defaultLoadBy) {
+      this.defaultLoadBy = set.defaultLoadBy;
+    }
+
+    if (!skipDependencyConnections) {
+      if (set.dependencyDataHandler) {
+        this.addDependencyDataHandler(set.dependencyDataHandler);
+      }
+  
+      if (set.dependentDataHandlers) {
+        this.addDependentDataHandlers(set.dependentDataHandlers, true);
+      }
+    }
+
+    if (set.getPostProcess) {
+      this.getPostProcesses.push(set.getPostProcess);
+    }
+  }
+
+  addDependencyDataHandler(dependencyDataHandler: DyFM_DataHandler<any>): void {
+    try {
+      if (!dependencyDataHandler) {
+        throw new Error(
+          `DYNAMO DH.addDependencyDataHandler (${this.name}) ERROR: ` +
+          `\n  Dependent DataHandler is null or undefined! (${this.name})`
+        );
+      }
+  
+      if (!(dependencyDataHandler instanceof DyFM_DataHandler)) {
+        throw new Error(
+          `DYNAMO DH.addDependencyDataHandler (${this.name}) ERROR: ` +
+          `\n  Dependent DataHandler is not instance of DyFM_DataHandler! (${this.name})`
+        );
+      }
+  
+      dependencyDataHandler.addDependentDataHandlers([ this ]);
+    } catch (error) {
+      console.error(
+        `DYNAMO DH.addDependencyDataHandler (${this.name}) ERROR: ` +
+        `\n  Failed to add dependency data handler! ("${this.name}": "${this.constructor.name}")`,
+        '\n\n', error,
+        '\n\n', new Error()
+      );
+    }
+  }
+
+  addDependentDataHandlers(
+    dependentDataHandlers: DyFM_DataHandler<any, any, any>[],
+    isInConstruct?: boolean
+  ): void {
+    dependentDataHandlers.forEach((dependent_DH: DyFM_DataHandler<any>): void => {
+      if (!dependent_DH) {
+        throw new Error(
+          `DYNAMO DH.addDependentDataHandlers (${this.name}) ERROR: ` +
+          `\n  Dependent DataHandler is null or undefined! (${this.name})`
+        );
+      }
+
+      if (!(dependent_DH instanceof DyFM_DataHandler)) {
+        throw new Error(
+          `DYNAMO DH.addDependentDataHandlers (${this.name}) ERROR: ` +
+          `\n  Dependent DataHandler is not instance of DyFM_DataHandler! (${this.name})`
+        );
+      }
+
+      if (dependent_DH.name === this.name) {
+        throw new Error(
+          `DYNAMO DH.addDependentDataHandlers (${this.name}) ERROR: ` +
+          `\n  Dependent DataHandler has the same name as the current DataHandler! (${this.name})`
+        );
+      }
+
+      if (!dependent_DH.data_BS) {
+        throw new Error(
+          `DYNAMO DH.addDependentDataHandlers (${this.name}) ERROR: ` +
+          `\n  Dependent DataHandler has not been set up yet! ` +
+          `(this: "${this.name}", dependent: "${dependent_DH.name}")` +
+          `\n    Try the opposite direction of dependency!\n\n`
+        );
+      }
+
+      if (!dependentDataHandlers.includes(dependent_DH)) {
+        dependentDataHandlers.push(dependent_DH);
+      }
+
+      if (this.debugLog) {
+        this.getPostProcesses.push(async (newData: T): Promise<T> => {
+          console.log(
+            `DYNAMO DH.addDependentDataHandlers (${this.name}) DEBUG:` +
+            `\nDataHandler triggering dependent dataHandler (${dependent_DH.name}) to reload... ` +
+            `\n(using id: ${newData && (newData as DyFM_Metadata)._id ? (newData as DyFM_Metadata)._id : ''})`
+          );
+
+          return newData;
+        });
+      }
+
+      this.getPostProcesses.push(
+        async (newData: T): Promise<T> => {
+          if (newData && (newData as DyFM_Metadata)._id && (newData as DyFM_Metadata)._id !== dependent_DH.lastLoadedBy) {
+            dependent_DH.reloadData((newData as DyFM_Metadata)._id);
+          } else if (!newData) {
+            dependent_DH.clear();
+          }
+
+          return newData;
+        }
+      );
+
+      if (!isInConstruct && this.data) {
+        dependent_DH.reloadData((this.data as DyFM_Metadata)._id);
+      }
+    });
+  }
+
+  /**
+   * reloads data on DynamoDataHandler using predefined apiservice,
+   * using previous or given id,
+   * prevents multiple load calls and triggers data change subscriptions when done
+   * @param loadBy previous or given id (or can be disabled trough setup by: { noId: true })
+   * @returns the data as Promise<T>, finishes when the call ends (throws error on fail)
+   */
+  async reloadData(loadBy?: T_LoadBy, opts?: { silentMissingId?: boolean }): Promise<T> {
+    try {
+      const loadInProgress = this.loadInProgress_BS.value;
+      const useLoadBy: T_LoadBy = loadBy ??
+        ((this.data as DyFM_Metadata)?._id as T_LoadBy) ??
+        this.lastLoadedBy ??
+        this.defaultLoadBy;
+
+      if (!useLoadBy && !this.noId) {
+        // BFR-MASTERPROMPTER-024: a getData not-loaded-yet útján (silentMissingId) a console.error
+        // kimarad — a boot-race ID-hiány nem caller-hiba; a throw változatlanul megy.
+        if (!opts?.silentMissingId) {
+          console.error(
+            `DynamoERROR (DH.reloadData): Missing ID! (${this.name})`,
+            this.data,
+            '\n\n', new Error()
+          );
+        }
+
+        throw new Error(`DynamoERROR (DH.reloadData): Missing ID! (${this.name})`);
+      }
+
+      if (loadInProgress && loadInProgress.loadBy === useLoadBy) {
+        if (this.debugLog) {
+          console.log(
+            `DYNAMO DH.reloadData (${this.name}) DEBUG:` +
+            `\n  DataHandler reloadData... (using id: ${useLoadBy})` +
+            `\n  DataHandler is already loading data...`
+          );
+        }
+
+        return this.data;
+      }
+
+      if (this.debugLog) {
+        console.log(
+          `DYNAMO DH.reloadData (${this.name}) DEBUG:` +
+          `\n  DataHandler reloadData... (using id: ${useLoadBy})`
+        );
+      }
+
+      const loadProgress = this.doReloadDataBy(useLoadBy);
+      this.loadInProgress_BS.next({ 
+        loadBy: useLoadBy,
+        progress: loadProgress
+      });
+      loadProgress.finally(() => {
+        this.loadInProgress_BS.next(false);
+      });
+
+      return await loadProgress;      
+    } catch (error) {
+      this.loadInProgress_BS.next(false);
+      this.loaded_BS.next(false);
+
+      if (!error?.error?.handled) {
+        console.error(
+          `DYNAMO DH.reloadData (${this.name}) ERROR: ` +
+          `\n  reloadData was UNSUCCESSFUL`,
+          '\n\n', error,
+          '\n\n', new Error()
+        );
+
+        if (error?.error?.flag?.includes('DYNAMO')) {
+          error.error.handled = true;
+        }
+      }
+
+      throw error;
+    }
+  }
+
+  async getData(): Promise<T> {
+    if (!this.data) {
+      const loadProgress = this.loadInProgress_BS.value;
+      if (loadProgress) {
+        return await loadProgress.progress;
+      } else {
+        // BFR-MASTERPROMPTER-024: not-loaded-yet út → silent missing-ID (a throw marad).
+        return await this.reloadData(undefined, { silentMissingId: true });
+      }
+    } else {
+      return this.data;
+    }
+  }
+
+  protected async doReloadDataBy(loadedBy: T_LoadBy): Promise<T> {
+    try {
+      this.lastLoadedBy = loadedBy;
+
+      return await this.processLoadResult(await this.get(loadedBy), loadedBy);
+    } catch (error) {
+      this.resolveWaitsOnLoad();
+      throw error;
+    }
+  }
+
+  /**
+   * A DataHandler adatának közvetlen frissítése egy már ismert value-val, szerver-round-trip NÉLKÜL
+   * (pl. login-response → user_DH.updateData). Alapból CSAK a saját data_BS-t frissíti.
+   *
+   * @param reloadDependents opt-in (BFR-MASTERPROMPTER-013): ha true, a `reloadData` post-process
+   *   dependent-reload-láncát is meghajtja — a függő DataHandler-ek (pl. token-balance) újratöltődnek
+   *   az új adat `_id`-jével. A `reloadData` (hard-nav boot) útján ez a lánc automatikus, de az
+   *   `updateData` (round-trip-mentes) útján eddig NEM futott → a friss SPA-login után a dependent-DH
+   *   adatok üresek maradtak hard-reload-ig. DEFAULT false (backward-safe): az `updateData` fő szándéka
+   *   ÉPP a szerver-hívás elkerülése, ezért a vak dependent-reload nem kívánt HTTP-flood-ot okozhatna.
+   */
+  async updateData(data: T, dontSendUpdate?: boolean, reloadDependents?: boolean): Promise<void> {
+    if (this.set && !dontSendUpdate) {
+      this.data_BS.next(await this.set(data));
+    } else {
+      this.data_BS.next(data);
+    }
+
+    if (reloadDependents) {
+      // ugyanaz a reload-vagy-clear logika, mint a reloadData post-process-e (dependent-lánc)
+      this.dependentDataHandlers?.forEach((dependent_DH: DyFM_DataHandler<any>): void => {
+        if (data && (data as DyFM_Metadata)._id && (data as DyFM_Metadata)._id !== dependent_DH.lastLoadedBy) {
+          dependent_DH.reloadData((data as DyFM_Metadata)._id);
+        } else if (!data) {
+          dependent_DH.clear();
+        }
+      });
+    }
+  }
+
+  clear(dontClearDependents?: boolean): void {
+    this.data_BS.next(undefined);
+    this.lastLoadedBy = undefined;
+    if (!dontClearDependents) {
+      this.dependentDataHandlers.forEach((ddh: DyFM_DataHandler<any>): void => {
+        ddh.clear();
+      });
+    }
+  }
+
+  protected async processLoadResult(result: any, loadedBy: T_LoadBy): Promise<T> {
+    if (this.debugLog) {
+      console.log(
+        `DYNAMO DH.processLoadResult (${this.name}) DEBUG:` +
+        `\n  DataHandler processLoadResult... (using id: ${loadedBy})` +
+        `\n  Result:`, result
+      );
+    }
+
+    for (const postProcess of this.getPostProcesses) {
+      if (this.debugLog) {
+        console.log(
+          `DYNAMO DH.processLoadResult (${this.name}) DEBUG:` +
+          `\n  Post process:`, postProcess
+        );
+      }
+      
+      result = await postProcess(result, loadedBy);
+
+      if (!result) {
+        DyFM_Log.warn(
+          `DYNAMO DH.processLoadResult (${this.name}) WARN: ` +
+          `\nPost process returned null or undefined!`,
+          '\n\n', new Error()
+        );
+      }
+    }
+    this.data_BS.next(result);
+    this.loaded_BS.next(true);
+    this.resolveWaitsOnLoad();
+    return result;
+  }
+
+  private resolveWaitsOnLoad(): void {
+    this.waitsOnLoad.forEach(({ promise, resolve }) => {
+      resolve();
+    });
+    this.waitsOnLoad = [];
+  }
+
+  /**
+   * waits for the first load to finish
+   * @returns a promise that resolves when the first load finishes after this "subscription"
+   */
+  waitForLoad(): Promise<void> {
+    let resolve: (value: void) => void;
+    const promise = new Promise<void>((r) => { resolve = r; });
+    this.waitsOnLoad.push({ promise, resolve });
+    return promise;
+  }
+}