@futdevpro/fsm-dynamo 1.20.92 → 1.20.93

package/build-esm/_modules/data-handler/_models/data-search-handler.control-model.js

@@ -0,0 +1,334 @@
+import { debounceTime, Subject } from 'rxjs';
+import { DyFM_DataListHandler } from './data-list-handler.control-model';
+import { DyFM_Object } from '../../../_collections/utils/object.util';
+/**
+ * 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_ControlModel<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_ControlModel extends DyFM_DataListHandler {
+    /**
+     * Subject for handling fresh search queries with debouncing.
+     * Used internally to manage query updates.
+     */
+    _freshQuery_S = new Subject();
+    /**
+     * Cache of search results for different pages.
+     * Helps optimize performance by storing previously loaded results.
+     */
+    cache = [];
+    /**
+     * 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.
+     */
+    cacheSize = 5;
+    /**
+     * Default number of items per page.
+     * Used when no pageSize is specified in the query.
+     */
+    defaultPageSize = 10;
+    /**
+     * Default search query to use when no query is provided.
+     * Can include default filters, sorting, and pagination settings.
+     */
+    get defaultQuery() {
+        return DyFM_Object.clone(this._defaultQuery);
+    }
+    _defaultQuery;
+    /**
+     * Total number of items available in the search results.
+     * Updated after each successful search.
+     */
+    totalItems;
+    /**
+     * Debounce time in milliseconds for query updates.
+     * Helps prevent too frequent API calls when query changes rapidly.
+     */
+    queryUpdateDebounceTime = 500;
+    /**
+     * Whether to perform initial search when handler is created.
+     * If true, will use defaultQuery for initial search.
+     */
+    /** @deprecated Use isSearchOnInitEnabled; searchOnInit remains the serialized compatibility key. */
+    searchOnInit = true;
+    /**
+     * Creates a new instance of DyFM_DataSearchHandler_ControlModel.
+     *
+     * @param set - Configuration settings for the search handler
+     */
+    constructor(set) {
+        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, loadedBy) => {
+            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) => {
+            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) {
+        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
+     */
+    addDependentDataHandlers(dependentDataHandlers) {
+        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) {
+        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) {
+        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) {
+        const query = this.lastLoadedBy ?? this.defaultQuery;
+        if (query) {
+            keys.forEach((key) => {
+                delete query.filterBy[key];
+            });
+            this.reloadData(query);
+        }
+    }
+    clearFilters() {
+        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) {
+        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) {
+        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) {
+        const query = this.lastLoadedBy ?? this.defaultQuery;
+        if (query) {
+            query.sortBy = query.sortBy.filter((sort) => !keys.includes(sort.key));
+            this.reloadData(query);
+        }
+    }
+    clearSorts() {
+        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, pageSize) {
+        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) {
+        const query = this.lastLoadedBy ?? this.defaultQuery;
+        if (query) {
+            query.pageSize = pageSize;
+            this.reloadData(query);
+        }
+    }
+    resetPage() {
+        const query = this.lastLoadedBy ?? this.defaultQuery;
+        if (query) {
+            query.page = 0;
+            query.pageSize = this.defaultPageSize;
+            this.reloadData(query);
+        }
+    }
+    resetQuery() {
+        const query = this.defaultQuery;
+        if (query) {
+            this.reloadData(query);
+        }
+        else {
+            query.filterBy = {};
+            query.sortBy = [];
+            query.page = 0;
+            query.pageSize = this.defaultPageSize;
+            this.reloadData(query);
+        }
+    }
+}
+Object.defineProperty(DyFM_DataSearchHandler_ControlModel, 'name', { value: 'DyFM_DataSearchHandler' });
+/** @deprecated Use DyFM_DataSearchHandler_ControlModel. Same constructor; no API removal. */
+export { DyFM_DataSearchHandler_ControlModel as DyFM_DataSearchHandler };
+Object.defineProperty(DyFM_DataSearchHandler_ControlModel.prototype, 'isSearchOnInitEnabled', {
+    configurable: true,
+    enumerable: false,
+    get: function () {
+        return this.searchOnInit;
+    },
+    set: function (isValue) {
+        this.searchOnInit = isValue;
+    },
+});

package/build-esm/_modules/data-handler/_models/list-collector-data-handler-settings.control-model.js

@@ -0,0 +1,12 @@
+import { DyFM_DataHandler_Settings } from './data-handler-settings.control-model';
+/** Settings for a list-collector data handler. */
+export class DyFM_ListCollectorDataHandlerSettings_ControlModel extends DyFM_DataHandler_Settings {
+    static {
+        Object.defineProperty(this, 'name', { value: 'DyFM_ListCollectorDataHandler_Settings' });
+    }
+    setItem;
+    deleteItem;
+    listKey;
+}
+/** @deprecated Use DyFM_ListCollectorDataHandlerSettings_ControlModel. Same constructor; no API removal. */
+export { DyFM_ListCollectorDataHandlerSettings_ControlModel as DyFM_ListCollectorDataHandler_Settings };

package/build-esm/_modules/data-handler/_models/list-collector-data-handler.control-model.js

@@ -0,0 +1,243 @@
+import { BehaviorSubject } from 'rxjs';
+import { DyFM_DataHandler } from './data-handler.control-model';
+import { DyFM_Error } from '../../../_models/control-models/error.control-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_ControlModel<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_ControlModel extends DyFM_DataHandler {
+    /** this is only for data list handlers,
+     * while creating arrow function for this, dont forget to use async n await! */
+    setItem;
+    /** this is only for data list handlers,
+     * while creating arrow function for this, dont forget to use async n await! */
+    deleteItem;
+    listKey;
+    /**
+     * BehaviorSubject that holds the current data list.
+     * Computed from the base data_BS BehaviorSubject, ensuring it always returns an array.
+     */
+    dataList_BS;
+    /**
+     * Observable that holds the current data list.
+     * Computed from the base data$ Observable, ensuring it always returns an array.
+     */
+    dataList$;
+    /**
+     * BehaviorSubject that holds the currently active item.
+     */
+    activeItem_BS;
+    /**
+     * Observable that holds the currently active item.
+     */
+    activeItem$;
+    /**
+     * Gets the current data value.
+     * @returns The current data value
+     */
+    get data() {
+        return this.data_BS.value;
+    }
+    /**
+     * Gets the current data list.
+     * Alias for data getter.
+     * @returns The current array of data items
+     */
+    get dataList() {
+        return this.dataList_BS.value;
+    }
+    /**
+     * Creates a new instance of DyFM_ListCollectorDataHandler_ControlModel.
+     *
+     * @param set - Configuration settings for the data handler
+     * @param skipDependencyConnections - Optional flag to skip dependency connections during construction
+     */
+    constructor(set, 
+    /** is in construct?
+     * so the dependent data handlers are not added here, but in the extended class */
+    skipDependencyConnections) {
+        super(set, skipDependencyConnections);
+        this.listKey = set.listKey;
+        // Initialize dataList BehaviorSubject and Observable
+        this.dataList_BS = new BehaviorSubject([]);
+        this.dataList$ = this.dataList_BS.asObservable();
+        // Initialize activeItem BehaviorSubject and Observable
+        this.activeItem_BS = new BehaviorSubject(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) => {
+            // 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);
+            }
+        }
+    }
+    clear(dontClearDependents) {
+        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, collectorId, dontSendUpdate) {
+        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, collectorId, dontSendUpdate) {
+        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, collectorId, dontSendUpdate) {
+        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) {
+        this.activeItem_BS.next(item);
+    }
+}
+Object.defineProperty(DyFM_ListCollectorDataHandler_ControlModel, 'name', { value: 'DyFM_ListCollectorDataHandler' });
+/** @deprecated Use DyFM_ListCollectorDataHandler_ControlModel. Same constructor; no API removal. */
+export { DyFM_ListCollectorDataHandler_ControlModel as DyFM_ListCollectorDataHandler };

package/build-esm/_modules/data-handler/index.js

@@ -0,0 +1,9 @@
+// MODELS
+export * from './_models/data-handler.control-model';
+export * from './_models/data-handler-settings.control-model';
+export * from './_models/data-list-handler-settings.control-model';
+export * from './_models/data-search-handler-settings.control-model';
+export * from './_models/list-collector-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';