dyo-tools 0.2.0 → 0.3.2

package/src/core/DTMaster.ts

@@ -0,0 +1,318 @@
+import DYOToolsComponent from './DTComponent';
+import DYOToolsError from './DTError';
+import DYOToolsManager from './DTManager';
+import DYOToolsAction from './DTAction';
+import DYOToolsModule from './DTModule';
+import { DTMasterToObject } from '../types';
+
+export default class DYOToolsMaster extends DYOToolsComponent {
+  /**
+   * Defining component type to "master".
+   */
+  protected _componentType: string = 'master';
+
+  /**
+   * DTManager instances handled by the Master.
+   *
+   * The property is an object with _id value of the Manager instance as key, and Manager instance as value.
+   * @protected
+   */
+  protected _managers: Record<string, DYOToolsManager>;
+
+  /**
+   * DTAction instances handled by the Master.
+   *
+   * The property is an object with _id value of the Action instance as key, and Action instance as value.
+   * @protected
+   */
+  protected _actions: Record<string, DYOToolsAction>;
+
+  /**
+   * DTModule instance handled by the Master.
+   *
+   * The property is an object with _id value of the Module instance as key, and Module instance as value.
+   * @protected
+   */
+  protected _modules: Record<string, DYOToolsModule>;
+
+  /**
+   * Applying the parent constructor, and initializing all properties to empty object.
+   *
+   * @param key
+   */
+  constructor(key?: string) {
+    super(key);
+
+    this._managers = {};
+    this._actions = {};
+    this._modules = {};
+  }
+
+  /**
+   * Add a DTManager **item** into _managers property.
+   *
+   * The adding process has the following specifications :
+   * * If the added manager has the same _id than existing manager, an error occurred (depending on **errors** option).
+   * * If the added manager has the same _key than existing manager, an error occurred (depending on **errors** option).
+   * * The Master instance becomes the new context of the added item.
+   *
+   * @param manager DYOToolsManager instance to add.
+   */
+  addManager(manager: DYOToolsManager): void {
+    // Id conflict
+    if (Object.keys(this._managers).includes(manager.getId())) {
+      this.triggerError(new DYOToolsError(
+        'id_conflict',
+        'Manager with same id already exists in the Master instance',
+        this,
+        manager,
+      ));
+      return;
+    }
+
+    // Key conflict
+    if (Object.values(this._managers).find((m) => m.getKey() === manager.getKey())) {
+      this.triggerError(new DYOToolsError(
+        'key_conflict',
+        'Manager with same key already exists in the Master instance',
+        this,
+        manager,
+      ));
+      return;
+    }
+
+    this._managers[manager.getId()] = manager;
+    manager.setContext<DYOToolsMaster>(this);
+  }
+
+  /**
+   * Return one DTManager instance handled by the Master.
+   * It could be selected by _id or _key property of the Manager.
+   *
+   * @param idOrKey String id or key to select.
+   * @returns DYOToolsManager selected Manager instance, or undefined if not found.
+   */
+  getManager(idOrKey: string): DYOToolsManager | undefined {
+    let managerFound = this._managers[idOrKey];
+
+    if (!managerFound) {
+      managerFound = Object.values(this._managers).find((m) => m.getKey() === idOrKey);
+    }
+
+    return managerFound;
+  }
+
+  /**
+   * Remove a handled Manager from the Master instance.
+   *
+   * @param idOrKey String id or key to select.
+   */
+  removeManager(idOrKey: string): void {
+    const manager = this.getManager(idOrKey);
+
+    if (manager) {
+      delete this._managers[manager.getId()];
+    }
+  }
+
+  /**
+   * Add a DTAction **item** into _actions property.
+   *
+   * The adding process has the following specifications :
+   * * If the added action has the same _id than existing action, an error occurred (depending on **errors** option).
+   * * If the added action has the same _key than existing action, an error occurred (depending on **errors** option).
+   * * The Master instance becomes the new context of the added item.
+   *
+   * @param action DYOToolsAction instance to add.
+   */
+  addAction(action: DYOToolsAction): void {
+    // Id conflict
+    if (Object.keys(this._actions).includes(action.getId())) {
+      this.triggerError(new DYOToolsError(
+        'id_conflict',
+        'Action with same id already exists in the Master instance',
+        this,
+        action,
+      ));
+      return;
+    }
+
+    // Key conflict
+    if (Object.values(this._actions).find((m) => m.getKey() === action.getKey())) {
+      this.triggerError(new DYOToolsError(
+        'key_conflict',
+        'Action with same key already exists in the Master instance',
+        this,
+        action,
+      ));
+      return;
+    }
+
+    this._actions[action.getId()] = action;
+    action.setContext<DYOToolsMaster>(this);
+  }
+
+  /**
+   * Return one DTAction instance handled by the Master.
+   * It could be selected by _id or _key property of the Action.
+   *
+   * @param idOrKey String id or key to select.
+   * @returns DYOToolsAction selected Action instance, or undefined if not found.
+   */
+  getAction(idOrKey: string): DYOToolsAction | undefined {
+    let actionFound = this._actions[idOrKey];
+
+    if (!actionFound) {
+      actionFound = Object.values(this._actions).find((a) => a.getKey() === idOrKey);
+    }
+
+    return actionFound;
+  }
+
+  /**
+   * Remove a handled Action from the Master instance.
+   *
+   * @param idOrKey String id or key to select.
+   */
+  removeAction(idOrKey: string): void {
+    const action = this.getAction(idOrKey);
+
+    if (action) {
+      delete this._actions[action.getId()];
+    }
+  }
+
+  /**
+   * Trigger the **execute** process of an action handled by the Master instance.
+   * It could be selected by _id or _key property of the Action.
+   *
+   * @param idOrKey String id or key to select.
+   * @param payload Object payload for the action execution.
+   * @returns Promise action execution.
+   */
+  async executeAction(idOrKey: string, payload: unknown): Promise<void> {
+    const action = this.getAction(idOrKey);
+
+    if (action) {
+      await this.getAction(idOrKey).execute(payload);
+    }
+  }
+
+  /**
+   * Add a DTModule **item** into _modules property.
+   *
+   * The adding process has the following specifications :
+   * * If the added module has the same _id than existing module, an error occurred (depending on **errors** option).
+   * * If the added module has the same _key than existing module, an error occurred (depending on **errors** option).
+   * * The Master instance becomes the new context of the added item.
+   *
+   * @param module DYOToolsModule instance to add.
+   */
+  addModule(module: DYOToolsModule): void {
+    // Id conflict
+    if (Object.keys(this._modules).includes(module.getId())) {
+      this.triggerError(new DYOToolsError(
+        'id_conflict',
+        'Module with same id already exists in the Master instance',
+        this,
+        module,
+      ));
+      return;
+    }
+
+    // Key conflict
+    if (Object.values(this._modules).find((m) => m.getKey() === module.getKey())) {
+      this.triggerError(new DYOToolsError(
+        'key_conflict',
+        'Module with same key already exists in the Master instance',
+        this,
+        module,
+      ));
+      return;
+    }
+
+    this._modules[module.getId()] = module;
+    module.setContext<DYOToolsMaster>(this);
+  }
+
+  /**
+   * Return one DTModule instance handled by the Master.
+   * It could be selected by _id or _key property of the Module.
+   *
+   * @param idOrKey String id or key to select.
+   * @returns DYOToolsModule selected Module instance, or undefined if not found.
+   */
+  getModule(idOrKey: string): DYOToolsModule | undefined {
+    let moduleFound = this._modules[idOrKey];
+
+    if (!moduleFound) {
+      moduleFound = Object.values(this._modules).find((m) => m.getKey() === idOrKey);
+    }
+
+    return moduleFound;
+  }
+
+  /**
+   * Remove a handled Module from the Master instance.
+   *
+   * @param idOrKey String id or key to select.
+   */
+  removeModule(idOrKey: string): void {
+    const module = this.getModule(idOrKey);
+
+    if (module) {
+      delete this._modules[module.getId()];
+    }
+  }
+
+  /**
+   * Return String representation of the Master instance.
+   *
+   * @returns String representation of the Master.
+   */
+  toString(): string {
+    const managersLabel = `Managers: ${Object.keys(this._managers).length}`;
+    const actionsLabel = `Actions: ${Object.keys(this._actions).length}`;
+    const modulesLabel = `Modules: ${Object.keys(this._modules).length}`;
+
+    return `Component ${this._key} - Type: Master - ${managersLabel} - ${actionsLabel} - ${modulesLabel}`;
+  }
+
+  /**
+   * Return JSON Object representation of the Master instance.
+   *
+   * JSON Object returned has the following structure :
+   * * **id** : _id property of the Master.
+   * * **key** : _key property of the Master.
+   * * **type** : _componentType property of the Master.
+   * * **managers** : Array of JSON Object representation for each DTManager instance in _managers property of the Master.
+   * * **actions** : Array of JSON Object representation for each DTAction instance in _actions property of the Master.
+   * * **modules** : Array of JSON Object representation for each DTModule instance in _modules property of the Master.
+   *
+   * @returns JSON Object representation of the Master.
+   */
+  toObject(): DTMasterToObject {
+    const toObject: DTMasterToObject = {
+      id: this._id,
+      key: this._key,
+      type: this._componentType,
+      managers: [],
+      actions: [],
+      modules: [],
+    };
+
+    if (Object.keys(this._managers).length) {
+      toObject.managers = Object.values(this._managers).map((obj) => obj.toObject());
+    }
+
+    if (Object.keys(this._actions).length) {
+      toObject.actions = Object.values(this._actions).map((obj) => obj.toObject());
+    }
+
+    if (Object.keys(this._modules).length) {
+      toObject.modules = Object.values(this._modules).map((obj) => obj.toObject());
+    }
+
+    return toObject;
+  }
+}

package/src/core/DTModule.ts

@@ -0,0 +1,90 @@
+import DYOToolsComponent from './DTComponent';
+import { DTModuleToObject } from '../types';
+import DYOToolsMaster from './DTMaster';
+
+export default class DYOToolsModule extends DYOToolsComponent {
+  /**
+   * Defining component type to "module".
+   */
+  protected _componentType: string = 'module';
+
+  /**
+   * Defining if the module is enabled or not.
+   * @protected
+   */
+  protected _enabled: boolean;
+
+  /**
+   * Applying the parent constructor, and initializing _enabled property to true by default.
+   *
+   * @param key
+   */
+  constructor(key?: string) {
+    super(key);
+
+    this._enabled = true;
+  }
+
+  /**
+   * Returns Master component from context, or undefined.
+   */
+  getMaster(): DYOToolsMaster | undefined {
+    return this.getContext<DYOToolsMaster>('master');
+  }
+
+  /**
+   * Getter for the _enabled property.
+   */
+  isEnabled(): boolean {
+    return this._enabled;
+  }
+
+  /**
+   * Change _enabled property to true.
+   */
+  enable(): void {
+    this._enabled = true;
+  }
+
+  /**
+   * Change _enabled property to false.
+   */
+  disable(): void {
+    this._enabled = false;
+  }
+
+  /**
+   * Return String representation of the Module instance.
+   *
+   * @returns String representation of the Module.
+   */
+  toString(): string {
+    let extraLabel: string = '';
+
+    if (!this._enabled) {
+      extraLabel = ' - Disabled';
+    }
+
+    return `Component ${this._key} - Type: Module${extraLabel}`;
+  }
+
+  /**
+   * Return JSON Object representation of the Module instance.
+   *
+   * JSON Object returned has the following structure :
+   * * **id** : _id property of the Module.
+   * * **key** : _key property of the Module.
+   * * **type** : _componentType property of the Module.
+   * * **enabled** : _enabled property of the Module.
+   *
+   * @returns JSON Object representation of the Module.
+   */
+  toObject(): DTModuleToObject {
+    return {
+      id: this._id,
+      key: this._key,
+      type: this._componentType,
+      enabled: this._enabled,
+    };
+  }
+}

package/src/index.ts

@@ -1,9 +1,17 @@
 // All exports
+// CORE
 export { default as DTComponent } from './core/DTComponent';
 export { default as DTComponentWithMeta } from './core/DTComponentWithMeta';
 export { default as DTComponentPhysical } from './core/DTComponentPhysical';
 export { default as DTElement } from './core/DTElement';
 export { default as DTBunch } from './core/DTBunch';
 export { default as DTManager } from './core/DTManager';
-export { default as DTPlayer } from './core/DTPlayer';
+export { default as DTMaster } from './core/DTMaster';
 export { default as DTError } from './core/DTError';
+export { default as DTAction } from './core/DTAction';
+export { default as DTModule } from './core/DTModule';
+
+// LIBS
+// PLAYER
+export { default as DTPlayer } from './libs/player/DTPlayer.element';
+export { default as DTPlayerManager } from './libs/player/DTPlayer.manager';

package/src/libs/player/DTPlayer.element.ts

@@ -0,0 +1,9 @@
+import { DTAcceptedMetaData } from '../../types';
+import DYOToolsElement from '../../core/DTElement';
+
+export default class DYOToolsPlayer<IComponentMeta extends DTAcceptedMetaData = DTAcceptedMetaData> extends DYOToolsElement<IComponentMeta> {
+  /**
+   * Defining component domain to "player".
+   */
+  protected _domain = 'player';
+}

package/src/libs/player/DTPlayer.manager.ts

@@ -0,0 +1,84 @@
+import DYOToolsManager from '../../core/DTManager';
+import DYOToolsPlayer from './DTPlayer.element';
+import { DTBunchFilters, DTManagerOptions, DTPlayerManagerSimpleConfiguration } from '../../types';
+import { DTPlayer } from '../../index';
+
+export default class DYOToolsPlayerManager extends DYOToolsManager<DYOToolsPlayer> {
+  /**
+   * Defining component domain to "player".
+   */
+  protected _domain = 'player';
+
+  /**
+   * Applying the parent constructor. The key is **player** by default.
+   *
+   *
+   * The constructor uses a Configuration JSON Object, with following properties :
+   * * **players** : Default player configuration.
+   * If **players** is a number, it generates this number of DTPlayer instances and add it to the library.
+   * If **players** is an array of DTPlayer instances, it adds these to the library.
+   * * **errors** : Set **errors** option of the Manager.
+   *
+   * @param configuration DTPlayerManagerSimpleConfiguration Optional configuration to apply.
+   */
+  constructor(configuration?: DTPlayerManagerSimpleConfiguration) {
+    super('player');
+
+    // Simple Configuration
+    const finalConfig = configuration ?? {};
+    const finalOptions: DTManagerOptions = this._options;
+    if (finalConfig.players) {
+      if (typeof finalConfig.players === 'number' && finalConfig.players > 0) {
+        let i = 1;
+        while (i <= finalConfig.players) {
+          const player = new DTPlayer(`player${i}`);
+          this._library.add(player);
+          i += 1;
+        }
+      } else if (Array.isArray(finalConfig.players)) {
+        this._library.addMany(finalConfig.players);
+      }
+    }
+
+    if (finalConfig.errors) {
+      finalOptions.errors = finalConfig.errors;
+    }
+  }
+
+  /**
+   * Get one DTPlayer instance by id into the library.
+   *
+   * @param id string _id property of the DTPlayer instance to get.
+   */
+  getPlayer(id: string): DYOToolsPlayer {
+    return this._library.get(id);
+  }
+
+  /**
+   * Add one DTPlayer instance into the library.
+   *
+   * @param player DYOToolsPlayer instance to add.
+   */
+  addPlayer(player: DYOToolsPlayer): void {
+    this._library.add(player);
+  }
+
+  /**
+   * Remove one DTPlayer instance by id from the library.
+   *
+   * @param id string _id property of the DTPlayer instance to remove.
+   */
+  removePlayer(id: string): void {
+    this._library.remove(id);
+  }
+
+  /**
+   * Find DTPlayer instances into the Library.
+   *
+   * @see [find](#find) method for search specifications.
+   * @param filters DTBunchFilters filters to apply.
+   */
+  findPlayers(filters: Partial<DTBunchFilters>): DYOToolsPlayer[] {
+    return this._library.find(filters);
+  }
+}

package/src/types/core.ts

@@ -0,0 +1,169 @@
+import { DTBunch, DTComponent } from '../index';
+import DYOToolsElement from '../core/DTElement';
+
+/** Constants Enum * */
+export enum FilterOperatorType {
+  EQ = '$eq',
+  IN = '$in',
+  NIN = '$nin',
+  NE = '$ne',
+  LTE = '$lte',
+  GTE = '$gte',
+  CONTAINS = '$contains',
+  NCONTAINS = '$ncontains',
+}
+
+/** Common Types * */
+export type StandardPrimitiveType = string | number | boolean | null | undefined;
+export type StandardPrimitiveTypeWithArray = string | number | boolean | Array<string | number | boolean> | null | undefined;
+
+/** DYO Finder interfaces * */
+export type DYOFinderConfiguration = Record<string, DYOFinderConfigurationProp>;
+export type DYOFinderComponentType = DTComponent & {
+  getAll: () => DTComponent[],
+};
+
+export interface DYOFinderConfigurationPropDefault {
+  operators: FilterOperatorType[],
+  getValue: (item: DTComponent, ctx?: DTComponent) => StandardPrimitiveType,
+  objectSearch: false,
+}
+
+export interface DYOFinderConfigurationPropObjectSearch {
+  operators: FilterOperatorType[],
+  getValue: (item: DTComponent, ctx?: DTComponent) => Record<string, StandardPrimitiveTypeWithArray>,
+  objectSearch: true,
+}
+export type DYOFinderConfigurationProp = DYOFinderConfigurationPropDefault | DYOFinderConfigurationPropObjectSearch;
+
+export interface DYOFinderFilterOperatorBase {
+  [FilterOperatorType.EQ]: StandardPrimitiveType
+  [FilterOperatorType.IN]: Array<StandardPrimitiveType>
+  [FilterOperatorType.NIN]: Array<StandardPrimitiveType>
+  [FilterOperatorType.NE]: StandardPrimitiveType
+}
+export interface DYOFinderFilterOperatorAdvanced {
+  [FilterOperatorType.LTE]: number
+  [FilterOperatorType.GTE]: number
+  [FilterOperatorType.CONTAINS]: StandardPrimitiveType
+  [FilterOperatorType.NCONTAINS]: StandardPrimitiveType
+}
+
+export type DYOFinderFilterOperator = DYOFinderFilterOperatorBase & DYOFinderFilterOperatorAdvanced;
+export type DYOFinderFilterOperatorArgument = Partial<DYOFinderFilterOperator | Record<string, Partial<DYOFinderFilterOperator>>>;
+export type DYOFinderFilters = Record<string, DYOFinderFilterOperatorArgument>;
+
+/** DTComponent interfaces * */
+/**
+ * DTComponent default options configuration.
+ */
+export interface DTComponentOptions {
+  /**
+   * Default *false*. If *true*, no exception is thrown when an error occurred, a new DTError instance is
+   * added to the _errors property array instead. If *false*, throw the exception with a DTError instance.
+   */
+  errors: boolean
+}
+
+export interface DTComponentToObject {
+  id: string
+  key: string
+  type: string
+}
+
+/** DTComponentWithMeta interfaces * */
+export type DTAcceptedMetaData = Record<
+string,
+StandardPrimitiveTypeWithArray
+>;
+
+/** DTElement interfaces * */
+export interface DTElementToObject<IComponentMeta> extends DTComponentToObject {
+  owner?: string
+  meta?: Partial<IComponentMeta>
+}
+
+/** DTBunch interfaces * */
+/**
+ * DTBunch option configuration.
+ */
+export interface DTBunchOptions extends DTComponentOptions {
+  /**
+   * Default *false*. If *true*, an error occurred when adding a new DTElement with the same key of an
+   * existing element into the bunch.
+   */
+  uniqueKey: boolean
+  /**
+   * Default *false*. If *true*, when a new DTElement is added at existing index (using **addAtIndex**
+   * or **addManyAtIndex** method), this component replaces the old one. If *false*, this component is added at the specified
+   * index and other existing component are reindexed with the following index.
+   */
+  replaceIndex: boolean
+  /**
+   * Default *false*. If *true*, when a new DTElement is added, the owner of this element becomes
+   * automatically the current bunch owner.
+   */
+  inheritOwner: boolean
+  /**
+   * Default *false*. If *true*, the container is not changed when a new DTElement is added.
+   * If *false*, when a new DTElement is added, the container of this element becomes automatically the current bunch instance
+   * and the element is removed from the old container Component (if defined).
+   */
+  virtualContainer: boolean
+}
+
+export interface DTBunchToObject<IComponentMeta> extends DTComponentToObject {
+  items: Array<DTElementToObject<DTAcceptedMetaData>>
+  owner?: string
+  meta?: Partial<IComponentMeta>
+}
+
+export interface DTBunchFilters {
+  id: Partial<DYOFinderFilterOperatorBase>
+  key: Partial<DYOFinderFilterOperatorBase>
+  container: Partial<DYOFinderFilterOperatorBase>
+  owner: Partial<DYOFinderFilterOperatorBase>
+  meta: Record<string, Partial<DYOFinderFilterOperatorBase & DYOFinderFilterOperatorAdvanced>>
+}
+
+/** DTManager interfaces * */
+export type DTManagerItemsType<IBunchItem extends DYOToolsElement<DTAcceptedMetaData>> = Record<string, DTManagerItemType<IBunchItem>>;
+export type DTManagerItemType<IBunchItem extends DYOToolsElement<DTAcceptedMetaData>> = {
+  scope: string,
+  item: DTBunch<IBunchItem>,
+};
+
+export interface DTManagerFilters extends DYOFinderFilters {
+  id: Partial<DYOFinderFilterOperatorBase>
+  key: Partial<DYOFinderFilterOperatorBase>
+  owner: Partial<DYOFinderFilterOperatorBase>
+  scope: Partial<DYOFinderFilterOperatorBase>
+  meta: Record<string, Partial<DYOFinderFilterOperatorBase & DYOFinderFilterOperatorAdvanced>>
+}
+
+/**
+ * DTManager option configuration.
+ */
+export interface DTManagerOptions extends DTComponentOptions {
+  /**
+   * Default *false*. If *true*, when a bunch instance is removed from the Manager _items, the process performs also
+   * a removal from the Manager Library of all DTElement instances of the bunch.
+   */
+  libraryDeletion: boolean,
+}
+
+export interface DTManagerToObject extends DTComponentToObject {
+  items: Array<DTBunchToObject<DTAcceptedMetaData> & { scope: string }>
+}
+
+/** DTModule interfaces * */
+export interface DTModuleToObject extends DTComponentToObject {
+  enabled: boolean
+}
+
+/** DTMaster interfaces * */
+export interface DTMasterToObject extends DTComponentToObject {
+  managers: Array<DTManagerToObject>,
+  actions: Array<DTComponentToObject>,
+  modules: Array<DTModuleToObject>,
+}