@api-client/core 0.6.13 → 0.6.16

package/src/amf/definitions/Shapes.ts

@@ -0,0 +1,414 @@
+import { AnyTypes, ArrayTypes, FileTypes, NodeTypes, PropertyTypes, RecursiveTypes, ScalarTypes, TupleTypes, UnionTypes, XmlSerializationTypes } from '../AmfTypes.js';
+import { ApiDocumentation, ApiDocumentSourceMaps } from './Api.js';
+import { IDomainProperty } from './Base.js';
+
+export type IShapeUnion = IScalarShape | INodeShape | IUnionShape | IFileShape | ISchemaShape | IAnyShape | IArrayShape | ITupleShape | IRecursiveShape;
+
+export interface IAssociationShape {
+  /**
+   * This is custom property not available in AMF and used with data associations.
+   * 
+   * Whether the target entity should be embedded under the property name.
+   * When false, this association is just an information that one entity depend on another.
+   * When true, it changes the definition of the schema having this association to 
+   * add the target schema properties inline with this property.
+   * 
+   * **When true**
+   * 
+   * ```javascript
+   * // generated schema for `address` association
+   * {
+   *  "name": "example value",
+   *  "address": {
+   *    "city": "example value",
+   *    ...
+   *  }
+   * }
+   * ```
+   * 
+   * **When false**
+   * 
+   * ```javascript
+   * // generated schema for `address` association
+   * {
+   *  "name": "example value",
+   *  "address": "the key of the referenced schema"
+   * }
+   * ```
+   */
+  linked?: boolean;
+  /**
+   * When the association has multiple targets the union type should be
+   * set to describe which union this is.
+   * 
+   * Possible values are:
+   * 
+   * - allOf - To validate against `allOf`, the given data must be valid against all of the given sub-schemas. When generating, it's a sum of all properties.
+   * - anyOf - To validate against `anyOf`, the given data must be valid against any (one or more) of the given sub-schemas. When generation a schema, it takes first union schema.
+   * - oneOf - To validate against `oneOf`, the given data must be valid against exactly one of the given sub-schemas. It behaves the same as `oneOf` when generating a schema
+   * - not - The `not` keyword declares that an instance validates if it doesn’t validate against the given sub-schema. It has no use when generating a schema.
+   * 
+   * @default anyOf
+   */
+  unionType?: 'allOf' | 'anyOf' | 'oneOf' | 'not';
+}
+
+export interface IDataExample extends IDomainProperty {
+  name?: string;
+  displayName?: string;
+  description?: string;
+  /**
+   * This is the "raw" property of AMF
+   */
+  value?: string;
+  structuredValue?: IDataNodeUnion;
+  strict: boolean;
+  mediaType?: string;
+  location?: string;
+  sourceMaps?: ApiDocumentSourceMaps;
+}
+
+export function xmlSerializer(id: string): IXmlSerializer {
+  return {
+    id: `xml-serializer-${id}`,
+    types: XmlSerializationTypes,
+    customDomainProperties: [],
+  };
+}
+
+export function shape(id: string): IShape {
+  const result: IShape = {
+    id,
+    types: [],
+    values: [], 
+    inherits: [], 
+    or: [], 
+    and: [], 
+    xone: [],
+    customDomainProperties: [],
+  };
+  return result;
+}
+
+export function anyShape(id: string): IAnyShape {
+  const result: IAnyShape = {
+    ...shape(id),
+    types: AnyTypes,
+    examples: [],
+    xmlSerialization: xmlSerializer(id),
+  };
+  return result;
+}
+
+export function nodeShape(id: string): INodeShape {
+  const result = anyShape(id);
+  result.types = NodeTypes;
+  result.id = `node-shape-${id}`;
+  return { 
+    ...result, 
+    properties: [], 
+    dependencies: [], 
+    customShapeProperties: [], 
+    customShapePropertyDefinitions: [],
+  };
+}
+
+export function scalarShape(id: string): IScalarShape {
+  const result = anyShape(id);
+  result.id = `scalar-shape-${id}`;
+  result.types = ScalarTypes;
+  return result;
+}
+
+export function unionShape(id: string): IUnionShape {
+  const result = anyShape(id);
+  result.id = `union-shape-${id}`;
+  result.types = UnionTypes;
+  return { ...result, anyOf: [] };
+}
+
+export function fileShape(id: string): IFileShape {
+  const result = anyShape(id);
+  result.id = `file-shape-${id}`;
+  result.types = FileTypes;
+  return result;
+}
+
+export function arrayShape(id: string): IArrayShape {
+  const result = anyShape(id);
+  result.id = `array-shape-${id}`;
+  result.types = ArrayTypes;
+  return result;
+}
+
+export function tupleShape(id: string): ITupleShape {
+  const result = anyShape(id);
+  result.id = `tuple-shape-${id}`;
+  result.types = TupleTypes;
+  return { ...result, items: [] };
+}
+
+export function propertyShape(id: string): IPropertyShape {
+  const result = anyShape(id);
+  result.types = PropertyTypes;
+  return result;
+}
+
+export function recursiveShape(id: string, fixedId?: string): IRecursiveShape {
+  const result: IRecursiveShape = {
+    ...shape(id),
+    id: `recursive-${id}`,
+    types: RecursiveTypes,
+    fixPoint: fixedId || '',
+  };
+  return result;
+}
+
+export interface IShape extends IDomainProperty {
+  /**
+   * Enum values for this shape.
+   */
+  values: IDataNodeUnion[];
+  /**
+   * The list of shapes that this shape inherits from
+   */
+  inherits: IShapeUnion[];
+  /**
+   * The `anyOf` union type.
+   */
+  or: IShapeUnion[];
+  /**
+   * The `allOf` union type.
+   */
+  and: IShapeUnion[];
+  /**
+   * The `oneOf` union type.
+   */
+  xone: IShapeUnion[];
+  /**
+   * The name of the shape in the system.
+   */
+  name?: string;
+  /**
+   * The display name for the shape in the UI.
+   */
+  displayName?: string;
+  /**
+   * The description of the shape.
+   */
+  description?: string;
+  /**
+   * The default value encoded as a string
+   */
+  defaultValueStr?: string;
+  /**
+   * The description of the default value of the shape.
+   */
+  defaultValue?: IDataNodeUnion;
+  /**
+   * Whether the shape is deprecated.
+   */
+  deprecated?: boolean;
+  /**
+   * Whether the shape is a read only shape (disallow writes to the value)
+   */
+  readOnly?: boolean;
+  /**
+   * Whether the shape can only be written to (disallow reading the value)
+   */
+  writeOnly?: boolean;
+  not?: IShapeUnion;
+  /**
+   * A label that appeared on a link.
+   */
+  linkLabel?: string;
+  sourceMaps?: ApiDocumentSourceMaps;
+}
+
+/**
+ * A property of an API operation.
+ */
+export interface IPropertyShape<T = IShapeUnion> extends IShape {
+  /**
+   * The path of the property. Essentially, it is link generated by the AMF library
+   * where the fragment part is the name of the property.
+   */
+  path?: string;
+  /**
+   * The parameter shape definition
+   */
+  range?: T;
+  /**
+   * When > 0 then the parameter is required.
+   */
+  minCount?: number;
+  maxCount?: number;
+}
+
+export interface IAnyShape extends IShape {
+  documentation?: ApiDocumentation;
+  /**
+   * Description of how the shape should be serialized as XML.
+   */
+  xmlSerialization: IXmlSerializer;
+  /**
+   * Examples defined for the shape.
+   */
+  examples: IDataExample[];
+}
+
+/**
+ * Describes an object shape.
+ */
+export interface INodeShape extends IAnyShape {
+  minProperties?: number;
+  maxProperties?: number;
+  closed?: boolean;
+  customShapeProperties: string[];
+  customShapePropertyDefinitions: string[];
+  discriminator?: string;
+  discriminatorValue?: string;
+  properties: IPropertyShape[];
+  dependencies: string[];
+}
+
+export interface IXmlSerializer extends IDomainProperty {
+  /**
+   * Whether this property should be represented as an attribute of the parent shape.
+   * 
+   * ```
+   * <Person name="John Doe"></Person>
+   * ```
+   */
+  attribute?: boolean;
+  /**
+   * When the property is an array (has the `multiple` set to true in the data model)
+   * then it tells that the list of values should be wrapped with a parent
+   * element:
+   * 
+   * ```
+   * <Person>
+   *  <Person fullName="John Doe"></Person>
+   *  <Person fullName="Other 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;
+  /**
+   * The name of the attribute or a wrapped property to use when serializing the property.
+   * 
+   * Attribute name
+   * ```xml
+   * <Person fullName="John Doe"></Person>
+   * ```
+   * 
+   * Wrapped name
+   * ```xml
+   * <people>
+   *  <Person name="John Doe"></Person>
+   * </people>
+   * ```
+   */
+  name?: string;
+  /**
+   * The XML namespace to use.
+   * 
+   * ```xml
+   * <Person ns:name="John Doe"></Person>
+   * ```
+   */
+  namespace?: string;
+  /**
+   * Name prefix
+   * 
+   * ```xml
+   * <ns:Person name="John Doe"></ns:Person>
+   * ```
+   */
+  prefix?: string;
+  sourceMaps?: ApiDocumentSourceMaps;
+}
+
+export interface IScalarShape extends IAnyShape {
+  dataType?: string;
+  pattern?: string;
+  minLength?: number;
+  maxLength?: number;
+  minimum?: number;
+  maximum?: number;
+  exclusiveMinimum?: boolean;
+  exclusiveMaximum?: boolean;
+  format?: string;
+  multipleOf?: number;
+}
+
+export interface IFileShape extends IAnyShape {
+  fileTypes?: string[];
+  pattern?: string;
+  minLength?: number;
+  maxLength?: number;
+  minimum?: number;
+  maximum?: number;
+  exclusiveMinimum?: boolean;
+  exclusiveMaximum?: boolean;
+  format?: string;
+  multipleOf?: number;
+}
+
+export interface ISchemaShape extends IAnyShape {
+  mediaType?: string;
+  raw?: string;
+}
+
+export interface IUnionShape extends IAnyShape {
+  anyOf: IShapeUnion[];
+}
+
+export interface IDataArrangeShape extends IAnyShape {
+  minItems?: number;
+  maxItems?: number;
+  uniqueItems?: boolean;
+}
+
+export interface IArrayShape<T = IShapeUnion> extends IDataArrangeShape {
+  items?: T;
+}
+
+export interface ITupleShape<T = IShapeUnion> extends IDataArrangeShape {
+  items: T[];
+  additionalItems?: boolean;
+}
+
+export interface IRecursiveShape extends IShape {
+  fixPoint: string;
+}
+
+export interface IDataNode extends IDomainProperty {
+  name?: string;
+}
+
+export interface IObjectNode extends IDataNode {
+  properties: { [key: string]: IDataNodeUnion };
+}
+
+export interface IScalarNode extends IDataNode {
+  value?: string;
+  dataType?: string;
+}
+
+export interface IArrayNode extends IDataNode {
+  members: IDataNodeUnion[];
+}
+
+export type IDataNodeUnion = IDataNode | IObjectNode | IScalarNode | IArrayNode;

package/src/amf/models/AmfDataNode.ts

@@ -0,0 +1,200 @@
+import v4 from '../../lib/uuid.js';
+import { ArrayNodeTypes, ObjectNodeTypes, ScalarNodeTypes } from '../AmfTypes.js';
+import { ICustomDomainProperty } from '../definitions/Base.js';
+import { AmfNamespace } from '../definitions/Namespace.js';
+import { IArrayNode, IDataNode, IDataNodeUnion, IObjectNode, IScalarNode } from '../definitions/Shapes.js';
+
+export type IDataNodeInit = 'scalar' | 'object' | 'array';
+
+/**
+ * A class that manipulates the AMF's DataNode node.
+ */
+export class AmfDataNode {
+  id = v4();
+
+  /**
+   * AMF domain types.
+   * This is set in the constructor
+   */
+  types: string[];
+
+  /**
+   * The name of this data node.
+   */
+  name?: string;
+
+  /**
+   * Set when the object node type
+   */
+  properties?: { [key: string]: AmfDataNode };
+
+  /**
+   * Scalar type value. Always a string.
+   */
+  value?: string;
+
+  /** 
+   * Scalar type value data type.
+   */
+  dataType?: string;
+
+  /**
+   * Set when the type is array.
+   */
+  members?: AmfDataNode[];
+
+  customDomainProperties: ICustomDomainProperty[] = [];
+
+  static scalar(value: string, type: string): AmfDataNode {
+    const result = new AmfDataNode('scalar');
+    result.value = value;
+    result.dataType = type;
+    return result;
+  }
+
+  constructor(init: IDataNodeUnion | IDataNodeInit) {
+    if (typeof init === 'string') {
+      if (init === 'scalar') {
+        this.types = ScalarNodeTypes;
+      } else if (init === 'array') {
+        this.types = ArrayNodeTypes;
+      } else if (init === 'object') {
+        this.types = ObjectNodeTypes;
+      } else {
+        throw new Error(`Invalid data node init option: ${init}`);
+      }
+      return;
+    }
+    if (!init) {
+      throw new Error(`Expected an initialization option.`);
+    }
+    const union = init as IDataNodeUnion;
+    const { id, types, customDomainProperties } = union;
+    this.id = id;
+    this.types = types;
+    this.customDomainProperties = customDomainProperties;
+    if (types.includes(AmfNamespace.aml.vocabularies.data.Scalar)) {
+      const typed = union as IScalarNode;
+      this.value = typed.value;
+      this.dataType = typed.dataType;
+    } else if (types.includes(AmfNamespace.aml.vocabularies.data.Object)) {
+      const typed = union as IObjectNode;
+      this.properties = {};
+      Object.keys(typed.properties).forEach((key) => {
+        const instance = new AmfDataNode(typed.properties[key]);
+        this.properties![key] = instance;
+      });
+    } else if (types.includes(AmfNamespace.aml.vocabularies.data.Array)) {
+      const typed = union as IArrayNode;
+      this.members = [];
+      if (Array.isArray(typed.members)) {
+        typed.members.forEach((member) => {
+          const instance = new AmfDataNode(member);
+          this.members!.push(instance);
+        });
+      }
+    }
+  }
+
+  toJSON(): IDataNodeUnion {
+    const { id, customDomainProperties, types, name } = this;
+    const result: IDataNode = {
+      id,
+      types,
+      customDomainProperties,
+    };
+    if (name) {
+      result.name = name;
+    }
+
+    if (types.includes(AmfNamespace.aml.vocabularies.data.Scalar)) {
+      const typed = result as IScalarNode;
+      typed.dataType = this.dataType;
+      typed.value = this.value;
+    } else if (types.includes(AmfNamespace.aml.vocabularies.data.Object)) {
+      const typed = result as IObjectNode;
+      typed.properties = {};
+      if (this.properties) {
+        Object.keys(this.properties).forEach((key) => {
+          typed.properties[key] = this.properties![key].toJSON();
+        });
+      }
+    } else if (types.includes(AmfNamespace.aml.vocabularies.data.Array)) {
+      const typed = result as IArrayNode;
+      typed.members = [];
+      if (this.members) {
+        this.members.forEach((member) => {
+          typed.members.push(member.toJSON());
+        });
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Adds a member to the list of members.
+   * It throws when this is not an array node.
+   * 
+   * @param init The member to add.
+   */
+  addMember(init: AmfDataNode): void {
+    if (!this.types.includes(AmfNamespace.aml.vocabularies.data.Array)) {
+      throw new Error(`Not an ArrayNode.`);
+    }
+    if (!this.members) {
+      this.members = [];
+    }
+    this.members.push(init);
+  }
+
+  /**
+   * Removes a member from the list of members.
+   * It throws when this is not an array node.
+   * 
+   * @param id The domain id of the member to remove.
+   */
+  removeMember(id: string): void {
+    if (!this.types.includes(AmfNamespace.aml.vocabularies.data.Array)) {
+      throw new Error(`Not an ArrayNode.`);
+    }
+    if (!this.members) {
+      return;
+    }
+    const index = this.members.findIndex(i => i.id === id);
+    if (index >= 0) {
+      this.members.splice(index, 1);
+    }
+  }
+
+  /**
+   * Adds a property to the ObjectNode.
+   * It throws when this is not an object node.
+   * 
+   * @param name The name of the property.
+   * @param value The instance of the DataNode to set.
+   */
+  addProperty(name: string, value: AmfDataNode): void {
+    if (!this.types.includes(AmfNamespace.aml.vocabularies.data.Object)) {
+      throw new Error(`Not an ObjectNode.`);
+    }
+    if (!this.properties) {
+      this.properties = {};
+    }
+    this.properties[name] = value;
+  }
+
+  /**
+   * Deletes a property by name.
+   * 
+   * @param name The name of the property to delete.
+   */
+  removeProperty(name: string): void {
+    if (!this.types.includes(AmfNamespace.aml.vocabularies.data.Object)) {
+      throw new Error(`Not an ObjectNode.`);
+    }
+    if (!this.properties) {
+      return;
+    }
+    delete this.properties[name];
+  }
+}

package/src/amf/shape/README.md

@@ -0,0 +1,4 @@
+# Shape based schema generators
+
+In this directory you will find libraries to generate a schema from AMF shapes.
+This generates a schema taking shape properties into the account.