@api-client/core 0.6.13 → 0.6.16

package/src/models/Thing.ts

@@ -12,6 +12,11 @@ export declare interface IThing {
    * The name of the thing.
    */
   name?: string;
+  /**
+   * Optional value to overwrite the `name` in the UI.
+   * The primary descriptive field is the `name`. The display name is only used in the presentation of the data.
+   */
+  displayName?: string;
   /**
    * The description of the thing.
    */
@@ -28,6 +33,11 @@ export class Thing {
    * The name of the thing.
    */
   name?: string;
+  /**
+   * Optional value to overwrite the `name` in the UI.
+   * The primary descriptive field is the `name`. The display name is only used in the presentation of the data.
+   */
+  displayName?: string;
   /**
    * The description of the thing.
    */
@@ -37,6 +47,16 @@ export class Thing {
    */
   version?: string;
 
+  /**
+   * Returns one in this order:
+   * - displayName
+   * - name
+   * - 'Unnamed object'
+   */
+  get renderLabel(): string {
+    return this.displayName || this.name || 'Unnamed object';
+  }
+
   /**
    * Creates a basic description from a name.
    */
@@ -74,9 +94,10 @@ export class Thing {
     if (!Thing.isThing(init)) {
       throw new Error(`Not a thing.`);
     }
-    const { description, name, version } = init;
+    const { description, name, version, displayName } = init;
     this.kind = Kind;
     this.name = name;
+    this.displayName = displayName;
     this.description = description;
     this.version = version;
   }
@@ -99,6 +120,9 @@ export class Thing {
     if (typeof this.name === 'string') {
       result.name = this.name;
     }
+    if (typeof this.displayName === 'string') {
+      result.displayName = this.displayName;
+    }
     if (this.description) {
       result.description = this.description;
     }

package/src/models/data/Bindings.ts

@@ -0,0 +1,186 @@
+/* eslint-disable import/export */
+import { IXmlSerializer } from "../../amf/definitions/Shapes.js";
+
+/**
+ * A general schema definition for a property. This is propagated to all bindings (when they support these properties).
+ */
+export interface IPropertySchema {
+  /**
+   * The enum values for the property.
+   * They are always encoded as strings. The actual type is defined in the `dataType` property.
+   */
+  enum?: string[];
+  /**
+   * The default value for the property.
+   * This is always encoded as a string. The actual type is defined in the `dataType` property.
+   */
+  defaultValue?: string;
+  /**
+   * The example values for the property.
+   * They are always encoded as strings. The actual type is defined in the `dataType` property.
+   */
+  examples?: string[];
+}
+
+/**
+ * Binding for web API schema types (RAML, OAS)
+ * 
+ * Data type translation (type to dataType)
+ * 
+ * - `string` -> `string` with appropriate format
+ * - `number` -> `number` data type with format `float`, `double`, or none format for OAS
+ * - `integer` -> `integer` data type with `int32`, `int64`, or none format for OAS
+ * - `nil` -> `nullable` property on OAS or `nil` type in RAML
+ * - `boolean` -> `boolean` (both the same)
+ * - `date` -> 
+ * - `any` -> `any` in RAML, `{}` shorthand in OAS
+ * 
+ * 
+ * 
+ * The `binary` type
+ * 
+ * OAS
+ * 
+ * `http://www.w3.org/2001/XMLSchema#byte` For a file
+ * `http://www.w3.org/2001/XMLSchema#base64Binary` for base 64
+ * 
+ * RAML
+ * 
+ * Has it's own AMF shape: FileShape.
+ * 
+ * The `data` type
+ * 
+ * OAS
+ * 
+ * `http://www.w3.org/2001/XMLSchema#date` for a `date`
+ * `http://www.w3.org/2001/XMLSchema#dateTime` for a `datetime` and `time`. 
+ * Note, OAS has no concept of `time` do we add `time` as the `format which is a custom thing.
+ * 
+ * RAML
+ * 
+ * `http://www.w3.org/2001/XMLSchema#date` for a `date` (raml's date-only)
+ * `http://a.ml/vocabularies/shapes#dateTimeOnly` for a `time` (raml's time-only)
+ * `http://www.w3.org/2001/XMLSchema#dateTime` for a `datetime` (raml's datetime) + format
+ * 
+ * Note, we won't support RAML's `datetime-only`.
+ */
+export interface IPropertyWebBindings {
+  /**
+   * When set it overrides the `name` of the property.
+   */
+  name?: string;
+  /**
+   * The data type of the property consistent with AMF's data types.
+   */
+  dataType?: string;
+  /**
+   * The XML encoding instructions.
+   */
+  xml?: IXmlSerializer;
+  /**
+   * Only valid for the `file` property type.
+   * The list of file mime types.
+   */
+  fileTypes?: string[];
+  /**
+   * The patter to use wit a string scalar
+   */
+  pattern?: string;
+  /**
+   * Minimum length of a string scalar or a file type.
+   */
+  minLength?: number;
+  /**
+   * Maximum length of a string scalar or a file type.
+   */
+  maxLength?: number;
+  /**
+   * Minimum value for a number scalar.
+   */
+  minimum?: number;
+  /**
+   * Maximum value for a number scalar.
+   */
+  maximum?: number;
+  /**
+   * The multiplier value for a number scalar.
+   */
+  multipleOf?: number;
+  /**
+   * When `false`: value ≥ minimum.
+   * When `true`: value > minimum.
+   */
+  exclusiveMinimum?: boolean;
+  /**
+   * When `false`: value ≤ maximum.
+   * When `true`: value < minimum.
+   */
+  exclusiveMaximum?: boolean;
+
+  format?:
+  //
+  // OAS 3 formats
+  //
+
+  // numbers
+  'float' | 'double' | 'int32' | 'int64' |
+  // string
+  'date' | 'date-time' | 'password' |
+  // files
+  'binary' | 'byte' |
+  // non-standard
+  'email' | 'uuid' | 'uri' | 'hostname' | 'ipv4' | 'ipv6' | string |
+
+  // 
+  // RAML formats
+  // 
+
+  'rfc3339' | 'rfc2616'
+}
+
+
+/**
+ * Binding to the protocol buffer.
+ * 
+ * Data type translation (type to dataType)
+ * 
+ * - `string` -> `string`
+ * - `number` -> `double`, `float`
+ * - `integer` -> `int32`, `int64`, `uint32`, `uint64`, `sint32`, `sint64`, `fixed32`, `fixed64`, `sfixed32`, `sfixed64`
+ * - `nil` -> No translation.
+ * - `boolean` -> `boolean`
+ * - `date` -> No translation, we allow string or number (date string or a timestamp with a combination with format but this is not standard for ProtoBuf)
+ * - `any` -> No translation, the user has to pick any of the data formats.
+ * - `binary` -> `bytes`
+ */
+export interface IPropertyProtobufBindings {
+  /**
+   * The field number in a protocol buffer message
+   */
+  field?: number;
+  /**
+   * Whether this property (field) is reserved
+   */
+  reserved?: boolean;
+  /**
+   * The data type of the property consistent with AMF's data types.
+   */
+  dataType?: string;
+}
+
+export interface IPropertyBindings {
+  /**
+   * The type of the bindings
+   * 
+   * - Protocol buffers: `protobuf`
+   * - RAML or OAS - `web`
+   */
+  type: 'protobuf' | 'web';
+  /**
+   * The definition of the bindings.
+   * The bindings tells how to translated the DataProperty to a specific format.
+   * For example, it allows to define the `dataType` and `format` for RAML / OAS (via the AMF shapes)
+   * or the field number for protocol buffer.
+   */
+  schema: IPropertyProtobufBindings | IPropertyWebBindings;
+}

package/src/models/data/DataAssociation.ts

@@ -1,15 +1,27 @@
+import { Core as JsonCore } from '@api-client/json';
+import { AmfShapeGenerator } from '../../amf/AmfShapeGenerator.js';
+import { IAssociationShape, IPropertyShape } from '../../amf/definitions/Shapes.js';
 import v4 from '../../lib/uuid.js';
 import { IThing, Thing } from "../Thing.js";
-import { IDataAssociationSchema } from './DataAssociationSchema.js';
-import { DataEntity } from './DataEntity.js';
+import { DataEntity, IDataEntity } from './DataEntity.js';
 import { DataNamespace } from './DataNamespace.js';
 
 export const Kind = 'Core#DataAssociation';
 
+/**
+ * Describes an association between entities. An association is another property of an entity. The `name` is the name of the
+ * property and the value is the associated target or targets.
+ * 
+ * An association can have multiple targets to allow describing the model as `allOf`, `anyOf` and `oneOf` schemas.
+ * When the association has only one target, then generated schema cannot have union types.
+ * 
+ * Depending on the schema translation an association can be embedded as a sub-object in the generated schema
+ * or can be references via a primary key.
+ */
 export interface IDataAssociation {
   kind: typeof Kind;
   /**
-   * The key of the namespace.
+   * The key of the association.
    */
   key: string;
   /**
@@ -25,23 +37,54 @@ export interface IDataAssociation {
    */
   multiple?: boolean;
   /**
-   * The target entity of this association.
+   * 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;
+  /**
+   * The list of keys associated with the entity through this association.
    * An association without a target is considered invalid and discarded when processing the values.
    */
-  target?: string;
+  targets?: string[];
   /**
    * The schema allowing to translate the model into a specific format (like JSON, RAML, XML, etc.)
+   * 
+   * When this is defined then it is used as the schema. When this is not defined it uses 
+   * referenced entities schemas. Note, changes in the referenced entities may not be propagated
+   * to schemas altered by the user.
+   * 
+   * Note, schema can only occur on an adapted property. Has no effect on the "main"
+   * property.
+   */
+  schema?: IAssociationShape;
+  /**
+   * The key of the association that is adapted by this association.
+   * Adapted associations can manipulate the shape of the schema for the association.
+   * 
+   * Each value defined on the adapted association changes the original value defined on
+   * the association.
    */
-  schema?: IDataAssociationSchema;
+  adapts?: string;
 }
 
+/**
+ * Describes an association between entities. An association is another property of an entity. The `name` is the name of the
+ * property and the value is the associated target or targets.
+ * 
+ * An association can have multiple targets to allow describing the model as `allOf`, `anyOf` and `oneOf` schemas.
+ * When the association has only one target, then generated schema cannot have union types.
+ * 
+ * Depending on the schema translation an association can be embedded as a sub-object in the generated schema
+ * or can be references via a primary key.
+ */
 export class DataAssociation {
   kind = Kind;
 
   key = '';
 
   /**
-   * The description of the data namespace.
+   * The description of the data association.
    */
   info: Thing = Thing.fromName('');
 
@@ -56,25 +99,65 @@ export class DataAssociation {
   multiple?: boolean;
 
   /**
-   * The target entity of this association.
+   * 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;
+
+  /**
+   * The list of keys associated with the entity through this association.
    * An association without a target is considered invalid and discarded when processing the values.
    */
-  target?: string;
+  targets: string[] = [];
 
   /**
    * The schema allowing to translate the model into a specific format (like JSON, RAML, XML, etc.)
    * 
-   * Implementation note, when an entity is removed this property is not changed. The target can't 
-   * be read but it can be tracked to a deleted entity.
+   * When this is defined then it is used as the schema. When this is not defined it uses 
+   * referenced entities schemas. Note, changes in the referenced entities may not be propagated
+   * to schemas altered by the user.
+   * 
+   * Note, schema can only occur on an adapted property. Has no effect on the "main"
+   * property.
+   */
+  schema?: IAssociationShape;
+
+  /**
+   * The key of the association that is adapted by this association.
+   * Adapted associations can manipulate the shape of the schema for the association.
+   * 
+   * Each value defined on the adapted association changes the original value defined on
+   * the association.
    */
-  schema?: IDataAssociationSchema;
+  adapts?: string;
 
+  /**
+   * Returns true when the association has 0 or 1 targets.
+   */
+  get isSingle(): boolean {
+    return this.targets.length < 2;
+  }
+
+  /**
+   * Creates an instance of DataAssociation from a target entity key.
+   * Note, this entity will have no name. The default name is used instead.
+   * 
+   * @param root The namespace root.
+   * @param target The target entity key.
+   */
   static fromTarget(root: DataNamespace, target: string): DataAssociation {
     const assoc = new DataAssociation(root);
-    assoc.target = target;
+    assoc.targets = [target];
     return assoc;
   }
 
+  /**
+   * Creates an instance of DataAssociation from a name, without defining a target.
+   * 
+   * @param root The namespace root.
+   * @param name The name of the association.
+   */
   static fromName(root: DataNamespace, name: string): DataAssociation {
     const assoc = new DataAssociation(root);
     assoc.info = Thing.fromName(name);
@@ -84,7 +167,7 @@ export class DataAssociation {
   /**
    * @param input The data association definition to restore.
    */
-  constructor(protected root: DataNamespace, input?: string | IDataAssociation) {
+  constructor(public root: DataNamespace, input?: string | IDataAssociation) {
     let init: IDataAssociation;
     if (typeof input === 'string') {
       init = JSON.parse(input);
@@ -94,7 +177,7 @@ export class DataAssociation {
       init = {
         kind: Kind,
         key: v4(),
-        info: Thing.fromName('').toJSON(),
+        info: Thing.fromName('Unnamed association').toJSON(),
       };
     }
     this.new(init);
@@ -104,7 +187,10 @@ export class DataAssociation {
     if (!DataAssociation.isDataAssociation(init)) {
       throw new Error(`Not a data association.`);
     }
-    const { info, key = v4(), kind = Kind, schema, multiple, required, target } = init;
+    const { 
+      info, key = v4(), kind = Kind, schema, multiple, required, targets,
+      adapts, hidden,
+    } = init;
     this.kind = kind;
     this.key = key;
     if (info) {
@@ -113,7 +199,7 @@ export class DataAssociation {
       this.info = Thing.fromName('');
     }
     if (schema) {
-      this.schema = { ...schema };
+      this.schema = JsonCore.clone(schema);
     } else {
       this.schema = undefined;
     }
@@ -127,10 +213,20 @@ export class DataAssociation {
     } else {
       this.required = undefined;
     }
-    if (typeof target === 'string') {
-      this.target = target;
+    if (Array.isArray(targets)) {
+      this.targets = [...targets];
     } else {
-      this.target = undefined;
+      this.targets = [];
+    }
+    if (typeof hidden === 'boolean') {
+      this.hidden = hidden;
+    } else {
+      this.hidden = undefined;
+    }
+    if (typeof adapts === 'string') {
+      this.adapts = adapts;
+    } else {
+      this.adapts = undefined;
     }
   }
 
@@ -149,7 +245,7 @@ export class DataAssociation {
       info: this.info.toJSON(),
     };
     if (this.schema) {
-      result.schema = { ...this.schema };
+      result.schema = JsonCore.clone(this.schema);
     }
     if (typeof this.multiple === 'boolean') {
       result.multiple = this.multiple;
@@ -157,18 +253,24 @@ export class DataAssociation {
     if (typeof this.required === 'boolean') {
       result.required = this.required;
     }
-    if (typeof this.target === 'string') {
-      result.target = this.target;
+    if (Array.isArray(this.targets) && this.targets.length) {
+      result.targets = [...this.targets];
+    }
+    if (typeof this.hidden === 'boolean') {
+      result.hidden = this.hidden;
+    }
+    if (this.adapts) {
+      result.adapts = this.adapts;
     }
     return result;
   }
 
-  getTarget(): DataEntity | undefined {
-    const { root, target } = this;
-    if (!target) {
-      return undefined;
-    }
-    return root.definitions.entities.find(i => i.key === target);
+  /**
+   * @returns The list of DataEntity definitions for the current targets.
+   */
+  getTargets(): DataEntity[] {
+    const { root, targets } = this;
+    return root.definitions.entities.filter(item => targets.some(i => i === item.key));
   }
 
   /**
@@ -186,4 +288,99 @@ export class DataAssociation {
       this.root.definitions.associations.splice(defIndex, 1);
     }
   }
+  
+  /**
+   * Adds a target to the targets list from an entity.
+   * @param entity The instance or schema of an entity.
+   */
+  addTarget(entity: DataEntity | IDataEntity): void;
+
+  /**
+   * Adds the target to the targets list with an entity key..
+   * @param key The key of the entity to add.
+   */
+  addTarget(key: string): void;
+
+  /**
+   * @param init The key of an entity, its instance, or schema.
+   */
+  addTarget(init: string | DataEntity | IDataEntity): void {
+    if (typeof init === 'string') {
+      this.targets.push(init);
+    } else {
+      const { key } = init;
+      this.targets.push(key);
+    }
+  }
+
+  /**
+   * Removes a target entity from the targets list.
+   * 
+   * @param entity The instance or schema of the entity to remove.
+   */
+  removeTarget(entity: DataEntity | IDataEntity): void;
+
+  /**
+   * Removes a target entity from the targets list.
+   * 
+   * @param key The key of the target entity to remove.
+   */
+  removeTarget(key: string): void;
+
+  /**
+   * Removes a target entity from the targets list.
+   * 
+   * @param init The key of an entity, its instance, or schema.
+   */
+  removeTarget(init: string | DataEntity | IDataEntity): void {
+    let key: string;
+    if (typeof init === 'string') {
+      key = init;
+    } else {
+      key = init.key;
+    }
+    const index = this.targets.indexOf(key);
+    if (index >= 0) {
+      this.targets.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.associationProperty(this);
+  }
+
+  /**
+   * @returns The adapted association, if any
+   */
+  readAdapted(): DataAssociation | undefined {
+    const { adapts } = this;
+    if (!adapts) {
+      return undefined;
+    }
+    return this.root.definitions.associations.find(i => i.key === adapts);
+  }
+
+  /**
+   * Creates new adapted association and associates it with this association.
+   * @returns The instance of the created association.
+   */
+  createAdapted(): DataAssociation {
+    const association = new DataAssociation(this.root);
+    // disallow defaults as this would influence the schema generation
+    association.info.name = undefined;
+    this.root.definitions.associations.push(association);
+    this.adapts = association.key;
+    return association;
+  }
 }

package/src/models/data/DataAssociationSchema.ts

@@ -29,4 +29,42 @@ export interface IDataAssociationSchema {
    * ```
    */
   embedded?: boolean;
+
+  /**
+   * Describes XML specific serialization.
+   */
+  xml?: {
+    /**
+     * The name of the attribute or a wrapped property to use when serializing the property.
+     * 
+     * ```
+     * <Person fullName="John Doe"></Person>
+     * ```
+     */
+    name?: string;
+
+    /**
+     * When the property is an array (has the `multiple` set to true)
+     * then it tells that the list of values should be wrapped with a parent
+     * element:
+     * 
+     * ```
+     * <Person>
+     *  <Person fullName="John Doe"></Person>
+     * </Person>
+     * ```
+     * 
+     * Use this with the combination with `name` to describe the name of the wrapped
+     * element
+     * 
+     * ```
+     * <people>
+     *  <Person fullName="John Doe"></Person>
+     * </people>
+     * ```
+     * 
+     * Note, this is mutually exclusive with `attribute`.
+     */
+    wrapped?: boolean;
+  }
 }