dyo-tools 0.3.0 → 0.4.0

package/src/core/DTComponent.ts

@@ -1,225 +1,258 @@
-import * as uuid from 'uuid';
-import DYOToolsError from './DTError';
-import { DTComponentOptions } from '../types';
-
-/**
- * @template {string} DTComponentOptions
- */
-export default abstract class DYOToolsComponent<IComponentOptions extends DTComponentOptions = DTComponentOptions> {
-  /**
-   * Component unique ID. Use uuid v4 generator.
-   */
-  protected _id: string;
-
-  /**
-   * Component specific and accessible label.
-   * If not provided, the key is set with ID by default.
-   */
-  protected _key: string;
-
-  /**
-   * Component Parent Context.
-   *
-   * A component can have only one *context*, and be managed by a parent Component.
-   */
-  protected _context?: DYOToolsComponent;
-
-  /**
-   * Higher Level Component category.
-   *
-   * Describing component Type, like Element, Bunch, Manager...
-   */
-  protected abstract _componentType: string;
-
-  /**
-   * Second Level Component category.
-   *
-   * Describing component Domain, like Card, Dice, Token...
-   */
-  protected _domain?: string;
-
-  /**
-   * Third Level Component category.
-   *
-   * Describing component extra type, like Hand, Deck, Trick...
-   */
-  protected _subKind?: string;
-
-  /**
-   * Array of current errors for the Component.
-   *
-   * Errors are only available if the **errors** option is enabled.
-   */
-  protected _errors: DYOToolsError[];
-
-  /**
-   * Component options configuration.
-   * Defined by generic type IComponentOptions.
-   *
-   * For all component, global option can be :
-   * * **errors** : 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.
-   */
-  protected _options: IComponentOptions;
-
-  /**
-   * Set automatic unique _id and _key.
-   *
-   * @param key Optional Key to set. If not provided, set the _key with the _id value.
-   * @param options Specific options configuration for the instance. Default empty object.
-   */
-  constructor(key?: string, options: Partial<IComponentOptions> = {}) {
-    this._id = uuid.v4();
-    this._key = key || this._id;
-    this._errors = [];
-
-    const defaultOptions: DTComponentOptions = {
-      errors: false,
-    };
-    this._options = {
-      ...defaultOptions,
-      ...options,
-    } as IComponentOptions;
-  }
-
-  /**
-   * Getter for _id property.
-   */
-  getId(): string {
-    return this._id;
-  }
-
-  /**
-   * Getter for _key property.
-   */
-  getKey(): string {
-    return this._key;
-  }
-
-  /**
-   * Getter for _context property.
-   *
-   * @param contextType If provided, the getter parse all component level hierarchy to find the corresponding component
-   * with **contextType** as _componentType value, and returns it. Return undefined if not found.
-   *
-   * @returns Direct parent Component or higher level Component if filtered with **contextType**.
-   * Returns undefined if context doesn't exist.
-   */
-  getContext<IContext extends DYOToolsComponent = DYOToolsComponent>(contextType?: string): IContext | undefined {
-    if (this._context) {
-      if (!contextType || this._context.getComponentType() === contextType) {
-        return this._context as IContext;
-      }
-      return this._context.getContext(contextType);
-    }
-    return undefined;
-  }
-
-  /**
-   * Setter for _context property.
-   */
-  setContext<IContext extends DYOToolsComponent = DYOToolsComponent>(value: IContext): void {
-    this._context = value;
-  }
-
-  /**
-   * Remove the current context of component.
-   */
-  removeContext(): void {
-    this._context = undefined;
-  }
-
-  /**
-   * Getter for _componentType property.
-   */
-  getComponentType(): string {
-    return this._componentType;
-  }
-
-  /**
-   * Getter for _domain property.
-   */
-  getDomain(): string {
-    return this._domain;
-  }
-
-  /**
-   * Getter for _subKind property.
-   */
-  getSubKind(): string {
-    return this._subKind;
-  }
-
-  /**
-   * Getter for _errors property.
-   *
-   * Note : Errors are always provided by the higher order component, defined into the _context property.
-   */
-  getErrors(): DYOToolsError[] {
-    if (this.getContext()) {
-      return this.getContext().getErrors();
-    }
-    return this._errors;
-  }
-
-  /**
-   * Return the last error (most recent) of the current component. Undefined if _errors is empty.
-   *
-   * Note : Errors are always provided by the higher order component, defined into the _context property.
-   */
-  getLastError(): DYOToolsError | undefined {
-    if (this.getContext()) {
-      return this.getContext().getLastError();
-    }
-    return this._errors.length > 0 ? this._errors[this._errors.length - 1] : undefined;
-  }
-
-  /**
-   * Generic method to trigger an error, depending on the **errors** option :
-   * * if the option is set to *false*, throw the DTError instance passed as an argument.
-   * * if the option is set to *true*, add DTError instance passed as an argument in the _errors array.
-   *
-   * Note : Errors are always stored into the higher order component, defined into the _context property.
-   *
-   * @param error DYOToolsError instance to trigger
-   */
-  triggerError(error: DYOToolsError): void {
-    const { errors = false } = this._options;
-    if (this.getContext()) {
-      this.getContext().triggerError(error);
-    } else if (!errors) {
-      throw error;
-    } else {
-      this._errors.push(error);
-    }
-  }
-
-  /**
-   * Clear all current errors.
-   *
-   * Note : Errors are always stored into the higher order component, defined into the _context property.
-   */
-  clearErrors(): void {
-    if (this.getContext()) {
-      this.getContext().clearErrors();
-    }
-    this._errors = [];
-  }
-
-  /**
-   * Getter for _options property.
-   */
-  getOptions(): IComponentOptions {
-    return this._options;
-  }
-
-  /**
-   * Abstract method for JSON Object representation of the component and returning it.
-   */
-  abstract toObject(): unknown;
-
-  /**
-   * Abstract method for String representation of the component and returning it.
-   */
-  abstract toString(): string;
-}
+import { v6 as uuidV6 } from 'uuid';
+import DTError from './DTError';
+import { DIXObject, DTComponentOptions } from '../types';
+
+/**
+ * @template {string} DTComponentOptions
+ */
+export default abstract class DTComponent<
+  IComponentOptions extends DTComponentOptions = DTComponentOptions,
+> {
+  /**
+   * Component unique ID. Use uuid v4 generator.
+   */
+  protected _id: string;
+
+  /**
+   * Component specific and accessible label.
+   * If not provided, the key is set with ID by default.
+   */
+  protected _key: string;
+
+  /**
+   * Component Parent Context.
+   *
+   * A component can have only one *context*, and be managed by a parent Component.
+   */
+  protected _context?: DTComponent;
+
+  /**
+   * Higher Level Component category.
+   *
+   * Describing component Type, like Element, Bunch, Manager...
+   */
+  protected abstract _componentType: string;
+
+  /**
+   * Second Level Component category.
+   *
+   * Describing component Domain, like Card, Dice, Token...
+   */
+  protected _domain?: string;
+
+  /**
+   * Third Level Component category.
+   *
+   * Describing component extra type, like Hand, Deck, Trick...
+   */
+  protected _subKind?: string;
+
+  /**
+   * Array of current errors for the Component.
+   *
+   * Errors are only available if the **errors** option is enabled.
+   */
+  protected _errors: DTError[];
+
+  /**
+   * Component options configuration.
+   * Defined by generic type IComponentOptions.
+   *
+   * For all component, global option can be :
+   * * **errors** : 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.
+   * * **syncId** : Default *undefined*. If specified, the string argument passed will be the id of the new DTComponent.
+   * Used to synchronize ids between to instances (with the DIX Module). Be careful when using.
+   */
+  protected _options: IComponentOptions;
+
+  /**
+   * Set automatic unique _id and _key.
+   *
+   * @param key Optional Key to set. If not provided, set the _key with the _id value.
+   * @param options Specific options configuration for the instance. Default empty object.
+   */
+  constructor(key?: string, options: Partial<IComponentOptions> = {}) {
+    const defaultOptions: DTComponentOptions = {
+      errors: false,
+      syncId: undefined,
+    };
+
+    this._options = {
+      ...defaultOptions,
+      ...options,
+    } as IComponentOptions;
+
+    this._id = this._options.syncId ?? uuidV6();
+    this._key = key || this._id;
+    this._errors = [];
+  }
+
+  /**
+   * Getter for _id property.
+   */
+  getId(): string {
+    return this._id;
+  }
+
+  /**
+   * Getter for _key property.
+   */
+  getKey(): string {
+    return this._key;
+  }
+
+  /**
+   * Getter for _context property.
+   *
+   * @param contextType If provided, the getter parse all component level hierarchy to find the corresponding component
+   * with **contextType** as _componentType value, and returns it. Return undefined if not found.
+   *
+   * @returns Direct parent Component or higher level Component if filtered with **contextType**.
+   * Returns undefined if context doesn't exist.
+   */
+  getContext<IContext extends DTComponent = DTComponent>(contextType?: string): IContext | undefined {
+    if (this._context) {
+      if (!contextType || this._context.getComponentType() === contextType) {
+        return this._context as IContext;
+      }
+      return this._context.getContext(contextType);
+    }
+    return undefined;
+  }
+
+  /**
+   * Setter for _context property.
+   */
+  setContext<IContext extends DTComponent = DTComponent>(value: IContext): void {
+    this._context = value;
+  }
+
+  /**
+   * Remove the current context of component.
+   */
+  removeContext(): void {
+    this._context = undefined;
+  }
+
+  /**
+   * Getter for _componentType property.
+   */
+  getComponentType(): string {
+    return this._componentType;
+  }
+
+  /**
+   * Getter for _domain property.
+   */
+  getDomain(): string {
+    return this._domain;
+  }
+
+  /**
+   * Getter for _subKind property.
+   */
+  getSubKind(): string {
+    return this._subKind;
+  }
+
+  /**
+   * Getter for _errors property.
+   *
+   * Note : Errors are always provided by the higher order component, defined into the _context property.
+   */
+  getErrors(): DTError[] {
+    if (this.getContext()) {
+      return this.getContext().getErrors();
+    }
+    return this._errors;
+  }
+
+  /**
+   * Return the last error (most recent) of the current component. Undefined if _errors is empty.
+   *
+   * Note : Errors are always provided by the higher order component, defined into the _context property.
+   */
+  getLastError(): DTError | undefined {
+    if (this.getContext()) {
+      return this.getContext().getLastError();
+    }
+    return this._errors.length > 0 ? this._errors[this._errors.length - 1] : undefined;
+  }
+
+  /**
+   * Generic method to trigger an error, depending on the **errors** option :
+   * * if the option is set to *false*, throw the DTError instance passed as an argument.
+   * * if the option is set to *true*, add DTError instance passed as an argument in the _errors array.
+   *
+   * Note : Errors are always stored into the higher order component, defined into the _context property.
+   *
+   * @param error DYOToolsError instance to trigger
+   */
+  triggerError(error: DTError): void {
+    const { errors = false } = this._options;
+    if (this.getContext()) {
+      this.getContext().triggerError(error);
+    } else if (!errors) {
+      throw error;
+    } else {
+      this._errors.push(error);
+    }
+  }
+
+  /**
+   * Clear all current errors.
+   *
+   * Note : Errors are always stored into the higher order component, defined into the _context property.
+   */
+  clearErrors(): void {
+    if (this.getContext()) {
+      this.getContext().clearErrors();
+    }
+    this._errors = [];
+  }
+
+  /**
+   * Getter for _options property.
+   */
+  getOptions(): IComponentOptions {
+    return this._options;
+  }
+
+  /**
+   * Return DIX Object representation of the DTComponent instance.
+   *
+   * @returns DIX Object representation of the DTComponent.
+   */
+  toDIXObject(): Record<string, DIXObject> {
+    const dixOptions = this._options;
+    delete dixOptions.syncId;
+
+    const dixObject: DIXObject = {
+      useClass: this.constructor.name,
+      key: this._key,
+      componentType: this._componentType,
+      options: JSON.stringify(this._options),
+    };
+
+    return {
+      [this._id]: dixObject,
+    };
+  }
+
+  /**
+   * Abstract method to update the component with a DIX Object Format.
+   * @param dix DIX Object to use for updating.
+   */
+  abstract updateFromDix(dix: Record<string, DIXObject>): void;
+
+  /**
+   * Abstract method for JSON Object representation of the component and returning it.
+   */
+  abstract toObject(): unknown;
+
+  /**
+   * Abstract method for String representation of the component and returning it.
+   */
+  abstract toString(): string;
+}

package/src/core/DTComponentPhysical.ts

@@ -1,53 +1,88 @@
-import { DTAcceptedMetaData, DTComponentOptions } from '../types';
-import DYOToolsComponentWithMeta from './DTComponentWithMeta';
-import DYOToolsMaster from './DTMaster';
-
-export default abstract class DYOToolsComponentPhysical<
-  IComponentMeta extends DTAcceptedMetaData,
-  IComponentOptions extends DTComponentOptions = DTComponentOptions,
-  > extends DYOToolsComponentWithMeta<IComponentMeta, IComponentOptions> {
-  /**
-   * Owner string representation, if defined.
-   */
-  protected _owner?: string;
-
-  /**
-   * Returns Manager component from context, or undefined.
-   */
-  getManager(): DYOToolsMaster | undefined {
-    return this.getContext<DYOToolsMaster>('manager');
-  }
-
-  /**
-   * Returns Master component from context, or undefined.
-   */
-  getMaster(): DYOToolsMaster | undefined {
-    return this.getContext<DYOToolsMaster>('master');
-  }
-
-  /**
-   * Getter for _owner property.
-   */
-  getOwner(): string {
-    return this._owner;
-  }
-
-  /**
-   * Setter for _owner property.
-   */
-  setOwner(value: string): void {
-    this._owner = value;
-  }
-
-  /**
-   * Remove the current owner of element.
-   */
-  removeOwner(): void {
-    this._owner = undefined;
-  }
-
-  /**
-   * Abstract method for copying the Component and returning it.
-   */
-  abstract copy(): DYOToolsComponentPhysical<IComponentMeta, IComponentOptions>;
-}
+import { DIXObject, DTAcceptedMetaData, DTComponentOptions } from '../types';
+import DTComponentWithMeta from './DTComponentWithMeta';
+import DTMaster from './DTMaster';
+import DTManager from './DTManager';
+
+export default abstract class DTComponentPhysical<
+  IComponentMeta extends DTAcceptedMetaData,
+  IComponentOptions extends DTComponentOptions = DTComponentOptions,
+  > extends DTComponentWithMeta<IComponentMeta, IComponentOptions> {
+  /**
+   * Owner string representation, if defined.
+   */
+  protected _owner?: string;
+
+  /**
+   * Returns Manager component from context, or undefined.
+   */
+  getManager(): DTManager | undefined {
+    return this.getContext<DTManager>('manager');
+  }
+
+  /**
+   * Returns Master component from context, or undefined.
+   */
+  getMaster(): DTMaster | undefined {
+    return this.getContext<DTMaster>('master');
+  }
+
+  /**
+   * Getter for _owner property.
+   */
+  getOwner(): string {
+    return this._owner;
+  }
+
+  /**
+   * Setter for _owner property.
+   */
+  setOwner(value: string): void {
+    this._owner = value;
+  }
+
+  /**
+   * Remove the current owner of element.
+   */
+  removeOwner(): void {
+    this._owner = undefined;
+  }
+
+  /**
+   * Return DIX Object representation of the DTComponentPhysical instance.
+   *
+   * @returns DIX Object representation of the DTComponentPhysical.
+   */
+  toDIXObject(): Record<string, DIXObject> {
+    const parentDixObject = super.toDIXObject();
+    const dixObject: DIXObject = {
+      ...parentDixObject[this._id],
+    };
+
+    if (this._owner) {
+      dixObject.owner = this._owner;
+    }
+
+    return {
+      [this._id]: dixObject,
+    };
+  }
+
+  /**
+   * Update the DTComponentPhysical instance with a DIX Object.
+   *
+   * @param dix DIX Object to use for updating.
+   */
+  updateFromDix(dix: Record<string, DIXObject>) {
+    super.updateFromDix(dix);
+    const dixObject = dix[this._id];
+
+    if (dixObject && dixObject.owner) {
+      this._owner = dixObject.owner;
+    }
+  }
+
+  /**
+   * Abstract method for copying the Component and returning it.
+   */
+  abstract copy(): DTComponentPhysical<IComponentMeta, IComponentOptions>;
+}