dyo-tools 0.4.0 → 0.4.1

package/src/core/DTComponent.ts

@@ -1,258 +0,0 @@
-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,88 +0,0 @@
-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>;
-}

package/src/core/DTComponentWithMeta.ts

@@ -1,98 +0,0 @@
-import DTComponent from './DTComponent';
-import { DIXObject, DTAcceptedMetaData, DTComponentOptions } from '../types';
-
-export default abstract class DTComponentWithMeta<
-  IComponentMeta extends DTAcceptedMetaData,
-  IComponentOptions extends DTComponentOptions = DTComponentOptions,
-  > extends DTComponent<IComponentOptions> {
-  /**
-   * Component meta data.
-   * Defined by generic type IComponentMeta.
-   * @default {}
-   */
-  protected _meta : Partial<IComponentMeta> = {} as Partial<IComponentMeta>;
-
-  /**
-   * Getter for one meta by key.
-   *
-   * @param metaKey Key name of one meta data.
-   *
-   * @returns Associated meta **metaKey** value or undefined if not found.
-   */
-  getMeta<K extends keyof IComponentMeta>(metaKey : K) : IComponentMeta[K] | undefined {
-    return this._meta && this._meta[metaKey];
-  }
-
-  /**
-   * Setter for one meta by key.
-   *
-   * @param metaKey Key name of the meta data to update.
-   * @param metaValue New value to set into the meta data.
-   */
-  setMeta<K extends keyof IComponentMeta>(metaKey : K, metaValue : IComponentMeta[K]) : void {
-    this._meta[metaKey] = metaValue;
-  }
-
-  /**
-   * Returns multiple defined keys values of meta data.
-   *
-   * @param metaKeys Array of keys to filter for meta data. If not provided or empty, returns all keys.
-   *
-   * @returns Meta data object with **metaKeys** provided keys only.
-   */
-  getManyMeta(metaKeys : Array<keyof IComponentMeta> = []) : Partial<IComponentMeta> {
-    const arrayMeta: Partial<IComponentMeta> = {} as Partial<IComponentMeta>;
-    if (!metaKeys.length) {
-      return this._meta;
-    }
-
-    metaKeys.forEach((key) => {
-      if (this._meta && this._meta[key]) {
-        arrayMeta[key] = this._meta[key];
-      }
-    });
-    return arrayMeta;
-  }
-
-  /**
-   * Set multiple meta data.
-   *
-   * @param metaValues Object of meta data to set, according to the meta data property type.
-   */
-  setManyMeta(metaValues : Partial<IComponentMeta>) : void {
-    this._meta = { ...this._meta, ...metaValues };
-  }
-
-  /**
-   * Return DIX Object representation of the DTComponentWithMeta instance.
-   *
-   * @returns DIX Object representation of the DTComponentWithMeta.
-   */
-  toDIXObject(): Record<string, DIXObject> {
-    const parentDixObject = super.toDIXObject();
-    const dixObject: DIXObject = {
-      ...parentDixObject[this._id],
-    };
-
-    if (Object.keys(this._meta).length > 0) {
-      dixObject.meta = JSON.stringify(this._meta);
-    }
-
-    return {
-      [this._id]: dixObject,
-    };
-  }
-
-  /**
-   * Update the DTComponentWithMeta instance with a DIX Object.
-   *
-   * @param dix DIX Object to use for updating.
-   */
-  updateFromDix(dix: Record<string, DIXObject>) {
-    const dixObject = dix[this._id];
-
-    if (dixObject && dixObject.meta) {
-      this._meta = JSON.parse(dixObject.meta);
-    }
-  }
-}

package/src/core/DTElement.ts

@@ -1,111 +0,0 @@
-import { DIXObject, DTAcceptedMetaData, DTElementToObject } from '../types';
-import DTComponentPhysical from './DTComponentPhysical';
-import DTBunch from './DTBunch';
-
-export default class DTElement<
-  IComponentMeta extends DTAcceptedMetaData,
-  > extends DTComponentPhysical<IComponentMeta> {
-  /**
-   * Defining component type to "element".
-   */
-  protected _componentType = 'element';
-
-  /**
-   * Component current **Container**.
-   *
-   * A container is a parent component which "contains" the current instance.
-   * **Context** and **container** are different components, with different purpose.
-   * For DYOToolsElement instances, a container is a DYOToolsBunch instance.
-   * @protected
-   */
-  protected _container: DTBunch;
-
-  /**
-   * Getter for _container property.
-   */
-  getContainer(): DTBunch | undefined {
-    return this._container;
-  }
-
-  /**
-   * Setter for _container property.
-   */
-  setContainer(container: DTBunch): void {
-    this._container = container;
-  }
-
-  /**
-   * Remove the current container of Element instance.
-   */
-  removeContainer(): void {
-    this._container = undefined;
-  }
-
-  /**
-   * Create and return a new DTElement instance by applying from current instance :
-   * - Copy _key property
-   * - Copy _meta property
-   *
-   * @returns New DTElement instance copied.
-   */
-  copy(): DTElement<IComponentMeta> {
-    const copyElement = new DTElement<IComponentMeta>(this._key, this._options);
-    copyElement.setManyMeta({ ...this.getManyMeta() });
-
-    return copyElement;
-  }
-
-  /**
-   * Return JSON Object representation of the Element instance.
-   *
-   * JSON Object returned has the following structure :
-   * * **id** : _id property of the Element.
-   * * **key** : _key property of the Element.
-   * * **type** : _componentType property of the Element.
-   * * **owner** : String representation of the current _owner property of the Element (only if defined).
-   * * **meta** : JSON Object of all current metadata in _meta property of the Element (only if not empty).
-   *
-   * @returns JSON Object representation of the Element.
-   */
-  toObject(): DTElementToObject<IComponentMeta> {
-    const objectElement: DTElementToObject<IComponentMeta> = {
-      id: this._id,
-      key: this._key,
-      type: this._componentType,
-    };
-
-    if (this._owner) {
-      objectElement.owner = this._owner.toString();
-    }
-
-    if (this._meta && Object.keys(this._meta).length > 0) {
-      objectElement.meta = { ...this.getManyMeta() };
-    }
-
-    return objectElement;
-  }
-
-  /**
-   * Return String representation of the Element instance.
-   *
-   * @returns String representation of the Element.
-   */
-  toString(): string {
-    let ownerKey = '';
-    if (this._owner) {
-      ownerKey = ` - Owner: ${this._owner}`;
-    }
-    const domainLabel = this._domain ? ` ${this._domain}` : '';
-
-    return `Component${domainLabel} ${this._key} - Type: Element${ownerKey}`;
-  }
-
-  /**
-   * Update the DTBunch instance with a DIX Object.
-   *
-   * @param dix DIX Object to use for updating.
-   */
-  updateFromDix(dix: Record<string, DIXObject>) {
-    super.updateFromDix(dix);
-  }
-}

package/src/core/DTError.ts

@@ -1,78 +0,0 @@
-import DTComponent from './DTComponent';
-
-export default class DTError extends Error {
-  /**
-   * Error code.
-   *
-   * Available error codes are :
-   * * **id_conflict** : _id property conflict between two DTComponent in the same context.
-   * * **key_conflict** : _key property conflict between two DTComponent in the same context.
-   */
-  protected code: string;
-
-  /**
-   * Error trigger date.
-   */
-  protected timestamp: Date;
-
-  /**
-   * DTComponent which trigger the error during its current execution process.
-   */
-  protected initiator?: DTComponent;
-
-  /**
-   * DTComponent which is directly involved in the error trigger.
-   */
-  protected convicted?: DTComponent;
-
-  /**
-   * Set all property for a new DTError.
-   *
-   * @param code
-   * @param message
-   * @param initiator
-   * @param convicted
-   */
-  constructor(code: string, message: string, initiator?: DTComponent, convicted?: DTComponent) {
-    super(message);
-    this.code = code;
-    this.timestamp = new Date();
-    this.initiator = initiator;
-    this.convicted = convicted;
-  }
-
-  /**
-   * Getter for code property.
-   */
-  getCode(): string {
-    return this.code;
-  }
-
-  /**
-   * Getter for message property (inherited from Error).
-   */
-  getMessage(): string {
-    return this.message;
-  }
-
-  /**
-   * Getter for timestamp property.
-   */
-  getTimestamp(): Date {
-    return this.timestamp;
-  }
-
-  /**
-   * Getter for initiator property.
-   */
-  getInitiator(): DTComponent {
-    return this.initiator;
-  }
-
-  /**
-   * Getter for convicted property.
-   */
-  getConvicted(): DTComponent {
-    return this.convicted;
-  }
-}