@api-client/core 0.6.13 → 0.6.16

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';
 
@@ -55,6 +58,29 @@ export interface IDataEntity {
    * with inconsistent definition of a schema because the last read property wins.
    */
   parents?: string[];
+
+  /**
+   * 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;
 }
 
 /**
@@ -104,6 +130,20 @@ export class DataEntity {
    */
   parents: string[] = [];
 
+  /**
+   * Whether this entity is deprecated.
+   */
+  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);
@@ -113,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);
@@ -133,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 } = init;
+    const { 
+      info, key = v4(), kind = Kind, tags, taxonomy, parents, properties, associations, 
+      deprecated, adapts,
+    } = init;
     this.kind = kind;
     this.key = key;
     if (info) {
@@ -141,7 +184,6 @@ export class DataEntity {
     } else {
       this.info = Thing.fromName('');
     }
-    
     if (Array.isArray(tags)) {
       this.tags = [...tags];
     } else {
@@ -157,7 +199,6 @@ export class DataEntity {
     } else {
       this.parents = [];
     }
-
     this.properties = [];
     if (Array.isArray(properties)) {
       properties.forEach(key => {
@@ -167,7 +208,6 @@ export class DataEntity {
         }
       });
     }
-
     this.associations = [];
     if (Array.isArray(associations)) {
       associations.forEach(key => {
@@ -177,6 +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 {
@@ -208,6 +258,12 @@ export class DataEntity {
     if (Array.isArray(this.associations) && this.associations.length) {
       result.associations = this.associations.map(i => i.key);
     }
+    if (typeof this.deprecated === 'boolean') {
+      result.deprecated = this.deprecated;
+    }
+    if (this.adapts) {
+      result.adapts = this.adapts;
+    }
     return result;
   }
 
@@ -224,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;
@@ -276,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;
@@ -302,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;
@@ -333,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);
       }
@@ -444,7 +509,7 @@ export class DataEntity {
     const graph: Record<string, string[]> = {};
     const { associations, entities } = this.root.definitions;
     for (const assoc of associations) {
-      if (!assoc.target) {
+      if (!assoc.targets.length) {
         continue;
       }
       const srcEntity = entities.find(i => i.associations.some(a => a === assoc));
@@ -454,7 +519,7 @@ export class DataEntity {
       if (!graph[srcEntity.key]) {
         graph[srcEntity.key] = [];
       }
-      graph[srcEntity.key].push(assoc.target);
+      graph[srcEntity.key].splice(0, 0, ...assoc.targets);
     }
     return graph;
   }
@@ -493,4 +558,96 @@ export class DataEntity {
     });
     return result.reverse();
   }
+
+  /**
+   * Adds a new tag to the property. It also populates the root namespace's tags when tag is new.
+   * 
+   * Note, it does nothing when the tag is already defined.
+   * 
+   * @param tag The tag to add.
+   */
+  addTag(tag: string): void {
+    if (!tag) {
+      return;
+    }
+    const lower = tag.toLowerCase();
+    const { tags } = this;
+    if (tags.some(t => t.toLowerCase() === lower)) {
+      return;
+    }
+    tags.push(tag);
+    const { definitions } = this.root;
+    if (!definitions.tags.some(t => t.toLowerCase() === lower)) {
+      definitions.tags.push(tag);
+    }
+  }
+
+  /**
+   * Removes a tag from the property. Unlike the `addTag()` this won't remove a `tag` from the root namespace.
+   * 
+   * @param tag The tag to remove.
+   */
+  removeTag(tag: string): void {
+    if (!tag) {
+      return;
+    }
+    const lower = tag.toLowerCase();
+    const { tags } = this;
+    const index = tags.findIndex(t => t.toLowerCase() === lower);
+    if (index >= 0) {
+      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;
+  }
 }

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

@@ -14,6 +14,7 @@ interface IDataDefinitions {
   properties?: IDataProperty[];
   associations?: IDataAssociation[];
   namespaces?: IDataNamespace[];
+  tags?: string[];
 }
 
 interface DataDefinitions {
@@ -22,6 +23,11 @@ interface DataDefinitions {
   properties: DataProperty[];
   associations: DataAssociation[];
   namespaces: DataNamespace[];
+  /**
+   * Common for the entire root namespace tags.
+   * These are kept separately so the UI can generate autocomplete for tags.
+   */
+  tags: string[];
 }
 
 interface IDataNamespaceParent {
@@ -289,6 +295,7 @@ export class DataNamespace extends DataNamespaceParent {
       entities: [],
       properties: [],
       namespaces: [],
+      tags: [],
     };
   }
 
@@ -359,6 +366,11 @@ export class DataNamespace extends DataNamespaceParent {
     } else {
       this.definitions.namespaces = [];
     }
+    if (Array.isArray(definitions.tags)) {
+      this.definitions.tags = [...definitions.tags];
+    } else {
+      this.definitions.tags = [];
+    }
   }
 
   toJSON(): IDataNamespace {
@@ -369,7 +381,7 @@ export class DataNamespace extends DataNamespaceParent {
       items: this.items.map(i => i.toJSON()),
       definitions: {},
     };
-    const { associations, entities, models, namespaces, properties } = this.definitions;
+    const { associations, entities, models, namespaces, properties, tags } = this.definitions;
     if (Array.isArray(associations) && associations.length) {
       result.definitions.associations = associations.map(i => i.toJSON());
     }
@@ -385,6 +397,9 @@ export class DataNamespace extends DataNamespaceParent {
     if (Array.isArray(properties) && properties.length) {
       result.definitions.properties = properties.map(i => i.toJSON());
     }
+    if (Array.isArray(tags) && tags.length) {
+      result.definitions.tags = [...tags];
+    }
     return result;
   }