@api-client/core 0.6.13 → 0.6.16

package/src/amf/ApiMonacoSchemaGenerator.ts

@@ -0,0 +1,296 @@
+import { AmfNamespace as ns } from "./definitions/Namespace.js";
+import { IArrayShape, INodeShape, IPropertyShape, IScalarNode, IScalarShape, IShapeUnion } from "./definitions/Shapes.js";
+import { collectNodeProperties } from './Utils.js';
+
+export interface IMonacoSchema {
+  uri: string;
+  schema: IMonacoProperty;
+  fileMatch?: string[];
+}
+
+export interface IMonacoProperty {
+  $id?: string;
+  title: string;
+  type: string;
+  description?: string;
+  readOnly?: boolean;
+  writeOnly?: boolean;
+}
+
+export interface IMonacoScalarProperty extends IMonacoProperty {
+  default?: string;
+  pattern?: string;
+  format?: string;
+  exclusiveMaximum?: boolean;
+  exclusiveMinimum?: boolean;
+  maxLength?: number;
+  minLength?: number;
+  minimum?: number;
+  maximum?: number;
+  multipleOf?: number;
+  enum?: string[];
+}
+
+export interface IMonacoObjectProperty extends IMonacoProperty {
+  properties: Record<string, IMonacoProperty>;
+  required: string[];
+  additionalProperties?: boolean;
+  minProperties?: number;
+  maxProperties?: number;
+}
+
+export interface IMonacoArrayProperty extends IMonacoProperty {
+  additionalItems?: boolean;
+  items: {
+    anyOf: IMonacoProperty[]
+  }
+  uniqueItems?: boolean;
+  minItems?: number;
+  maxItems?: number;
+  required: string[];
+}
+
+function cleanName(name?: string): string {
+  if (!name) {
+    return '';
+  }
+  return name.replace('?', '');
+}
+
+/**
+ * A class to generate JSON schema from an ApiShapeUnion declaration to use with the Monaco editor schemas.
+ */
+export class ApiMonacoSchemaGenerator {
+  schemas: IMonacoSchema[] = [];
+
+  /**
+   * @param parentUri The URI for the fileMatch property.
+   */
+  generate(schema: IShapeUnion, parentUri: string): IMonacoSchema[] {
+    this.schemas = [];
+    if (!schema) {
+      return [];
+    }
+    const { types } = schema;
+    if (types.includes(ns.w3.shacl.NodeShape)) {
+      return this.fromNodeShape(schema as INodeShape, parentUri);
+    }
+    return [];
+  }
+
+  /**
+   * @param parentUri The URI for the fileMatch property.
+   */
+  fromNodeShape(schema: INodeShape, parentUri?: string): IMonacoSchema[] {
+    const { id, name } = schema;
+    const properties = collectNodeProperties(schema);
+    const content: IMonacoObjectProperty = {
+      title: cleanName(name),
+      type: "object",
+      properties: {},
+      required: [],
+    };
+    const result: IMonacoSchema = {
+      uri: id,
+      schema: content,
+    };
+    if (parentUri) {
+      result.fileMatch = [parentUri];
+    }
+    this.schemas.push(result);
+    if (!Array.isArray(properties) || !properties.length) {
+      return this.schemas;
+    }
+    properties.forEach(property => this.appendSchemaProperty(content, property));
+    return this.schemas;
+  }
+
+  appendSchemaProperty(content: IMonacoObjectProperty, property: IPropertyShape): void {
+    const { name, range, minCount } = property;
+    if (!range) {
+      return;
+    }
+    const value = this.rangeToPropertySchema(range);
+    if (value && name) {
+      content.properties[name] = value;
+      if (minCount === 1) {
+        content.required.push(name);
+      }
+    }
+  }
+
+  rangeToPropertySchema(range: IShapeUnion): IMonacoScalarProperty | IMonacoObjectProperty | IMonacoArrayProperty | undefined {
+    const { types } = range;
+    if (types.includes(ns.aml.vocabularies.shapes.ScalarShape)) {
+      return this.scalarRangeToPropertySchema(range as IScalarShape);
+    }
+    if (types.includes(ns.w3.shacl.NodeShape)) {
+      return this.nodeShapeRangeToPropertySchema(range as INodeShape);
+    }
+    if (types.includes(ns.aml.vocabularies.shapes.ArrayShape)) {
+      return this.arrayShapeRangeToPropertySchema(range as IArrayShape);
+    }
+    return undefined;
+  }
+
+  scalarRangeToPropertySchema(schema: IScalarShape): IMonacoScalarProperty {
+    const { values, description, name, displayName, defaultValueStr, exclusiveMaximum, exclusiveMinimum, minimum, maximum, minLength, maxLength, id, multipleOf, pattern, readOnly, writeOnly } = schema;
+    const type = this.schemaTypeToJsonDataType(schema.dataType);
+    const result: IMonacoScalarProperty = {
+      '$id': id,
+      type,
+      title: cleanName(displayName || name),
+    };
+    if (description) {
+      result.description = description;
+    }
+    if (defaultValueStr) {
+      result.default = defaultValueStr;
+    }
+    if (typeof exclusiveMaximum === 'boolean') {
+      result.exclusiveMaximum = exclusiveMaximum;
+    }
+    if (typeof exclusiveMinimum === 'boolean') {
+      result.exclusiveMinimum = exclusiveMinimum;
+    }
+    if (typeof maxLength === 'number') {
+      result.maxLength = maxLength;
+    }
+    if (typeof minLength === 'number') {
+      result.minLength = minLength;
+    }
+    if (typeof minimum === 'number') {
+      result.minimum = minimum;
+    }
+    if (typeof maximum === 'number') {
+      result.maximum = maximum;
+    }
+    if (typeof multipleOf === 'number') {
+      result.multipleOf = multipleOf;
+    }
+    if (typeof pattern === 'string') {
+      result.pattern = pattern;
+    }
+    if (typeof readOnly === 'boolean') {
+      result.readOnly = readOnly;
+    }
+    if (typeof writeOnly === 'boolean') {
+      result.writeOnly = writeOnly;
+    }
+    switch (schema.dataType) {
+      case ns.aml.vocabularies.shapes.dateTimeOnly: result.format = 'date-time'; break;
+      case ns.w3.xmlSchema.date: result.format = 'date'; break;
+      case ns.w3.xmlSchema.time: result.format = 'time'; break;
+      default:
+    }
+    if (Array.isArray(values) && values.length) {
+      // enum properties
+      result.enum = [];
+      values.forEach((value) => {
+        const { types } = value;
+        if (types.includes(ns.aml.vocabularies.data.Scalar)) {
+          const typed = value as IScalarNode;
+          if (typed.value) {
+            result.enum!.push(typed.value);
+          }
+        }
+      });
+    }
+    return result;
+  }
+
+  /**
+   * Translates AMF data type to JSON schema data type.
+   */
+  schemaTypeToJsonDataType(schemaType?: string): string {
+    switch (schemaType) {
+      case ns.aml.vocabularies.shapes.number:
+      case ns.aml.vocabularies.shapes.integer:
+      case ns.aml.vocabularies.shapes.float:
+      case ns.aml.vocabularies.shapes.long:
+      case ns.aml.vocabularies.shapes.double:
+      case ns.w3.xmlSchema.number:
+      case ns.w3.xmlSchema.integer:
+      case ns.w3.xmlSchema.float:
+      case ns.w3.xmlSchema.long:
+      case ns.w3.xmlSchema.double: return 'number';
+      case ns.w3.xmlSchema.boolean:
+      case ns.aml.vocabularies.shapes.boolean: return 'boolean';
+      case ns.aml.vocabularies.shapes.nil:
+      case ns.w3.xmlSchema.nil: return 'null';
+      default: return 'string';
+    }
+  }
+
+  nodeShapeRangeToPropertySchema(schema: INodeShape): IMonacoObjectProperty {
+    const { description, name, displayName, id, readOnly, writeOnly, closed, minProperties, maxProperties } = schema;
+    const properties = collectNodeProperties(schema);
+
+    const result: IMonacoObjectProperty = {
+      '$id': id,
+      type: 'object',
+      title: cleanName(displayName || name),
+      properties: {},
+      required: [],
+    };
+    if (description) {
+      result.description = description;
+    }
+    if (typeof readOnly === 'boolean') {
+      result.readOnly = readOnly;
+    }
+    if (typeof writeOnly === 'boolean') {
+      result.writeOnly = writeOnly;
+    }
+    if (typeof closed === 'boolean') {
+      result.additionalProperties = !closed;
+    }
+    if (typeof minProperties === 'number') {
+      result.minProperties = minProperties;
+    }
+    if (typeof maxProperties === 'number') {
+      result.maxProperties = maxProperties;
+    }
+    properties.forEach(property => this.appendSchemaProperty(result, property));
+    return result;
+  }
+
+  arrayShapeRangeToPropertySchema(schema: IArrayShape): IMonacoArrayProperty {
+    const { description, name, displayName, id, readOnly, writeOnly, items, minItems, maxItems, uniqueItems } = schema;
+    const result: IMonacoArrayProperty = {
+      '$id': id,
+      type: 'array',
+      title: cleanName(displayName || name),
+      items: {
+        anyOf: [],
+      },
+      required: [],
+      additionalItems: false,
+    };
+    if (description) {
+      result.description = description;
+    }
+    if (typeof readOnly === 'boolean') {
+      result.readOnly = readOnly;
+    }
+    if (typeof writeOnly === 'boolean') {
+      result.writeOnly = writeOnly;
+    }
+    if (typeof uniqueItems === 'boolean') {
+      result.uniqueItems = uniqueItems;
+    }
+    if (items) {
+      const value = this.rangeToPropertySchema(items);
+      if (value) {
+        result.items.anyOf.push(value);
+      }
+    }
+    if (typeof minItems === 'number') {
+      result.minItems = minItems;
+    }
+    if (typeof maxItems === 'number') {
+      result.maxItems = maxItems;
+    }
+    return result;
+  }
+}

package/src/amf/ApiSchemaGenerator.ts

@@ -0,0 +1,108 @@
+import { AmfNamespace as ns } from "./definitions/Namespace.js";
+import { IAnyShape, IDataExample, IShapeUnion } from "./definitions/Shapes.js";
+import { ShapeBase, ShapeRenderOptions } from "./shape/ShapeBase.js";
+import { ShapeJsonSchemaGenerator } from './shape/ShapeJsonSchemaGenerator.js';
+import { ShapeXmlSchemaGenerator } from './shape/ShapeXmlSchemaGenerator.js';
+
+export interface ISchemaExample extends IDataExample {
+  /**
+   * The value to render as the example value.
+   */
+  renderValue?: string | number | boolean | null | undefined;
+  label?: string;
+}
+
+/**
+ * A class that processes AMF's Shape to auto-generate a schema from examples/type for a given media type.
+ * This should be used when examples for the Shape are not available but the application still needs to 
+ * render an example or a schema from the Shape.
+ * If examples can be found directly in the shape, use the `ApiExampleGenerator` instead.
+ */
+export class ApiSchemaGenerator {
+  opts: Readonly<ShapeRenderOptions>;
+
+  generator?: ShapeBase;
+
+  /**
+   * 
+   * @param mime The example mime type to format the generated example.
+   * @param opts Optional configuration.
+   */
+  constructor(public mime: string, opts: ShapeRenderOptions = {}) {
+    this.opts = Object.freeze({ ...opts });
+    if (mime.includes('json')) {
+      this.generator = new ShapeJsonSchemaGenerator(opts);
+    } else if (mime.includes('xml')) {
+      this.generator = new ShapeXmlSchemaGenerator(opts);
+    }
+  }
+
+  /**
+   * @param shape The Shape definition
+   * @param mime The mime type for the value.
+   * @returns Customized Example with the `renderValue` that is the generated Example value.
+   */
+  static asExample(shape: IShapeUnion, mime: string, opts?: ShapeRenderOptions): ISchemaExample | undefined {
+    const generator = new ApiSchemaGenerator(mime, opts);
+    return generator.toExample(shape);
+  }
+
+  /**
+   * @param shape The Shape definition
+   * @param mime The mime type for the value.
+   * @returns The generated schema
+   */
+  static asSchema(shape: IShapeUnion, mime: string, opts?: ShapeRenderOptions): string | number | boolean | null | undefined {
+    const generator = new ApiSchemaGenerator(mime, opts);
+    return generator.toValue(shape);
+  }
+
+  /**
+   * Generates the schema from the AMF shape.
+   * 
+   * @param shape The Shape definition
+   */
+  generate(shape: IShapeUnion): string | number | boolean | null | undefined {
+    const { generator } = this;
+    if (!generator) {
+      return undefined;
+    }
+    return generator.generate(shape);
+  }
+
+  /**
+   * @link {#generate()}
+   * @param shape The Shape definition
+   */
+  toValue(shape: IShapeUnion): string | number | boolean | null | undefined {
+    return this.generate(shape);
+  }
+
+  /**
+   * Generates an API Example object with the value to render.
+   * @param shape The Shape definition
+   * @returns Customized Example with the `renderValue` that is the generated Example value.
+   */
+  toExample(shape: IShapeUnion): ISchemaExample | undefined {
+    const renderValue = this.generate(shape);
+    if (renderValue === null || renderValue === undefined) {
+      return undefined;
+    }
+    const result: ISchemaExample = {
+      id: `${shape.id}/generated`,
+      strict: true,
+      types: [ns.aml.vocabularies.apiContract.Example],
+      mediaType: this.mime,
+      renderValue,
+      customDomainProperties: [],
+    };
+    const typed = shape as IAnyShape;
+    if (Array.isArray(typed.examples) && typed.examples.length) {
+      const [example] = typed.examples;
+      if (example.value) {
+        result.value = example.value;
+      }
+    }
+    return result;
+  }
+}