dyo-tools 0.1.0-rc1

package/src/core/DTComponent.ts

@@ -0,0 +1,135 @@
+import * as uuid from 'uuid';
+
+export default abstract class DYOToolsComponent {
+  /**
+   * 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 *physical 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;
+
+  /**
+   * Set automatic unique _id and _key.
+   *
+   * @param key Optional Key to set. If not provided, set the _key with the _id value.
+   */
+  constructor(key?: string) {
+    this._id = uuid.v4();
+    this._key = key || this._id;
+  }
+
+  /**
+   * 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(contextType?: string): DYOToolsComponent | undefined {
+    if (this._context) {
+      if (!contextType || this._context.getComponentType() === contextType) {
+        return this._context;
+      }
+      return this._context.getContext(contextType);
+    }
+    return undefined;
+  }
+
+  /**
+   * Setter for _context property.
+   */
+  setContext(value: DYOToolsComponent): 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;
+  }
+
+  /**
+   * Abstract method for copying the Component and returning it.
+   */
+  abstract copy(): DYOToolsComponent;
+
+  /**
+   * 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/DTComponentWithMeta.ts

@@ -0,0 +1,62 @@
+import DYOToolsComponent from './DTComponent';
+import { DTAcceptedMetaData } from '../types';
+
+export default abstract class DYOToolsComponentWithMeta<IComponentMeta extends DTAcceptedMetaData> extends DYOToolsComponent {
+  /**
+   * 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 };
+  }
+}

package/src/core/DTElement.ts

@@ -0,0 +1,96 @@
+import DYOToolsComponentWithMeta from './DTComponentWithMeta';
+import DYOToolsPlayer from './DTPlayer';
+import { DTAcceptedMetaData, DTElementToObject } from '../types';
+
+export default class DYOToolsElement<
+  IComponentMeta extends DTAcceptedMetaData,
+  > extends DYOToolsComponentWithMeta<IComponentMeta> {
+  /**
+   * Defining component type to "element".
+   */
+  protected _componentType = 'element';
+
+  /**
+   * DTPlayer instance who owns the current element
+   */
+  private _owner?: DYOToolsPlayer<DTAcceptedMetaData>;
+
+  /**
+   * Getter for _owner property.
+   */
+  getOwner(): DYOToolsPlayer<DTAcceptedMetaData> {
+    return this._owner;
+  }
+
+  /**
+   * Setter for _owner property.
+   */
+  setOwner(value: DYOToolsPlayer<DTAcceptedMetaData>): void {
+    this._owner = value;
+  }
+
+  /**
+   * Remove the current owner of element.
+   */
+  removeOwner(): void {
+    this._owner = 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(): DYOToolsElement<IComponentMeta> {
+    const copyElement = new DYOToolsElement<IComponentMeta>(this._key);
+    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.getKey()}`;
+    }
+
+    return `Component ${this._key} - Type: Element${ownerKey}`;
+  }
+}

package/src/core/DTError.ts

@@ -0,0 +1,78 @@
+import DYOToolsComponent from './DTComponent';
+
+export default class DYOToolsError 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?: DYOToolsComponent;
+
+  /**
+   * DTComponent which is directly involved in the error trigger.
+   */
+  protected convicted?: DYOToolsComponent;
+
+  /**
+   * Set all property for a new DTError.
+   *
+   * @param code
+   * @param message
+   * @param initiator
+   * @param convicted
+   */
+  constructor(code: string, message: string, initiator?: DYOToolsComponent, convicted?: DYOToolsComponent) {
+    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(): DYOToolsComponent {
+    return this.initiator;
+  }
+
+  /**
+   * Getter for convicted property.
+   */
+  getConvicted(): DYOToolsComponent {
+    return this.convicted;
+  }
+}

package/src/core/DTPlayer.ts

@@ -0,0 +1,57 @@
+import DYOToolsComponentWithMeta from './DTComponentWithMeta';
+import { DTAcceptedMetaData, DTPlayerToObject } from '../types';
+
+export default class DYOToolsPlayer<IComponentMeta extends DTAcceptedMetaData> extends DYOToolsComponentWithMeta<IComponentMeta> {
+  /**
+   * Defining component type to "player".
+   */
+  protected _componentType = 'player';
+
+  /**
+   * Create and return a new DTPlayer instance by applying from current instance :
+   * - Copy _key property
+   * - Copy _meta property
+   *
+   * @returns New DTPlayer instance copied.
+   */
+  copy(): DYOToolsPlayer<IComponentMeta> {
+    const copyElement = new DYOToolsPlayer<IComponentMeta>(this._key);
+    copyElement.setManyMeta({ ...this.getManyMeta() });
+
+    return copyElement;
+  }
+
+  /**
+   * Return JSON Object representation of the Player instance.
+   *
+   * JSON Object returned has the following structure :
+   * * **id** : _id property of the Player.
+   * * **key** : _key property of the Player.
+   * * **type** : _componentType property of the Player.
+   * * **meta** : JSON Object of all current metadata in _meta property of the Player (only if not empty).
+   *
+   * @returns JSON Object representation of the Player.
+   */
+  toObject(): DTPlayerToObject<IComponentMeta> {
+    const objectPlayer: DTPlayerToObject<IComponentMeta> = {
+      id: this._id,
+      key: this._key,
+      type: this._componentType,
+    };
+
+    if (this._meta && Object.keys(this._meta).length > 0) {
+      objectPlayer.meta = { ...this.getManyMeta() };
+    }
+
+    return objectPlayer;
+  }
+
+  /**
+   * Return String representation of the Player instance.
+   *
+   * @returns String representation of the Player.
+   */
+  toString(): string {
+    return `Component ${this._key} - Type: Player`;
+  }
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+// All exports
+export { default as DTComponent } from './core/DTComponent';
+export { default as DTComponentWithMeta } from './core/DTComponentWithMeta';
+export { default as DTElement } from './core/DTElement';
+export { default as DTBunch } from './core/DTBunch';
+export { default as DTPlayer } from './core/DTPlayer';
+export { default as DTError } from './core/DTError';

package/src/types/index.ts

@@ -0,0 +1,76 @@
+/** filters Methods * */
+export enum FilterOperatorType {
+  EQ = '$eq',
+  IN = '$in',
+  NIN = '$nin',
+  NE = '$ne',
+  LTE = '$lte',
+  GTE = '$gte',
+  CONTAINS = '$contains',
+  NCONTAINS = '$ncontains',
+}
+
+export type StandardPrimitiveType = string | number | boolean | null;
+
+/** DTComponent interfaces * */
+export interface DTComponentToObject {
+  id: string
+  key: string
+  type: string
+}
+
+/** DTComponentWithMeta interfaces * */
+export type DTAcceptedMetaDataValue = string | number | boolean | Array<string | number | boolean> | undefined;
+export type DTAcceptedMetaData = Record<
+string,
+DTAcceptedMetaDataValue
+>;
+
+/** DTElement interfaces * */
+export interface DTElementToObject<IComponentMeta> extends DTComponentToObject {
+  owner?: string
+  meta?: Partial<IComponentMeta>
+}
+
+/** DTBunch interfaces * */
+export interface DTBunchOptionsEditable {
+  errors: boolean
+  uniqueKey: boolean
+  replaceIndex: boolean
+  inheritOwner: boolean
+}
+
+export interface DTBunchOptionsConstructor extends DTBunchOptionsEditable {
+  virtualContext: boolean
+}
+
+export interface DTBunchToObject<IComponentMeta> extends DTComponentToObject {
+  items: Array<DTElementToObject<DTAcceptedMetaData>>
+  owner?: string
+  meta?: Partial<IComponentMeta>
+}
+
+export type DTBunchFilterWithBaseOperator = {
+  [FilterOperatorType.EQ]: StandardPrimitiveType
+  [FilterOperatorType.IN]: Array<StandardPrimitiveType>
+  [FilterOperatorType.NIN]: Array<StandardPrimitiveType>
+  [FilterOperatorType.NE]: StandardPrimitiveType
+};
+export interface DTBunchFilterWithMetaOperator extends DTBunchFilterWithBaseOperator {
+  [FilterOperatorType.LTE]: number
+  [FilterOperatorType.GTE]: number
+  [FilterOperatorType.CONTAINS]: StandardPrimitiveType
+  [FilterOperatorType.NCONTAINS]: StandardPrimitiveType
+}
+export interface DTBunchFilters {
+  id: Partial<DTBunchFilterWithBaseOperator>
+  key: Partial<DTBunchFilterWithBaseOperator>
+  context: Partial<DTBunchFilterWithBaseOperator>
+  owner: Partial<DTBunchFilterWithBaseOperator>
+  meta: Record<string, Partial<DTBunchFilterWithMetaOperator>>
+}
+
+/** DTPlayer interfaces * */
+export interface DTPlayerToObject<IComponentMeta> extends DTComponentToObject {
+  meta?: Partial<IComponentMeta>
+}

package/src/utils/filters.ts

@@ -0,0 +1,64 @@
+import { FilterOperatorType, StandardPrimitiveType } from '../types';
+
+export function validFiltersForItem(itemProp: StandardPrimitiveType,
+  filter: StandardPrimitiveType,
+  operator: FilterOperatorType.EQ): boolean;
+export function validFiltersForItem(itemProp: StandardPrimitiveType,
+  filter: StandardPrimitiveType[],
+  operator: FilterOperatorType.IN | FilterOperatorType.NIN): boolean;
+export function validFiltersForItem(itemProp: StandardPrimitiveType,
+  filter: StandardPrimitiveType,
+  operator: FilterOperatorType.NE): boolean;
+export function validFiltersForItem(itemProp: number, filter: number,
+  operator: FilterOperatorType.LTE |
+  FilterOperatorType.GTE): boolean;
+export function validFiltersForItem(itemProp: StandardPrimitiveType[],
+  filter: StandardPrimitiveType,
+  operator: FilterOperatorType.CONTAINS | FilterOperatorType.NCONTAINS): boolean;
+export function validFiltersForItem(
+  itemProp: StandardPrimitiveType | StandardPrimitiveType[],
+  filter: StandardPrimitiveType | StandardPrimitiveType[],
+  operator: FilterOperatorType = FilterOperatorType.EQ,
+): boolean {
+  // $eq Filter
+  if (operator === FilterOperatorType.EQ) {
+    return itemProp === filter;
+  }
+  // $in Filter
+  if (operator === FilterOperatorType.IN) {
+    return filter ? (filter as StandardPrimitiveType[]).includes(itemProp as StandardPrimitiveType) : false;
+  }
+  // $nin Filter
+  if (operator === FilterOperatorType.NIN) {
+    return filter ? !(filter as StandardPrimitiveType[]).includes(itemProp as StandardPrimitiveType) : false;
+  }
+  // $ne Filter
+  /* c8 ignore next */
+  if (operator === FilterOperatorType.NE) {
+    return itemProp !== filter;
+  }
+  // $lte Filter
+  if (operator === FilterOperatorType.LTE) {
+    if (typeof itemProp === 'number' && typeof filter === 'number') {
+      return itemProp <= filter;
+    }
+    return false;
+  }
+  // $gte Filter
+  if (operator === FilterOperatorType.GTE) {
+    if (typeof itemProp === 'number' && typeof filter === 'number') {
+      return itemProp >= filter;
+    }
+    return false;
+  }
+  // $contains Filter
+  if (operator === FilterOperatorType.CONTAINS) {
+    return itemProp ? (itemProp as StandardPrimitiveType[]).includes(filter as StandardPrimitiveType) : false;
+  }
+  // $Ncontains Filter
+  if (operator === FilterOperatorType.NCONTAINS) {
+    return itemProp ? !(itemProp as StandardPrimitiveType[]).includes(filter as StandardPrimitiveType) : false;
+  }
+
+  return false;
+}