@api-client/core 0.6.14 → 0.6.15

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);
       }
@@ -463,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));
@@ -473,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;
   }
@@ -552,4 +598,56 @@ 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;
+  }
 }

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/DataProperty.ts

@@ -1,51 +1,44 @@
+import { Core as JsonCore } from '@api-client/json';
 import { IThing, Thing } from "../Thing.js";
 import v4 from '../../lib/uuid.js';
 import { DataNamespace } from "./DataNamespace.js";
-import { IDataPropertySchema } from "./DataPropertySchema.js";
+import { IPropertyShape } from "../../amf/definitions/Shapes.js";
+import { AmfShapeGenerator } from '../../amf/AmfShapeGenerator.js';
+import { IPropertyBindings, IPropertySchema } from './Bindings.js';
 
-export type DataPropertyType = 'string' | 'number' | 'nil' | 'boolean' | 'date' | 'datetime' |
-  'time' | 'bytes' | 'any' | 'file';
+export type DataPropertyType = 'string' | 'number' | 'integer' | 'nil' | 'boolean' | 'date' | 'datetime' | 'time' | 'any' | 'binary';
 export const DataPropertyTypes: DataPropertyType[] = [
-  'string', 'number', 'nil', 'boolean', 'date', 'datetime', 'time', 'bytes', 'any', 'file'
+  'string', 'number', 'integer', 'nil', 'boolean', 'date', 'datetime', 'time' , 'any', 'binary'
 ];
 
 export enum DataPropertyList {
   string = 'string',
   number = 'number',
+  integer = 'integer', // RAML, OAS and JSON schema define numbers and integers separately
   nil = 'nil',
   boolean = 'boolean',
   date = 'date',
   datetime = 'datetime',
   time = 'time',
-  bytes = 'bytes',
   any = 'any',
-  file = 'file',
+  file = 'binary',
 }
 
-export const Kind = 'Core#DataProperty';
-
-export interface IPropertySchema<T> {
+export type DateFormat = 'rfc3339' | 'rfc2616';
+export const DateFormats: DateFormat[] = ['rfc3339', 'rfc2616'];
+export enum DateFormatList {
   /**
-   * Whether it is a general schema for the property.
-   * All other schemas inherit from this one. This allows creating global schema description 
-   * like examples, default values, minimum value, etc and then use it as a base to generate specific formats.
-   * 
-   * A property may not have a global schema.
+   * The "date-time" notation of RFC3339
    */
-  global?: boolean;
+  rfc3339 = 'rfc3339',
   /**
-   * The mime type this schema describes.
-   * For JSON it is `application/json`, for XML it is `application/xml` (or `text/xml`) adn so on.
-   * 
-   * Note, when this value is missing then it is assumed that the schema is `global`.
+   * The format defined in RFC2616.
    */
-  format?: string;
-  /**
-   * The schema definition.
-   */
-  value: IDataPropertySchema<T>;
+  rfc2616 = 'rfc2616',
 }
 
+export const Kind = 'Core#DataProperty';
+
 export interface IDataProperty {
   kind: typeof Kind;
   /**
@@ -72,6 +65,21 @@ export interface IDataProperty {
    * Whether this property describes an indexed property of the entity.
    */
   index?: boolean;
+  /**
+   * Whether the property is read only in the schema.
+   */
+  readOnly?: boolean;
+  /**
+   * Whether the property is write only in the schema.
+   */
+  writeOnly?: boolean;
+  /**
+   * Whether the attribute is hidden in the schema (not a part of it).
+   * 
+   * The hidden attribute should only appear in the adapted attribute. 
+   * Has no effect when added to the "main" attribute.
+   */
+  hidden?: boolean;
   /**
    * Whether this property is deprecated.
    */
@@ -94,16 +102,30 @@ export interface IDataProperty {
    * a derivative entity for specific schema to describe specific schema case.
    */
   type: DataPropertyType;
-
   /**
-   * While the `DataProperty` describes the general shape of the data and can be used to 
-   * model the structure of the data in the system, a schema describes hwo the data 
-   * should be serialized into a specific format. This allows adding example values,
-   * default values, specifying data format, etc. The assumption here is
-   * that with enough specifics provided by the user (a domain specialist)
-   * we can automatically generate a schema for the given format.
+   * The general schema definition of this property. 
+   * This is propagated to all bindings (when they support these properties).
+   * 
+   * Note, schema can only occur on an adapted property. Has no effect on the "main"
+   * property.
+   */
+  schema?: IPropertySchema;
+  /**
+   * The list of bindings for this property.
+   * 
+   * A binding defines a translation from a data model to a specific format.
+   * For example allows to define properties required to generate AMF shape and therefore RAML/OAS shapes for web APIs
+   * or a protocol buffer schema.
+   */
+  bindings?: IPropertyBindings[];
+  /**
+   * The key of the property that is adapted by this property.
+   * Adapted properties can manipulate the shape of the schema for the property.
+   * 
+   * Each value defined on the adapted property changes the original value defined on
+   * the property.
    */
-  schemas?: IPropertySchema<unknown>[];
+  adapts?: string;
 }
 
 export class DataProperty {
@@ -136,6 +158,23 @@ export class DataProperty {
    */
   index?: boolean;
 
+  /**
+   * Whether the property is read only in the schema.
+   */
+  readOnly?: boolean;
+
+  /**
+   * Whether the property is write only in the schema.
+   */
+  writeOnly?: boolean;
+
+  /**
+   * Whether the attribute is hidden in the schema (not a part of it).
+   * The hidden attribute should only appear in the adapted attribute. 
+   * Has no effect when added to the "main" attribute.
+   */
+  hidden?: boolean;
+
   /**
    * Whether this property is deprecated.
    */
@@ -165,14 +204,30 @@ export class DataProperty {
   type: DataPropertyType = 'string';
 
   /**
-   * While the `DataProperty` describes the general shape of the data and can be used to 
-   * model the structure of the data in the system, a schema describes hwo the data 
-   * should be serialized into a specific format. This allows adding example values,
-   * default values, specifying data format, etc. The assumption here is
-   * that with enough specifics provided by the user (a domain specialist)
-   * we can automatically generate a schema for the given format.
+   * The general schema definition of this property. 
+   * This is propagated to all bindings (when they support these properties).
+   * 
+   * Note, schema can only occur on an adapted property. Has no effect on the "main"
+   * property.
+   */
+  schema?: IPropertySchema;
+  /**
+   * The list of bindings for this property.
+   * 
+   * A binding defines a translation from a data model to a specific format.
+   * For example allows to define properties required to generate AMF shape and therefore RAML/OAS shapes for web APIs
+   * or a protocol buffer schema.
+   */
+  bindings: IPropertyBindings[] = [];
+
+  /**
+   * The key of the property that is adapted by this property.
+   * Adapted properties can manipulate the shape of the schema for the property.
+   * 
+   * Each value defined on the adapted property changes the original value defined on
+   * the property.
    */
-  schemas: IPropertySchema<unknown>[] = [];
+  adapts?: string;
 
   static get supportedTypes(): DataPropertyType[] {
     return [...DataPropertyTypes];
@@ -193,7 +248,7 @@ export class DataProperty {
   /**
    * @param input The data property definition to restore.
    */
-  constructor(protected root: DataNamespace, input?: string | IDataProperty) {
+  constructor(public root: DataNamespace, input?: string | IDataProperty) {
     let init: IDataProperty;
     if (typeof input === 'string') {
       init = JSON.parse(input);
@@ -214,7 +269,11 @@ export class DataProperty {
     if (!DataProperty.isDataProperty(init)) {
       throw new Error(`Not a data property.`);
     }
-    const { info, key = v4(), kind = Kind, multiple, required, type = DataPropertyList.string, index, primary, tags, taxonomy, schemas, deprecated } = init;
+    const { 
+      info, key = v4(), kind = Kind, multiple, required, type = DataPropertyList.string, 
+      index, primary, readOnly, writeOnly, adapts, hidden, tags, taxonomy, deprecated,
+      schema, bindings,
+    } = init;
     this.kind = kind;
     this.key = key;
     this.type = type;
@@ -248,6 +307,26 @@ export class DataProperty {
     } else {
       this.primary = undefined;
     }
+    if (typeof readOnly === 'boolean') {
+      this.readOnly = readOnly;
+    } else {
+      this.readOnly = undefined;
+    }
+    if (typeof writeOnly === 'boolean') {
+      this.writeOnly = writeOnly;
+    } else {
+      this.writeOnly = undefined;
+    }
+    if (typeof hidden === 'boolean') {
+      this.hidden = hidden;
+    } else {
+      this.hidden = undefined;
+    }
+    if (typeof adapts === 'string') {
+      this.adapts = adapts;
+    } else {
+      this.adapts = undefined;
+    }
     if (Array.isArray(tags)) {
       this.tags = [...tags];
     } else {
@@ -258,10 +337,15 @@ export class DataProperty {
     } else {
       this.taxonomy = [];
     }
-    if (Array.isArray(schemas)) {
-      this.schemas = schemas.map(i => ({ ...i }));
+    if (schema) {
+      this.schema = JsonCore.clone(schema);
+    } else {
+      this.schema = undefined;
+    }
+    if (Array.isArray(bindings)) {
+      this.bindings = bindings.map(i => JsonCore.clone(i));
     } else {
-      this.schemas = [];
+      this.bindings = [];
     }
   }
 
@@ -295,14 +379,29 @@ export class DataProperty {
     if (typeof this.required === 'boolean') {
       result.required = this.required;
     }
+    if (typeof this.readOnly === 'boolean') {
+      result.readOnly = this.readOnly;
+    }
+    if (typeof this.writeOnly === 'boolean') {
+      result.writeOnly = this.writeOnly;
+    }
+    if (typeof this.hidden === 'boolean') {
+      result.hidden = this.hidden;
+    }
+    if (this.adapts) {
+      result.adapts = this.adapts;
+    }
     if (Array.isArray(this.tags) && this.tags.length) {
       result.tags = [...this.tags];
     }
     if (Array.isArray(this.taxonomy) && this.taxonomy.length) {
       result.taxonomy = [...this.taxonomy];
     }
-    if (Array.isArray(this.schemas) && this.schemas.length) {
-      result.schemas = this.schemas.map(i => ({ ...i }));
+    if (this.schema) {
+      result.schema = JsonCore.clone(this.schema);
+    }
+    if (Array.isArray(this.bindings) && this.bindings.length) {
+      result.taxonomy = this.taxonomy.map(i => JsonCore.clone(i));
     }
     return result;
   }
@@ -311,7 +410,7 @@ export class DataProperty {
    * Removes self from the parent entity and the namespace definition.
    */
   remove(): void {
-    const { root } = this;
+    const { root, adapts } = this;
     const entity = root.definitions.entities.find(i => i.properties.some(j => j === this));
     if (entity) {
       const assocIndex = entity.properties.findIndex(i => i === this);
@@ -321,6 +420,12 @@ export class DataProperty {
     if (defIndex >= 0) {
       this.root.definitions.properties.splice(defIndex, 1);
     }
+    if (adapts) {
+      const adaptsIndex = this.root.definitions.properties.findIndex(i => i.key === adapts);
+      if (adaptsIndex >= 0) {
+        this.root.definitions.properties.splice(adaptsIndex, 1);
+      }
+    }
   }
 
   /**
@@ -362,4 +467,43 @@ export class DataProperty {
       tags.splice(index, 1);
     }
   }
+
+  /**
+   * Creates a Property 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(): IPropertyShape {
+    const serializer = new AmfShapeGenerator();
+    return serializer.property(this);
+  }
+
+  /**
+   * @returns The adapted property, if any
+   */
+  readAdapted(): DataProperty | undefined {
+    const { adapts } = this;
+    if (!adapts) {
+      return undefined;
+    }
+    return this.root.definitions.properties.find(i => i.key === adapts);
+  }
+
+  /**
+   * Creates new adapted property and associates it with this property.
+   * @returns The instance of the created property.
+   */
+  createAdapted(): DataProperty {
+    const property = new DataProperty(this.root);
+    // disallow defaults as this would influence the schema generation
+    property.info.name = undefined;
+    this.root.definitions.properties.push(property);
+    this.adapts = property.key;
+    return property;
+  }
 }