@futdevpro/fsm-dynamo 1.14.10 → 1.14.12

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

@@ -0,0 +1,390 @@
+import { debounceTime, Subject } from 'rxjs';
+
+import { DyFM_DataSearchHandler_Settings } from './data-handler-settings.control-model';
+
+import { DyFM_DataListHandler } from './data-list-handler.control-model';
+import { DyFM_Object } from '../../../_collections/utils/object.util';
+import { DyFM_Metadata } from '../../../_models/data-models/metadata.data-model';
+import { DyFM_SearchQuery } from '../../../_models/interfaces/search-query.interface';
+import { DyFM_SearchResult } from '../../../_models/interfaces/search-result.interface';
+import { DyFM_DSFilter } from '../../../_models/types/ds-filter.type';
+import { DyFM_DSSort, DyFM_DSPropertySort } from '../../../_models/types/ds-sort.type';
+
+interface SearchCache<T> {
+  page: number;
+  loadPageSize: number;
+  data: T[];
+}
+
+/**
+ * A specialized data handler for managing searchable data with pagination and caching.
+ * Extends DyFM_DataListHandler to provide additional functionality for handling search results.
+ * 
+ * @template T_Data - The type of data items in the search results
+ * @template T_DataLoadBy - The type of search query (must extend DyFM_SearchQuery)
+ * @template T_Result - The type of search result (must extend DyFM_SearchResult)
+ * @template T_DependencyData - The type of dependency data (defaults to any)
+ * 
+ * @example
+ * ```typescript
+ * // Create a search handler for flow runs
+ * const flowRunsHandler = new DyFM_DataSearchHandler<FlowRun_Preview>({
+ *   name: 'myRuns',
+ *   get: async (query?: DyFM_SearchQuery<FlowRun>): Promise<DyFM_SearchResult<FlowRun_Preview>> => {
+ *     return await flowRunService.searchFlowRuns(query);
+ *   },
+ *   defaultQuery: {
+ *     filterBy: { userId: currentUserId },
+ *     pageSize: 20
+ *   },
+ *   queryUpdateDebounceTime: 500
+ * });
+ * 
+ * // Update search query
+ * flowRunsHandler.updateQuery({
+ *   page: 0,
+ *   pageSize: 10,
+ *   filterBy: { status: 'completed' }
+ * });
+ * 
+ * // Access search results
+ * const runs = flowRunsHandler.dataList;
+ * 
+ * // Get total items count
+ * const totalItems = flowRunsHandler.totalItems;
+ * ```
+ */
+export class DyFM_DataSearchHandler<
+  T_Data,
+  T_DataLoadBy extends DyFM_SearchQuery<any> = DyFM_SearchQuery<T_Data>,
+  T_Result extends DyFM_SearchResult<any> = DyFM_SearchResult<T_Data>,
+  T_DependencyData extends DyFM_Metadata = any,
+> extends DyFM_DataListHandler<T_Data, T_DependencyData, T_DataLoadBy> {
+
+  /**
+   * Subject for handling fresh search queries with debouncing.
+   * Used internally to manage query updates.
+   */
+  protected readonly _freshQuery_S = new Subject<T_DataLoadBy>();
+
+  /**
+   * Cache of search results for different pages.
+   * Helps optimize performance by storing previously loaded results.
+   */
+  protected cache: SearchCache<T_Data>[] = [];
+
+  /**
+   * Override of the get method to handle search queries.
+   * Must be implemented to fetch search results from the data source.
+   */
+  // this is redundant, because the base class has the get method and it uses Generic type
+  /* override get: (query?: T_DataLoadBy) => Promise<T_Result>; */
+
+  /**
+   * Maximum number of cached pages to keep in memory.
+   * Default is 5 pages.
+   */
+  protected cacheSize: number = 5;
+
+  /**
+   * Default number of items per page.
+   * Used when no pageSize is specified in the query.
+   */
+  protected defaultPageSize: number = 10;
+
+  /**
+   * Default search query to use when no query is provided.
+   * Can include default filters, sorting, and pagination settings.
+   */
+  protected get defaultQuery(): T_DataLoadBy {
+    return DyFM_Object.clone(this._defaultQuery);
+  }
+
+  protected _defaultQuery?: T_DataLoadBy;
+
+  /**
+   * Total number of items available in the search results.
+   * Updated after each successful search.
+   */
+  protected totalItems: number;
+
+  /**
+   * Debounce time in milliseconds for query updates.
+   * Helps prevent too frequent API calls when query changes rapidly.
+   */
+  protected queryUpdateDebounceTime: number = 500;
+
+  /**
+   * Whether to perform initial search when handler is created.
+   * If true, will use defaultQuery for initial search.
+   */
+  protected searchOnInit: boolean = true;
+
+  /**
+   * Creates a new instance of DyFM_DataSearchHandler.
+   * 
+   * @param set - Configuration settings for the search handler
+   */
+  constructor(
+    set: DyFM_DataSearchHandler_Settings<T_Data, T_DataLoadBy, T_DependencyData>
+  ) {
+    super({
+      ...set,
+      noId: true,
+    });
+
+    if (set.queryUpdateDebounceTime) {
+      this.queryUpdateDebounceTime = set.queryUpdateDebounceTime;
+    }
+
+    if (set.defaultQuery) {
+      this._defaultQuery = set.defaultQuery;
+    }
+
+    // 3
+    // Add post-processing for search results
+    this.getPostProcesses.unshift(
+      (searchResult: T_Result, loadedBy: T_DataLoadBy): T_Data[] => {
+        console.warn('WTF DyFM_Search_DataHandler getPostProcess', searchResult, this.lastLoadedBy);
+
+        this.cache = this.cache.filter((c) => c.loadPageSize !== this.lastLoadedBy?.pageSize);
+
+        if (this.cache.length >= this.cacheSize) {
+          this.cache.shift();
+        }
+
+        this.cache.push({
+          page: this.lastLoadedBy?.page,
+          loadPageSize: this.lastLoadedBy?.pageSize,
+          data: searchResult.results,
+        });
+
+        this.totalItems = searchResult.totalItems;
+
+        return searchResult.results;
+      }
+    );
+
+    // 2
+    // Set up query update handling with debouncing
+    this._freshQuery_S.pipe(
+      debounceTime(this.queryUpdateDebounceTime),        
+    ).subscribe((query: T_DataLoadBy) => {
+      console.warn('asd', query, this.lastLoadedBy);
+
+      if (!query) {
+        if (!this._defaultQuery) {
+          this.reloadData();
+          return;
+        }
+
+        query = this.defaultQuery;
+      }
+
+      if (!query.page) {
+        query.page = 0;
+      }
+
+      if (!query.pageSize) {
+        query.pageSize = this.defaultPageSize;
+      }
+
+      if (this._defaultQuery?.filterBy) {
+        if (!query.filterBy) {
+          query.filterBy = {};
+        }
+
+        for (const key in this._defaultQuery.filterBy) {
+          if (!query.filterBy[key] && query.filterBy[key] !== null) {
+            query.filterBy[key] = this._defaultQuery.filterBy[key];
+          }
+        }
+      }
+
+      if (this._defaultQuery?.sortBy) {
+        if (!query.sortBy) {
+          query.sortBy = [];
+        }
+
+        if (!query.sortBy.length) {
+          query.sortBy = DyFM_Object.clone(this._defaultQuery.sortBy);
+        }
+      }
+
+      this.reloadData(query);
+    });
+
+    if (this.searchOnInit) {
+      this._freshQuery_S.next(this.defaultQuery);
+    }
+  }
+
+  // 1
+  /**
+   * Updates the search query and triggers a new search.
+   * The search will be debounced according to queryUpdateDebounceTime.
+   * 
+   * @param query - The new search query to use
+   */
+  updateQuery(query: T_DataLoadBy): void {
+    this._freshQuery_S.next(query);
+  }
+
+  /**
+   * Override to prevent adding dependent data handlers.
+   * Search handlers cannot have dependencies.
+   * 
+   * @throws Error - Always throws as search handlers cannot have dependencies
+   */
+  override addDependentDataHandlers(dependentDataHandlers: any[]): void {
+    throw new Error('Cannot add dependent data handlers to a search data handler');
+  }
+
+  /**
+   * Filters the current search query
+   * 
+   * @param filterBy - The filter to apply to the current search query 
+   */
+  filter(filterBy: DyFM_DSFilter<T_Data>): void {
+    const query = this.lastLoadedBy ?? this.defaultQuery;
+    if (query) {
+      query.filterBy = filterBy;
+      this.reloadData(query);
+    }
+  }
+
+  /**
+   * Adds a filter to the current search query
+   * 
+   * @param filterBy - The filter to add to the current search query
+   */
+  addFiler(filterBy: DyFM_DSFilter<T_Data>): void {
+    const query = this.lastLoadedBy ?? this.defaultQuery;
+    if (query) {
+      Object.assign(query.filterBy, filterBy);
+      this.reloadData(query);
+    }
+  }
+
+  /**
+   * Removes a filter from the current search query
+   * 
+   * @param keys - The keys of the filter to remove from the current search query
+   */
+  removeFilter(keys: (keyof T_Data)[]): void {
+    const query = this.lastLoadedBy ?? this.defaultQuery;
+    if (query) {
+      keys.forEach((key) => {
+        delete query.filterBy[key];
+      });
+      
+      this.reloadData(query);
+    }
+  }
+
+  clearFilters(): void {
+    const query = this.lastLoadedBy ?? this.defaultQuery;
+    if (query) {
+      query.filterBy = {};
+      this.reloadData(query);
+    }
+  }
+
+  /**
+   * Sorts the current search query
+   * 
+   * @param sortBy - The sort to apply to the current search query
+   */
+  sort(sortBy: DyFM_DSSort[]): void {
+    const query = this.lastLoadedBy ?? this.defaultQuery;
+    if (query) {
+      query.sortBy = sortBy;
+      this.reloadData(query);
+    }
+  }
+
+  /**
+   * Adds a sort to the current search query
+   * 
+   * @param sortBy - The sort to add to the current search query
+   */
+  addSort(sortBy: DyFM_DSSort[]): void {
+    const query = this.lastLoadedBy ?? this.defaultQuery;
+    if (query) {
+      query.sortBy.push(...sortBy);
+      this.reloadData(query);
+    }
+  }
+
+  /**
+   * Removes a sort from the current search query
+   * 
+   * @param keys - The keys of the sort to remove from the current search query
+   */
+  removeSort(keys: string[]): void {
+    const query = this.lastLoadedBy ?? this.defaultQuery;
+    if (query) {
+      query.sortBy = query.sortBy.filter((sort) => !keys.includes((sort as DyFM_DSPropertySort).key));
+      this.reloadData(query);
+    }
+  }
+
+  clearSorts(): void {
+    const query = this.lastLoadedBy ?? this.defaultQuery;
+    if (query) {
+      query.sortBy = [];
+      this.reloadData(query);
+    }
+  }
+
+  /**
+   * Sets the page of the current search query
+   * 
+   * @param page - The page to set to the current search query
+   */
+  page(page: number, pageSize?: number): void {
+    const query = this.lastLoadedBy ?? this.defaultQuery;
+    if (query) {
+      query.page = page;
+      if (pageSize) {
+        query.pageSize = pageSize;
+      }
+      this.reloadData(query);
+    }
+  }
+
+  /**
+   * Sets the page size of the current search query
+   * 
+   * @param pageSize - The page size to set to the current search query
+   */
+  pageSize(pageSize: number): void {
+    const query = this.lastLoadedBy ?? this.defaultQuery;
+    if (query) {
+      query.pageSize = pageSize;
+      this.reloadData(query);
+    }
+  }
+
+  resetPage(): void {
+    const query = this.lastLoadedBy ?? this.defaultQuery;
+    if (query) {
+      query.page = 0;
+      query.pageSize = this.defaultPageSize;
+      this.reloadData(query);
+    }
+  }
+
+  resetQuery(): void {
+    const query = this.defaultQuery;
+    if (query) {
+      this.reloadData(query);
+    } else {
+      query.filterBy = {};
+      query.sortBy = [];
+      query.page = 0;
+      query.pageSize = this.defaultPageSize;
+      this.reloadData(query);
+    }
+  }
+}

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

@@ -0,0 +1,274 @@
+import { BehaviorSubject, Observable } from 'rxjs';
+
+import { DyFM_ListCollectorDataHandler_Settings } from './data-handler-settings.control-model';
+
+import { DyFM_DataHandler } from './data-handler.control-model';
+import { DyFM_Error } from '../../../_models/control-models/error.control-model';
+import { DyFM_Metadata } from '../../../_models/data-models/metadata.data-model';
+
+/**
+ * A specialized data handler for managing list collections within a parent data object.
+ * Extends DyFM_DataHandler to provide functionality for handling lists within a collector object.
+ * 
+ * @template T_ListCollectorData - The type of the parent collector data object
+ * @template T_DataItem - The type of individual items in the list (must extend DyFM_Metadata)
+ * @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)
+ * 
+ * @example
+ * ```typescript
+ * // Create a list collector handler for user's projects
+ * const userProjectsHandler = new DyFM_ListCollectorDataHandler<User, Project>({
+ *   listKey: 'projects',
+ *   get: async (userId: string): Promise<User> => {
+ *     return await userService.getUserWithProjects(userId);
+ *   }
+ * });
+ * 
+ * // Access the data list
+ * const projects = userProjectsHandler.dataList;
+ * 
+ * // Add a new project
+ * userProjectsHandler.addItem(newProject);
+ * 
+ * // Update an existing project
+ * userProjectsHandler.updateItem(updatedProject);
+ * 
+ * // Subscribe to changes
+ * userProjectsHandler.dataList$.subscribe(projects => {
+ *   console.log('Projects updated:', projects);
+ * });
+ * ```
+ */
+export class DyFM_ListCollectorDataHandler<
+  T_ListCollectorData extends DyFM_Metadata,
+  T_DataItem extends DyFM_Metadata,
+  T_DependencyData extends DyFM_Metadata = any,
+  T_DataLoadBy = string,
+> extends DyFM_DataHandler<T_ListCollectorData, T_DependencyData, T_DataLoadBy> {
+
+  /** this is only for data list handlers, 
+   * while creating arrow function for this, dont forget to use async n await! */
+  protected readonly setItem?: (item: T_DataItem, collectorId?: string) => Promise<T_DataItem>;
+  /** this is only for data list handlers, 
+   * while creating arrow function for this, dont forget to use async n await! */
+  protected readonly deleteItem?: (id: string, collectorId?: string) => Promise<void>;
+
+  protected readonly listKey: string;
+
+  /**
+   * 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 value.
+   * @returns The current data value
+   */
+  override get data(): T_ListCollectorData {
+    return this.data_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_ListCollectorDataHandler.
+   * 
+   * @param set - Configuration settings for the data handler
+   * @param skipDependencyConnections - Optional flag to skip dependency connections during construction
+   */
+  constructor(
+    set: DyFM_ListCollectorDataHandler_Settings<T_ListCollectorData, T_DataItem, T_DependencyData, T_DataLoadBy>,
+    /** is in construct? 
+     * so the dependent data handlers are not added here, but in the extended class */
+    skipDependencyConnections?: boolean,
+  ) {
+    super(set, skipDependencyConnections);
+
+    this.listKey = set.listKey;
+    
+    // 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?.[this.listKey]) ? data[this.listKey] : [];
+      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 DynamoDataHandler (${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 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 collectorId - Optional collector ID for tracking
+   * @param dontSendUpdate - Optional flag to prevent sending update notification
+   */
+  async addItem(item: T_DataItem, collectorId?: string, dontSendUpdate?: boolean): Promise<void> {
+    if (!this.data) {
+      throw new DyFM_Error({
+        error: new Error(`Data not found! (${this.name})`),
+        errorCode: 'DyFM-LCDH-AI1',
+        additionalContent: {
+          listKey: this.listKey,
+        },
+      });
+    }
+    this.data[this.listKey] ??= [];
+    this.data[this.listKey].push(item);
+    if (this.setItem && !dontSendUpdate) {
+      await this.setItem(item, collectorId);
+      // dont send update because we already sent it to the setItem function
+      await this.updateData(this.data_BS.value, true);
+    } else {
+      await this.updateData(this.data_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 collectorId - Optional collector ID for tracking
+   * @param dontSendUpdate - Optional flag to prevent sending update notification
+   */
+  async removeItem(id: string, collectorId?: string, dontSendUpdate?: boolean): Promise<void> {
+    if (!this.data?.[this.listKey]?.length) {
+      throw new DyFM_Error({
+        error: new Error(`List not found! (${this.name})`),
+        errorCode: 'DyFM-LCDH-RI1',
+        additionalContent: {
+          listKey: this.listKey,
+        },
+      });
+    }
+    const index = this.data[this.listKey].findIndex(i => i._id === id);
+    if (index !== -1) {
+      this.data[this.listKey].splice(index, 1);
+      if (this.deleteItem) {
+        await this.deleteItem(id, collectorId);
+        await this.updateData(this.data_BS.value, true);
+      } else {
+        await this.updateData(this.data_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 collectorId - Optional collector ID for 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, collectorId?: string, dontSendUpdate?: boolean): Promise<void> {
+    if (!this.data?.[this.listKey]?.length) {
+      throw new DyFM_Error({
+        error: new Error(`List not found! (${this.name})`),
+        errorCode: 'DyFM-LCDH-UI0',
+        additionalContent: {
+          listKey: this.listKey,
+        },
+      });
+    }
+    // check if item is in the list
+    const index = this.data[this.listKey].findIndex(i => i._id === item._id);
+    if (index !== -1) {
+      // update the item
+      this.data[this.listKey][index] = item;
+      if (this.setItem) {
+        // send update to API
+        await this.setItem(item, collectorId);
+        await this.updateData(this.data_BS.value, true);
+      } else {
+        // send update to API
+        await this.updateData(this.data_BS.value, dontSendUpdate);
+      }
+    } else {
+      throw new DyFM_Error({
+        error: new Error(`Item not found! (${this.name})`),
+        errorCode: 'DyFM-LCDH-UI1',
+        additionalContent: {
+          item: item,
+        },
+      });
+    }
+  }
+
+  setActiveItem(item: T_DataItem): void {
+    this.activeItem_BS.next(item);
+  }
+}

package/src/_modules/data-handler/index.ts

@@ -0,0 +1,6 @@
+// MODELS
+export * from './_models/data-handler.control-model';
+export * from './_models/data-handler-settings.control-model';
+export * from './_models/data-list-handler.control-model';
+export * from './_models/data-search-handler.control-model';
+export * from './_models/list-collector-data-handler.control-model';