@futdevpro/fsm-dynamo 1.14.11 → 1.14.12

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

@@ -0,0 +1,459 @@
+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 DataHandler (${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 DataHandler ERROR: ` +
+          `\n  Dependent DataHandler is null or undefined! (${this.name})`
+        );
+      }
+  
+      if (!(dependencyDataHandler instanceof DyFM_DataHandler)) {
+        throw new Error(
+          `DYNAMO DataHandler ERROR: ` +
+          `\n  Dependent DataHandler is not instance of DyFM_DataHandler! (${this.name})`
+        );
+      }
+  
+      dependencyDataHandler.addDependentDataHandlers([ this ]);
+    } catch (error) {
+      console.error(
+        `DYNAMO DataHandler 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 DataHandler ERROR: ` +
+          `\n  Dependent DataHandler is null or undefined! (${this.name})`
+        );
+      }
+
+      if (!(dependent_DH instanceof DyFM_DataHandler)) {
+        throw new Error(
+          `DYNAMO DataHandler ERROR: ` +
+          `\n  Dependent DataHandler is not instance of DyFM_DataHandler! (${this.name})`
+        );
+      }
+
+      if (dependent_DH.name === this.name) {
+        throw new Error(
+          `DYNAMO DataHandler ERROR: ` +
+          `\n  Dependent DataHandler has the same name as the current DataHandler! (${this.name})`
+        );
+      }
+
+      if (!dependent_DH.data_BS) {
+        throw new Error(
+          `DYNAMO DataHandler 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 DataHandler (${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): 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) {
+        console.error(
+          `DynamoERROR: Missing ID! (${this.name})`,
+          this.data,
+          '\n\n', new Error()
+        );
+
+        throw new Error(`DynamoERROR: Missing ID! (${this.name})`);
+      }
+
+      if (loadInProgress && loadInProgress.loadBy === useLoadBy) {
+        if (this.debugLog) {
+          console.log(
+            `DYNAMO DataHandler (${this.name}) DEBUG:` +
+            `\n  DataHandler reloadData... (using id: ${useLoadBy})` +
+            `\n  DataHandler is already loading data...`
+          );
+        }
+
+        return this.data;
+      }
+
+      if (this.debugLog) {
+        console.log(
+          `DYNAMO DataHandler (${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 DynamoDataHandler (${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 {
+        return await this.reloadData();
+      }
+    } 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;
+    }
+  }
+
+  async updateData(data: T, dontSendUpdate?: boolean): Promise<void> {
+    if (this.set && !dontSendUpdate) {
+      this.data_BS.next(await this.set(data));
+    } else {
+      this.data_BS.next(data);
+    }
+  }
+
+  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 DataHandler (${this.name}) DEBUG:` +
+        `\n  DataHandler processLoadResult... (using id: ${loadedBy})` +
+        `\n  Result:`, result
+      );
+    }
+
+    for (const postProcess of this.getPostProcesses) {
+      if (this.debugLog) {
+        console.log(
+          `DYNAMO DataHandler (${this.name}) DEBUG:` +
+          `\n  Post process:`, postProcess
+        );
+      }
+      
+      result = await postProcess(result, loadedBy);
+
+      if (!result) {
+        DyFM_Log.warn(
+          `DYNAMO DataHandler (${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;
+  }
+}

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

@@ -0,0 +1,245 @@
+import { BehaviorSubject, Observable } from 'rxjs';
+
+import { DyFM_DataListHandler_Settings } from './data-handler-settings.control-model';
+
+import { DyFM_DataHandler } from './data-handler.control-model';
+import { DyFM_Metadata } from '../../../_models/data-models/metadata.data-model';
+import { DyFM_Error } from '../../../_models/control-models/error.control-model';
+
+/**
+ * A specialized data handler for managing arrays of data items.
+ * Extends DyFM_DataHandler to provide additional functionality for handling lists of data.
+ * 
+ * @template T_DataList - The type of the data list (must be an array of T_DataItem)
+ * @template T_DependencyData - The type of dependency data (defaults to any)
+ * @template T_DataLoadBy - The type used to identify how data should be loaded (defaults to string)
+ * @template T_DataItem - The type of individual items in the list (must extend DyFM_Metadata)
+ * 
+ * @example
+ * ```typescript
+ * // Create a data list handler for user messages
+ * const messagesHandler = new DyFM_DataListHandler<UserMessage[]>({
+ *   get: async (userId: string): Promise<UserMessage[]> => {
+ *     return await userApiService.getUserMessages(userId, 0, 100);
+ *   }
+ * });
+ * 
+ * // Access the data list
+ * const messages = messagesHandler.dataList;
+ * 
+ * // Add a new message
+ * messagesHandler.addItem(newMessage);
+ * 
+ * // Update an existing message
+ * messagesHandler.updateItem(updatedMessage);
+ * 
+ * // Subscribe to changes
+ * messagesHandler.dataList$.subscribe(messages => {
+ *   console.log('Messages updated:', messages);
+ * });
+ * ```
+ */
+export class DyFM_DataListHandler<
+  T_DataItem extends DyFM_Metadata,
+  T_DependencyData extends DyFM_Metadata = any,
+  T_DataLoadBy = string,
+  T_UpdateItemBy = string,
+> extends DyFM_DataHandler<T_DataItem[], T_DependencyData, T_DataLoadBy> {
+  
+  protected readonly setItem: (item: T_DataItem, updateBy?: T_UpdateItemBy) => Promise<T_DataItem>;
+  protected readonly deleteItem: (id: string, updateBy?: T_UpdateItemBy) => Promise<void>;
+
+  /**
+   * BehaviorSubject that holds the current data list.
+   * Computed from the base data_BS BehaviorSubject, ensuring it always returns an array.
+   */
+  protected readonly dataList_BS: BehaviorSubject<T_DataItem[]>;
+
+  /**
+   * Observable that holds the current data list.
+   * Computed from the base data$ Observable, ensuring it always returns an array.
+   */
+  readonly dataList$: Observable<T_DataItem[]>;
+
+  /**
+   * BehaviorSubject that holds the currently active item.
+   */
+  readonly activeItem_BS: BehaviorSubject<T_DataItem>;
+
+  /**
+   * Observable that holds the currently active item.
+   */
+  readonly activeItem$: Observable<T_DataItem>;
+
+  /**
+   * Gets the current data list.
+   * @returns The current array of data items
+   */
+  override get data(): T_DataItem[] {
+    return this.dataList_BS.value;
+  }
+
+  /**
+   * Gets the current data list.
+   * Alias for data getter.
+   * @returns The current array of data items
+   */
+  get dataList(): T_DataItem[] {
+    return this.dataList_BS.value;
+  }
+
+  /**
+   * Creates a new instance of DyFM_DataListHandler.
+   * 
+   * @param set - Configuration settings for the data handler
+   * @param skipDependencyConnections - Optional flag to skip dependency connections during construction
+   */
+  constructor(
+    set: DyFM_DataListHandler_Settings<T_DataItem, T_DependencyData, T_DataLoadBy, T_UpdateItemBy>,
+    /** is in construct? 
+     * so the dependent data handlers are not added here, but in the extended class */
+    skipDependencyConnections?: boolean,
+  ) {
+    super(set, skipDependencyConnections);
+    
+    // Initialize dataList BehaviorSubject and Observable
+    this.dataList_BS = new BehaviorSubject<T_DataItem[]>([]);
+    this.dataList$ = this.dataList_BS.asObservable();
+    
+    // Initialize activeItem BehaviorSubject and Observable
+    this.activeItem_BS = new BehaviorSubject<T_DataItem>(null);
+    this.activeItem$ = this.activeItem_BS.asObservable();
+
+    // Subscribe to data changes to update dataList
+    this.data$.subscribe(data => {
+      const dataList = Array.isArray(data) ? data : [];
+      this.dataList_BS.next(dataList);
+    });
+    
+    if (set.setItem) {
+      this.setItem = set.setItem;
+    }
+
+    if (set.deleteItem) {
+      this.deleteItem = set.deleteItem;
+    }
+
+    this.getPostProcesses.push((data: T_DataItem[]) => {
+      // check if data is an array
+      if (!Array.isArray(data) ) {
+        console.error(
+          `DYNAMO DataListHandler (${this.name}) ERROR: ` +
+          `\nData is not an array!:` +
+          '\n\n', data
+        );
+        throw new Error(`Data is not an array! (${this.name})`);
+      }
+
+      return data;
+    });
+
+    if (!skipDependencyConnections) {
+      if (set.dependencyDataHandler) {
+        this.addDependencyDataHandler(set.dependencyDataHandler);
+      }
+  
+      if (set.dependentDataHandlers) {
+        this.addDependentDataHandlers(set.dependentDataHandlers, true);
+      }
+    }
+  }
+
+  override async reloadData(loadBy?: T_DataLoadBy): Promise<T_DataItem[]> {
+    const setActiveItem = !this.activeItem_BS.value || this.activeItem_BS.value?._id !== loadBy;
+    const dataList = await super.reloadData(loadBy);
+    if (setActiveItem && dataList.length > 0) {
+      this.setActiveItem(dataList[0]);
+    }
+    return dataList;
+  }
+
+  override clear(dontClearDependents?: boolean): void {
+    super.clear(dontClearDependents);
+    this.activeItem_BS.next(null);
+  }
+
+  /**
+   * Adds a new item to the data list.
+   * 
+   * @param item - The item to add to the list
+   * @param updateBy - Optional parameter for update tracking
+   * @param dontSendUpdate - Optional flag to prevent sending update notification
+   */
+  async addItem(item: T_DataItem, updateBy?: T_UpdateItemBy, dontSendUpdate?: boolean): Promise<void> {
+    const currentData = this.data;
+    currentData.push(item);
+    if (this.setItem && !dontSendUpdate) {
+      await this.setItem(item, updateBy);
+      // dont send update because we already sent it to the setItem function
+      await this.updateData(this.dataList_BS.value, true);
+    } else {
+      await this.updateData(this.dataList_BS.value, dontSendUpdate);
+    }
+    this.activeItem_BS.next(item);
+  }
+
+  /**
+   * Removes an item from the data list.
+   * The item is identified by its _id property.
+   * 
+   * @param id - The id of the item to remove from the list
+   * @param updateBy - Optional parameter for update tracking
+   * @param dontSendUpdate - Optional flag to prevent sending update notification
+   */
+  async removeItem(id: string, updateBy?: T_UpdateItemBy, dontSendUpdate?: boolean): Promise<void> {
+    const currentData = this.data;
+    const index = currentData.findIndex(i => i._id === id);
+    if (index !== -1) {
+      currentData.splice(index, 1);
+      if (this.deleteItem) {
+        await this.deleteItem(id, updateBy);
+        await this.updateData(this.dataList_BS.value, true);
+      } else {
+        await this.updateData(this.dataList_BS.value, dontSendUpdate);
+      }
+    }
+    if (this.activeItem_BS.value?._id === id) {
+      this.activeItem_BS.next(null);
+    }
+  }
+
+  /**
+   * Updates an existing item in the data list.
+   * The item is identified by its _id property.
+   * 
+   * @param item - The updated item
+   * @param updateBy - Optional parameter for update tracking
+   * @param dontSendUpdate - Optional flag to prevent sending update notification
+   * @throws Error if the item is not found in the list
+   */
+  async updateItem(item: T_DataItem, updateBy?: T_UpdateItemBy, dontSendUpdate?: boolean): Promise<void> {
+    const currentData = this.data;
+    const index = currentData.findIndex(i => i._id === item._id);
+    if (index !== -1) {
+      currentData[index] = item;
+      if (this.setItem) {
+        await this.setItem(item, updateBy);
+        await this.updateData(this.dataList_BS.value, true);
+      } else {
+        await this.updateData(this.dataList_BS.value, dontSendUpdate);
+      }
+    } else {
+      throw new DyFM_Error({
+        error: new Error(`Item not found! (${this.name})`),
+        errorCode: 'DyFM-DLH-UI1',
+        additionalContent: {
+          item: item,
+        },
+      });
+    }
+  }
+
+  setActiveItem(item: T_DataItem): void {
+    this.activeItem_BS.next(item);
+  }
+}