@api-client/core 0.6.14 → 0.6.17

package/src/models/data/DataEntity.ts

@@ -5,6 +5,9 @@ import { DataProperty, DataPropertyType } from "./DataProperty.js";
 import { DataAssociation } from "./DataAssociation.js";
 import { IBreadcrumb } from "../store/Breadcrumb.js";
 import { DataModel } from "./DataModel.js";
+import { INodeShape, IShapeUnion } from "../../amf/definitions/Shapes.js";
+import { AmfShapeGenerator } from "../../amf/AmfShapeGenerator.js";
+import { ApiSchemaGenerator } from "../../amf/ApiSchemaGenerator.js";
 
 export const Kind = 'Core#DataEntity';
 
@@ -60,6 +63,24 @@ export interface IDataEntity {
    * Whether this entity is deprecated.
    */
   deprecated?: boolean;
+
+  /**
+   * The schema allowing to translate the model into a specific format (like JSON, RAML, XML, etc.)
+   * 
+   * Schema limitations:
+   * 
+   * - can only occur on an adapted property. Has no effect on the "main" property. 
+   */
+  schema?: INodeShape;
+
+  /**
+   * The key of the entity that is adapted by this entity.
+   * Adapted entities can manipulate the shape of the schema for the entity.
+   * 
+   * Each value defined on the adapted entity changes the original value defined on
+   * the entity.
+   */
+  adapts?: string;
 }
 
 /**
@@ -114,6 +135,15 @@ export class DataEntity {
    */
   deprecated?: boolean;
 
+  /**
+   * The key of the entity that is adapted by this entity.
+   * Adapted entities can manipulate the shape of the schema for the entity.
+   * 
+   * Each value defined on the adapted entity changes the original value defined on
+   * the entity.
+   */
+  adapts?: string;
+
   static fromName(root: DataNamespace, name: string): DataEntity {
     const entity = new DataEntity(root);
     entity.info = Thing.fromName(name);
@@ -123,7 +153,7 @@ export class DataEntity {
   /**
    * @param input The data entity definition to restore.
    */
-  constructor(protected root: DataNamespace, input?: string | IDataEntity) {
+  constructor(public root: DataNamespace, input?: string | IDataEntity) {
     let init: IDataEntity;
     if (typeof input === 'string') {
       init = JSON.parse(input);
@@ -143,7 +173,10 @@ export class DataEntity {
     if (!DataEntity.isDataEntity(init)) {
       throw new Error(`Not a data entity.`);
     }
-    const { info, key = v4(), kind = Kind, tags, taxonomy, parents, properties, associations, deprecated } = init;
+    const { 
+      info, key = v4(), kind = Kind, tags, taxonomy, parents, properties, associations, 
+      deprecated, adapts,
+    } = init;
     this.kind = kind;
     this.key = key;
     if (info) {
@@ -151,7 +184,6 @@ export class DataEntity {
     } else {
       this.info = Thing.fromName('');
     }
-    
     if (Array.isArray(tags)) {
       this.tags = [...tags];
     } else {
@@ -167,7 +199,6 @@ export class DataEntity {
     } else {
       this.parents = [];
     }
-
     this.properties = [];
     if (Array.isArray(properties)) {
       properties.forEach(key => {
@@ -177,7 +208,6 @@ export class DataEntity {
         }
       });
     }
-
     this.associations = [];
     if (Array.isArray(associations)) {
       associations.forEach(key => {
@@ -187,12 +217,16 @@ export class DataEntity {
         }
       });
     }
-
     if (typeof deprecated === 'boolean') {
       this.deprecated = deprecated;
     } else {
       this.deprecated = undefined;
     }
+    if (typeof adapts === 'string') {
+      this.adapts = adapts;
+    } else {
+      this.adapts = undefined;
+    }
   }
 
   static isDataEntity(input: unknown): boolean {
@@ -227,6 +261,9 @@ export class DataEntity {
     if (typeof this.deprecated === 'boolean') {
       result.deprecated = this.deprecated;
     }
+    if (this.adapts) {
+      result.adapts = this.adapts;
+    }
     return result;
   }
 
@@ -243,8 +280,11 @@ export class DataEntity {
    * @param type The type of the property
    * @returns The created property
    */
-  addTypedProperty(type: DataPropertyType): DataProperty {
+  addTypedProperty(type: DataPropertyType, name?: string): DataProperty {
     const property = DataProperty.fromType(this.root, type);
+    if (name) {
+      property.info.name = name;
+    }
     this.root.definitions.properties.push(property);
     this.properties.push(property);
     return property;
@@ -295,8 +335,11 @@ export class DataEntity {
    * @param target The target entity key of the association
    * @returns The created association
    */
-  addTargetAssociation(target: string): DataAssociation {
+  addTargetAssociation(target: string, name?: string): DataAssociation {
     const result = DataAssociation.fromTarget(this.root, target);
+    if (name) {
+      result.info.name = name;
+    }
     this.root.definitions.associations.push(result);
     this.associations.push(result);
     return result;
@@ -321,15 +364,18 @@ export class DataEntity {
   /**
    * Reads the list of parents for the entity, inside the root namespace. The computed list contains the list of all
    * parents in the inheritance chain in no particular order.
+   * @param recursive Whether to include parent parents as well.
    */
-  getComputedParents(): DataEntity[] {
+  getComputedParents(recursive?: boolean): DataEntity[] {
     const { entities } = this.root.definitions;
     let result: DataEntity[] = [];
     this.parents.forEach((key) => {
       const parent = entities.find(i => i.key === key);
       if (parent) {
         result.push(parent);
-        result = result.concat(parent.getComputedParents());
+        if (recursive) {
+          result = result.concat(parent.getComputedParents());
+        }
       }
     });
     return result;
@@ -352,10 +398,10 @@ export class DataEntity {
     const { entities } = root.definitions;
     const result: DataEntity[] = [];
     associations.forEach((assoc) => {
-      if (!assoc.target) {
+      if (!assoc.targets.length) {
         return;
       }
-      const entity = entities.find(i => i.key === assoc.target);
+      const entity = entities.find(i => assoc.targets.includes(i.key));
       if (entity) {
         result.push(entity);
       }
@@ -419,63 +465,39 @@ export class DataEntity {
    * @yields The path containing keys of entities from this entity to the `toEntity` (inclusive) and all entities in between.
    */
   * associationPath(toEntity: string): Generator<string[]> {
-    const graph = this._associationGraph();
-    for (const path of this._associationPath(this.key, toEntity, graph)) {
+    const graph = this.root.associationGraph();
+    for (const path of this.root.associationPath(this.key, toEntity, graph)) {
       yield path;
     }
   }
 
   /**
-   * The actual implementation of the graph search.
+   * Returns a list of entities that are association with this entity through an association
+   * that the target property points to this entity.
    * 
-   * @param from The current from node
-   * @param to The target node
-   * @param g The graph
-   * @param path The current list of entity ids.
-   * @param visited The list of visited paths to avoid cycles
-   */
-  protected * _associationPath(from: string, to: string, g: Record<string, string[]>, path: string[] = [], visited: Set<string> = new Set()): Generator<string[]> {
-    if (from === to) {
-      yield path.concat(to);
-      return;
-    }
-    if (visited.has(from)) {
-      // it's a cycle
-      return;
-    }
-    if (g[from]) {
-      visited.add(from);
-      path.push(from);
+   * In other words, if entity `A` has association target with `B`, then asking `B` for related entities will
+   * result with `[A]`.
+   * 
+   * ```plain
+   * A -> B -> C
+   * D -> C
+   * 
+   * C => [B, D]
+   * ```
+   */
+  getRelatedEntities(): DataEntity[] {
+    const { key, root } = this;
+    const result: DataEntity[] = [];
+    const inverse = root.definitions.associations.filter(i => i.targets.includes(key));
 
-      for (const neighbor of g[from]) {
-        yield *this._associationPath(neighbor, to, g, path, visited);
+    inverse.forEach((assoc) => {
+      const entity = root.definitions.entities.find(e => e.associations.includes(assoc));
+      if (entity) {
+        result.push(entity);
       }
-      
-      visited.delete(from);
-      path.pop();
-    }
-  }
+    });
 
-  /**
-   * @returns The graph of associations where keys are the source entities and the value is the list of all target entities.
-   */
-  protected _associationGraph(): Record<string, string[]> {
-    const graph: Record<string, string[]> = {};
-    const { associations, entities } = this.root.definitions;
-    for (const assoc of associations) {
-      if (!assoc.target) {
-        continue;
-      }
-      const srcEntity = entities.find(i => i.associations.some(a => a === assoc));
-      if (!srcEntity) {
-        continue;
-      }
-      if (!graph[srcEntity.key]) {
-        graph[srcEntity.key] = [];
-      }
-      graph[srcEntity.key].push(assoc.target);
-    }
-    return graph;
+    return result;
   }
 
   /**
@@ -552,4 +574,84 @@ export class DataEntity {
       tags.splice(index, 1);
     }
   }
+
+  /**
+   * Creates a Shape of AMF.
+   * The property itself is auto-generated. If the `schema` is defined then it is used
+   * as the `range` of the property. Otherwise basic shape is generated for the range.
+   * 
+   * This is a preferred way of reading the AMF shape as this synchronizes changed 
+   * data properties with the shape definition.
+   * 
+   * @returns AMF property shape definition.
+   */
+  toApiShape(): IShapeUnion {
+    const serializer = new AmfShapeGenerator();
+    return serializer.entity(this);
+  }
+
+  /**
+   * Reads the schema of the Entity and generates an example for it.
+   */
+  toExample(mime: string): string | number | boolean | null | undefined {
+    const shape = this.toApiShape();
+    const generator = new ApiSchemaGenerator(mime, {
+      renderExamples: true,
+      renderMocked: true,
+      renderOptional: true,      
+    });
+    return generator.generate(shape);
+  }
+
+  /**
+   * @returns The adapted entity, if any
+   */
+  readAdapted(): DataEntity | undefined {
+    const { adapts } = this;
+    if (!adapts) {
+      return undefined;
+    }
+    return this.root.definitions.entities.find(i => i.key === adapts);
+  }
+
+  /**
+   * Creates new adapted entity and associates it with this entity.
+   * @returns The instance of the created entity.
+   */
+  createAdapted(): DataEntity {
+    const entity = new DataEntity(this.root);
+    // disallow defaults as this would influence the schema generation
+    entity.info.name = undefined;
+    this.root.definitions.entities.push(entity);
+    this.adapts = entity.key;
+    return entity;
+  }
+
+  /**
+   * Checks whether the `target` creates a cycle in the graph (whether this creates a recursive association).
+   * @param target 
+   */
+  hasForwardCycle(target: string, g = this.root.associationGraph(), key = this.key): boolean {
+    if (target === key) {
+      return true;
+    }
+    const neighbors: string[] = [];
+    Object.keys(g).forEach(prop => {
+      if (g[prop].includes(key)) {
+        neighbors.push(prop);
+      }
+    });
+    if (neighbors.includes(target)) {
+      return true;
+    }
+    for (const neighbor of neighbors) {
+      if (neighbor === key) {
+        return true;
+      }
+      if (this.hasForwardCycle(target, g, neighbor)) {
+        return true;
+      }
+    }
+    return false;
+  }
 }

package/src/models/data/DataFile.ts

@@ -9,6 +9,9 @@ export interface IDataFile extends IFile {
   kind: typeof Kind;
 }
 
+/**
+ * Used by the store. A file definition for the DataNamespace
+ */
 export class DataFile extends File {
   kind = Kind;
 

package/src/models/data/DataModel.ts

@@ -59,7 +59,7 @@ export class DataModel {
    * @param root the root namespace.
    * @param input The data model definition to restore.
    */
-  constructor(protected root: DataNamespace, input?: string | IDataModel) {
+  constructor(public root: DataNamespace, input?: string | IDataModel) {
     let init: IDataModel;
     if (typeof input === 'string') {
       init = JSON.parse(input);

package/src/models/data/DataNamespace.ts

@@ -534,4 +534,58 @@ export class DataNamespace extends DataNamespaceParent {
       model.remove();
     }
   }
+
+  /**
+   * @returns The graph of associations where keys are the source entities and the value is the list of all target entities.
+   */
+  associationGraph(): Record<string, string[]> {
+    const graph: Record<string, string[]> = {};
+    const { definitions } = this.root || this;
+    const { associations, entities } = definitions;
+    for (const assoc of associations) {
+      if (!assoc.targets.length) {
+        continue;
+      }
+      const srcEntity = entities.find(i => i.associations.some(a => a === assoc));
+      if (!srcEntity) {
+        continue;
+      }
+      if (!graph[srcEntity.key]) {
+        graph[srcEntity.key] = [];
+      }
+      graph[srcEntity.key].splice(0, 0, ...assoc.targets);
+    }
+    return graph;
+  }
+
+  /**
+   * Prints out all associations from one entity to another through all entities that may be in between.
+   * 
+   * @param from The key of the from entity
+   * @param to The key of the target entity
+   * @param g The graph generated with `associationGraph()`
+   * @param path The current list of entity ids. Do not set this, it is for the recursive processing of the graph.
+   * @param visited The list of visited paths to avoid cycles. Do not set this, it is for the recursive processing of the graph.
+   */
+  * associationPath(from: string, to: string, g: Record<string, string[]>, path: string[] = [], visited: Set<string> = new Set()): Generator<string[]> {
+    if (from === to) {
+      yield path.concat(to);
+      return;
+    }
+    if (visited.has(from)) {
+      // it's a cycle
+      return;
+    }
+    if (g[from]) {
+      visited.add(from);
+      path.push(from);
+
+      for (const neighbor of g[from]) {
+        yield *this.associationPath(neighbor, to, g, path, visited);
+      }
+      
+      visited.delete(from);
+      path.pop();
+    }
+  }
 }