@futdevpro/fsm-dynamo 1.16.33 → 1.16.35

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

@@ -1,274 +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);
-  }
-}
+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

@@ -1,6 +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';
+// 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';

package/src/_modules/game/_models/audio-mixer-config.interface.ts

@@ -42,4 +42,12 @@ export interface DyFM_AudioMixer_Config {
 
   /** Alapertelmezes a `defaults`-ban fel nem sorolt csatornakra (**sajat skala**). Default: a maximum 80%-a. */
   defaultChannelVolume?: number;
+
+  /**
+   * Szoljon-e a hang alapbol akkor is, ha a tab/ablak nem aktiv. **Default: `false`**
+   * (owner-direktiva — a hatter-hang opt-in, sosem opt-out).
+   *
+   * Csak nagyon indokolt esetben allitsd `true`-ra (pl. tisztan audio-jatek).
+   */
+  defaultPlayWhenUnfocused?: boolean;
 }

package/src/_modules/game/_models/audio-mixer-settings.interface.ts

@@ -25,4 +25,14 @@ export interface DyFM_AudioMixer_Settings {
 
   /** Globalis nemitas — ha true, minden effektiv hangero 0. */
   muted: boolean;
+
+  /**
+   * Szoljon-e a hang, ha a tab/ablak nem aktiv. **Default: `false`.**
+   *
+   * **OPCIONALIS** — szandekosan, hogy a mezo bevezetese ne legyen torо valtozas a round-1
+   * alakot mar hasznalo projekteknek. A letezese viszont azt biztositja, hogy a klasszikus
+   * oda-vissza konverzio (`toClassicSettings` -> `fromClassicSettings`) NE veszitse el a
+   * kapcsolot.
+   */
+  playWhenUnfocused?: boolean;
 }

package/src/_modules/game/_models/audio-mixer-state.interface.ts

@@ -20,4 +20,17 @@ export interface DyFM_AudioMixer_State {
 
   /** Globalis nemitas — ha `true`, minden effektiv hangero 0. */
   muted: boolean;
+
+  /**
+   * Szoljon-e a hang akkor is, ha a **tab / ablak NEM aktiv** (hattervben van).
+   *
+   * **Alapertelmezes: `false`** — owner-direktiva. Egy hattervbe tett jatek alapbol NE szoljon
+   * bele a felhasznalo mas munkajaba; aki ezt akarja, az kapcsolja be. Ez a mezo CSAK a
+   * szandekot hordozza — a tenyleges szuneteltetest a lejatszo-reteg vegzi (bongeszo-fuggo
+   * `visibilitychange` / `blur`), mert a modell-reteg szandekosan DOM-fuggetlen.
+   *
+   * **Migracio:** a mezo nelkuli (regi) mentesek a `merge()`-ben a config alapertelmezeset
+   * kapjak, tehat egy regi save betoltese nem kapcsolja be veletlenul a hatter-hangot.
+   */
+  playWhenUnfocused: boolean;
 }