@api-client/core 0.6.13 → 0.6.16

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,25 @@ 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.
+   */
+  deprecated?: boolean;
   /**
    * Optional general purpose tags for the UI.
    */
@@ -90,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 {
@@ -132,8 +158,32 @@ 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.
+   */
+  deprecated?: boolean;
+
   /**
    * Optional general purpose tags for the UI.
+   * 
+   * Note to implementations, use the `addTag()` method as it propagates the "tag" value in the namespace.
    */
   tags: string[] = [];
 
@@ -154,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];
@@ -182,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);
@@ -203,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 } = 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;
@@ -227,11 +297,36 @@ export class DataProperty {
     } else {
       this.index = undefined;
     }
+    if (typeof deprecated === 'boolean') {
+      this.deprecated = deprecated;
+    } else {
+      this.deprecated = undefined;
+    }
     if (typeof primary === 'boolean') {
       this.primary = primary;
     } 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 {
@@ -242,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 = [];
     }
   }
 
@@ -267,6 +367,9 @@ export class DataProperty {
     if (typeof this.index === 'boolean') {
       result.index = this.index;
     }
+    if (typeof this.deprecated === 'boolean') {
+      result.deprecated = this.deprecated;
+    }
     if (typeof this.primary === 'boolean') {
       result.primary = this.primary;
     }
@@ -276,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;
   }
@@ -292,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);
@@ -302,5 +420,90 @@ 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);
+      }
+    }
+  }
+
+  /**
+   * 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 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;
   }
 }

package/build/src/models/data/DataPropertySchema.d.ts

@@ -1,125 +0,0 @@
-export declare type NumberFormat = 'integer' | 'float' | 'long' | 'double' | 'int32' | 'int64' | 'uint32' | 'uint64' | 'sint32' | 'sint64' | 'fixed32' | 'fixed64' | 'sfixed32' | 'sfixed64';
-export declare const NumberFormats: NumberFormat[];
-export declare enum NumberFormatList {
-    integer = "integer",
-    float = "float",
-    int32 = "int32",
-    int64 = "int64",
-    uint32 = "uint32",
-    uint64 = "uint64",
-    sint32 = "sint32",
-    sint64 = "sint64",
-    fixed32 = "fixed32",
-    fixed64 = "fixed64",
-    sfixed32 = "sfixed32",
-    sfixed64 = "sfixed64",
-    double = "double"
-}
-export declare type DateFormat = 'rfc3339' | 'rfc2616';
-export declare const DateFormats: DateFormat[];
-export declare enum DateFormatList {
-    /**
-     * The "date-time" notation of RFC3339
-     */
-    rfc3339 = "rfc3339",
-    /**
-     * The format defined in RFC2616.
-     */
-    rfc2616 = "rfc2616"
-}
-/**
- * The difference between the DataProperty and this is that the `DataProperty` describes the general shape of
- * the data and `IDataPropertySchema` describes how this property is translated into a specific format
- * (like JSON, Protocol Buffer, XML, etc)
- */
-export interface IDataPropertySchema<T> {
-    /**
-     * The default value for the property.
-     */
-    default?: T;
-    /**
-     * Enum values for the property.
-     */
-    enum?: T[];
-    /**
-     * The example value for the property.
-     */
-    examples?: T[];
-    /**
-     * The format of a `number` or `datetime` type.
-     */
-    format?: NumberFormat | DateFormat;
-    /**
-     * Minimum length of the string or a file. Value MUST be equal to or greater than 0.
-     */
-    minLength?: number;
-    /**
-     * The minimum length of the string or a file. Value MUST be equal to or greater than 0.
-     */
-    maxLength?: number;
-    /**
-     * Regular expression that this string MUST match.
-     */
-    pattern?: string;
-    /**
-     * The minimum value.
-     */
-    minimum?: number;
-    /**
-     * The maximum value.
-     */
-    maximum?: number;
-    /**
-     * A numeric instance is valid against "multipleOf" if the result of dividing the instance by this
-     * value is an integer.
-     */
-    multipleOf?: number;
-    /**
-     * A list of valid content-type strings for the file. The file type `*\/*` is a valid value.
-     */
-    fileTypes?: string[];
-    /**
-     * Describes XML specific serialization.
-     */
-    xml?: {
-        /**
-         * Whether is property should be represented as an attribute of the parent entity.
-         *
-         * ```
-         * <Person name="John Doe"></Person>
-         * ```
-         */
-        attribute?: boolean;
-        /**
-         * 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;
-    };
-}

package/build/src/models/data/DataPropertySchema.js

@@ -1,33 +0,0 @@
-export const NumberFormats = [
-    'integer', 'float', 'long', 'double', 'int32', 'int64', 'uint32', 'uint64', 'sint32', 'sint64', 'fixed32', 'fixed64',
-    'sfixed32', 'sfixed64'
-];
-export var NumberFormatList;
-(function (NumberFormatList) {
-    NumberFormatList["integer"] = "integer";
-    NumberFormatList["float"] = "float";
-    NumberFormatList["int32"] = "int32";
-    NumberFormatList["int64"] = "int64";
-    NumberFormatList["uint32"] = "uint32";
-    NumberFormatList["uint64"] = "uint64";
-    NumberFormatList["sint32"] = "sint32";
-    NumberFormatList["sint64"] = "sint64";
-    NumberFormatList["fixed32"] = "fixed32";
-    NumberFormatList["fixed64"] = "fixed64";
-    NumberFormatList["sfixed32"] = "sfixed32";
-    NumberFormatList["sfixed64"] = "sfixed64";
-    NumberFormatList["double"] = "double";
-})(NumberFormatList || (NumberFormatList = {}));
-export const DateFormats = ['rfc3339', 'rfc2616'];
-export var DateFormatList;
-(function (DateFormatList) {
-    /**
-     * The "date-time" notation of RFC3339
-     */
-    DateFormatList["rfc3339"] = "rfc3339";
-    /**
-     * The format defined in RFC2616.
-     */
-    DateFormatList["rfc2616"] = "rfc2616";
-})(DateFormatList || (DateFormatList = {}));
-//# sourceMappingURL=DataPropertySchema.js.map

package/build/src/models/data/DataPropertySchema.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"DataPropertySchema.js","sourceRoot":"","sources":["../../../../src/models/data/DataPropertySchema.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,aAAa,GAAmB;IAC3C,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS;IACpH,UAAU,EAAE,UAAU;CACvB,CAAC;AAEF,MAAM,CAAN,IAAY,gBAcX;AAdD,WAAY,gBAAgB;IAC1B,uCAAmB,CAAA;IACnB,mCAAe,CAAA;IACf,mCAAe,CAAA;IACf,mCAAe,CAAA;IACf,qCAAiB,CAAA;IACjB,qCAAiB,CAAA;IACjB,qCAAiB,CAAA;IACjB,qCAAiB,CAAA;IACjB,uCAAmB,CAAA;IACnB,uCAAmB,CAAA;IACnB,yCAAqB,CAAA;IACrB,yCAAqB,CAAA;IACrB,qCAAiB,CAAA;AACnB,CAAC,EAdW,gBAAgB,KAAhB,gBAAgB,QAc3B;AAGD,MAAM,CAAC,MAAM,WAAW,GAAiB,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;AAChE,MAAM,CAAN,IAAY,cASX;AATD,WAAY,cAAc;IACxB;;OAEG;IACH,qCAAmB,CAAA;IACnB;;OAEG;IACH,qCAAmB,CAAA;AACrB,CAAC,EATW,cAAc,KAAd,cAAc,QASzB"}