@loopback/repository-json-schema 4.0.0-alpha.8 → 5.0.0

package/src/build-schema.ts

@@ -1,58 +1,203 @@
-// Copyright IBM Corp. 2018. All Rights Reserved.
+// Copyright IBM Corp. 2018,2020. All Rights Reserved.
 // Node module: @loopback/repository-json-schema
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
+import {MetadataInspector} from '@loopback/core';
 import {
+  isBuiltinType,
+  ModelDefinition,
   ModelMetadataHelper,
+  Null,
   PropertyDefinition,
-  ModelDefinition,
+  PropertyType,
+  RelationMetadata,
+  resolveType,
 } from '@loopback/repository';
-import {includes} from 'lodash';
-import {Definition, PrimitiveType} from 'typescript-json-schema';
-import {MetadataInspector} from '@loopback/context';
+import debugFactory from 'debug';
+import {inspect} from 'util';
+import {JsonSchema} from './index';
+import {JSON_SCHEMA_KEY} from './keys';
+const debug = debugFactory('loopback:repository-json-schema:build-schema');
+
+export interface JsonSchemaOptions<T extends object> {
+  /**
+   * The title to use in the generated schema.
+   *
+   * When using options like `exclude`, the auto-generated title can be
+   * difficult to read for humans. Use this option to change the title to
+   * a more meaningful value.
+   */
+  title?: string;
+
+  /**
+   * Set this flag if you want the schema to define navigational properties
+   * for model relations.
+   */
+  includeRelations?: boolean;
+
+  /**
+   * Set this flag to mark all model properties as optional. This is typically
+   * used to describe request body of PATCH endpoints. This option will be
+   * overridden by the "optional" option if it is set and non-empty.
+   *
+   * The flag also applies to nested model instances if its value is set to
+   * 'deep', such as:
+   *
+   * @example
+   * ```ts
+   * @model()
+   * class Address {
+   *  @property()
+   *  street: string;
+   *  @property()
+   *  city: string;
+   *  @property()
+   *  state: string;
+   *  @property()
+   *  zipCode: string;
+   * }
+   *
+   * @model()
+   * class Customer {
+   *   @property()
+   *   address: Address;
+   * }
+   *
+   * // The following schema allows properties of `customer` optional, but not
+   * // `customer.address`
+   * const schemaRef1 = getModelSchemaRef(Customer, {partial: true});
+   *
+   * // The following schema allows properties of `customer` and
+   * // `customer.address` optional
+   * const schemaRef2 = getModelSchemaRef(Customer, {partial: 'deep'});
+   * ```
+   */
+  partial?: boolean | 'deep';
+
+  /**
+   * List of model properties to exclude from the schema.
+   */
+  exclude?: (keyof T)[];
+
+  /**
+   * List of model properties to mark as optional. Overrides the "partial"
+   * option if it is not empty.
+   */
+  optional?: (keyof T)[];
 
-export const JSON_SCHEMA_KEY = 'loopback:json-schema';
+  /**
+   * @internal
+   */
+  visited?: {[key: string]: JsonSchema};
+}
 
 /**
- * Type definition for JSON Schema
+ * @internal
  */
-export interface JsonDefinition extends Definition {
-  allOf?: JsonDefinition[];
-  oneOf?: JsonDefinition[];
-  anyOf?: JsonDefinition[];
-  items?: JsonDefinition | JsonDefinition[];
-  additionalItems?: {
-    anyOf: JsonDefinition[];
-  };
-  enum?: PrimitiveType[] | JsonDefinition[];
-  additionalProperties?: JsonDefinition | boolean;
-  definitions?: {[definition: string]: JsonDefinition};
-  properties?: {[property: string]: JsonDefinition};
+export function buildModelCacheKey<T extends object>(
+  options: JsonSchemaOptions<T> = {},
+): string {
+  // Backwards compatibility: preserve cache key "modelOnly"
+  if (Object.keys(options).length === 0) {
+    return 'modelOnly';
+  }
+
+  // New key schema: use the same suffix as we use for schema title
+  // For example: "modelPartialWithRelations"
+  // Note this new key schema preserves the old key "modelWithRelations"
+  return 'model' + (options.title ?? '') + getTitleSuffix(options);
 }
 
 /**
  * Gets the JSON Schema of a TypeScript model/class by seeing if one exists
  * in a cache. If not, one is generated and then cached.
- * @param ctor Contructor of class to get JSON Schema from
+ * @param ctor - Constructor of class to get JSON Schema from
  */
-export function getJsonSchema(ctor: Function): JsonDefinition {
-  // NOTE(shimks) currently impossible to dynamically update
-  const jsonSchema = MetadataInspector.getClassMetadata(JSON_SCHEMA_KEY, ctor);
-  if (jsonSchema) {
-    return jsonSchema;
-  } else {
-    const newSchema = modelToJsonSchema(ctor);
-    MetadataInspector.defineMetadata(JSON_SCHEMA_KEY, newSchema, ctor);
-    return newSchema;
+export function getJsonSchema<T extends object>(
+  ctor: Function & {prototype: T},
+  options?: JsonSchemaOptions<T>,
+): JsonSchema {
+  // In the near future the metadata will be an object with
+  // different titles as keys
+  const cached = MetadataInspector.getClassMetadata(JSON_SCHEMA_KEY, ctor, {
+    ownMetadataOnly: true,
+  });
+  const key = buildModelCacheKey(options);
+  let schema = cached?.[key];
+
+  if (!schema) {
+    // Create new json schema from model
+    // if not found in cache for specific key
+    schema = modelToJsonSchema(ctor, options);
+    if (cached) {
+      // Add a new key to the cached schema of the model
+      cached[key] = schema;
+    } else {
+      // Define new metadata and set in cache
+      MetadataInspector.defineMetadata(
+        JSON_SCHEMA_KEY.key,
+        {[key]: schema},
+        ctor,
+      );
+    }
   }
+
+  return schema;
+}
+
+/**
+ * Describe the provided Model as a reference to a definition shared by multiple
+ * endpoints. The definition is included in the returned schema.
+ *
+ * @example
+ *
+ * ```ts
+ * const schema = {
+ *   $ref: '/definitions/Product',
+ *   definitions: {
+ *     Product: {
+ *       title: 'Product',
+ *       properties: {
+ *         // etc.
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @param modelCtor - The model constructor (e.g. `Product`)
+ * @param options - Additional options
+ */
+export function getJsonSchemaRef<T extends object>(
+  modelCtor: Function & {prototype: T},
+  options?: JsonSchemaOptions<T>,
+): JsonSchema {
+  const schemaWithDefinitions = getJsonSchema(modelCtor, options);
+  const key = schemaWithDefinitions.title;
+
+  // ctor is not a model
+  if (!key) return schemaWithDefinitions;
+
+  const definitions = Object.assign({}, schemaWithDefinitions.definitions);
+  const schema = Object.assign({}, schemaWithDefinitions);
+  delete schema.definitions;
+  definitions[key] = schema;
+
+  return {
+    $ref: `#/definitions/${key}`,
+    definitions,
+  };
 }
 
 /**
  * Gets the wrapper function of primitives string, number, and boolean
- * @param type Name of type
+ * @param type - Name of type
  */
-export function stringTypeToWrapper(type: string): Function {
+export function stringTypeToWrapper(type: string | Function): Function {
+  if (typeof type === 'function') {
+    return type;
+  }
   type = type.toLowerCase();
   let wrapper;
   switch (type) {
@@ -68,50 +213,203 @@ export function stringTypeToWrapper(type: string): Function {
       wrapper = Boolean;
       break;
     }
+    case 'array': {
+      wrapper = Array;
+      break;
+    }
+    case 'object':
+    case 'any': {
+      wrapper = Object;
+      break;
+    }
+    case 'date': {
+      wrapper = Date;
+      break;
+    }
+    case 'buffer': {
+      wrapper = Buffer;
+      break;
+    }
+    case 'null': {
+      wrapper = Null;
+      break;
+    }
     default: {
-      throw new Error('Unsupported type');
+      throw new Error('Unsupported type: ' + type);
     }
   }
   return wrapper;
 }
 
 /**
- * Determines whether the given constructor is a custom type or not
- * @param ctor Constructor
+ * Determines whether a given string or constructor is array type or not
+ * @param type - Type as string or wrapper
  */
-export function isComplexType(ctor: Function) {
-  return !includes([String, Number, Boolean, Object, Function], ctor);
+export function isArrayType(type: string | Function | PropertyType) {
+  return type === Array || type === 'array';
 }
 
 /**
  * Converts property metadata into a JSON property definition
  * @param meta
  */
-export function metaToJsonProperty(meta: PropertyDefinition): JsonDefinition {
-  let ctor = meta.type as string | Function;
-  let def: JsonDefinition = {};
+export function metaToJsonProperty(meta: PropertyDefinition): JsonSchema {
+  const propDef: JsonSchema = {};
+  let result: JsonSchema;
+  let propertyType = meta.type as string | Function;
+
+  if (isArrayType(propertyType) && meta.itemType) {
+    if (isArrayType(meta.itemType) && !meta.jsonSchema) {
+      throw new Error(
+        'You must provide the "jsonSchema" field when define ' +
+          'a nested array property',
+      );
+    }
+    result = {type: 'array', items: propDef};
+    propertyType = meta.itemType as string | Function;
+  } else {
+    result = propDef;
+  }
+
+  const wrappedType = stringTypeToWrapper(propertyType);
+  const resolvedType = resolveType(wrappedType);
+
+  if (resolvedType === Date) {
+    Object.assign(propDef, {
+      type: 'string',
+      format: 'date-time',
+    });
+  } else if (propertyType === 'any') {
+    // no-op, the json schema for any type is {}
+  } else if (isBuiltinType(resolvedType)) {
+    Object.assign(propDef, {
+      type: resolvedType.name.toLowerCase(),
+    });
+  } else {
+    Object.assign(propDef, {$ref: `#/definitions/${resolvedType.name}`});
+  }
 
-  // errors out if @property.array() is not used on a property of array
-  if (ctor === Array) {
-    throw new Error('type is defined as an array');
+  if (meta.description) {
+    Object.assign(propDef, {
+      description: meta.description,
+    });
   }
 
-  if (typeof ctor === 'string') {
-    ctor = stringTypeToWrapper(ctor);
+  if (meta.jsonSchema) {
+    Object.assign(propDef, meta.jsonSchema);
   }
 
-  const propDef = isComplexType(ctor)
-    ? {$ref: `#/definitions/${ctor.name}`}
-    : {type: ctor.name.toLowerCase()};
+  return result;
+}
 
-  if (meta.array) {
-    def.type = 'array';
-    def.items = propDef;
+/**
+ * Checks and return navigational property definition for the relation
+ * @param relMeta Relation metadata object
+ * @param targetRef Schema definition for the target model
+ */
+export function getNavigationalPropertyForRelation(
+  relMeta: RelationMetadata,
+  targetRef: JsonSchema,
+): JsonSchema {
+  if (relMeta.targetsMany === true) {
+    // Targets an array of object, like, hasMany
+    return {
+      type: 'array',
+      items: targetRef,
+    };
+  } else if (relMeta.targetsMany === false) {
+    // Targets single object, like, hasOne, belongsTo
+    return targetRef;
   } else {
-    Object.assign(def, propDef);
+    // targetsMany is undefined or null
+    // not allowed if includeRelations is true
+    throw new Error(`targetsMany attribute missing for ${relMeta.name}`);
+  }
+}
+
+function buildSchemaTitle<T extends object>(
+  ctor: Function & {prototype: T},
+  meta: ModelDefinition,
+  options: JsonSchemaOptions<T>,
+) {
+  if (options.title) return options.title;
+  const title = meta.title || ctor.name;
+  return title + getTitleSuffix(options);
+}
+
+/**
+ * Checks the options and generates a descriptive suffix using compatible chars
+ * @param options json schema options
+ */
+function getTitleSuffix<T extends object>(options: JsonSchemaOptions<T> = {}) {
+  let suffix = '';
+
+  if (options.optional?.length) {
+    suffix += `Optional_${options.optional.join('-')}_`;
+  } else if (options.partial) {
+    suffix += 'Partial';
+  }
+  if (options.exclude?.length) {
+    suffix += `Excluding_${options.exclude.join('-')}_`;
+  }
+  if (options.includeRelations) {
+    suffix += 'WithRelations';
+  }
+
+  return suffix;
+}
+
+function stringifyOptions(modelSettings: object = {}) {
+  return inspect(modelSettings, {
+    depth: Infinity,
+    maxArrayLength: Infinity,
+    breakLength: Infinity,
+  });
+}
+
+function isEmptyJson(obj: object) {
+  return !(obj && Object.keys(obj).length);
+}
+
+/**
+ * Checks the options and generates a descriptive suffix that contains the
+ * TypeScript type and options
+ * @param typeName - TypeScript's type name
+ * @param options - json schema options
+ */
+function getDescriptionSuffix<T extends object>(
+  typeName: string,
+  rawOptions: JsonSchemaOptions<T> = {},
+) {
+  const options = {...rawOptions};
+
+  delete options.visited;
+  if (options.optional && !options.optional.length) {
+    delete options.optional;
+  }
+
+  const type = typeName;
+  let tsType = type;
+  if (options.includeRelations) {
+    tsType = `${type}WithRelations`;
+  }
+  if (options.partial) {
+    tsType = `Partial<${tsType}>`;
+  }
+  if (options.exclude) {
+    const excludedProps = options.exclude.map(p => `'${p}'`);
+    tsType = `Omit<${tsType}, ${excludedProps.join(' | ')}>`;
+  }
+  if (options.optional) {
+    const optionalProps = options.optional.map(p => `'${p}'`);
+    tsType = `@loopback/repository-json-schema#Optional<${tsType}, ${optionalProps.join(
+      ' | ',
+    )}>`;
   }
 
-  return def;
+  return !isEmptyJson(options)
+    ? `(tsType: ${tsType}, schemaOptions: ${stringifyOptions(options)})`
+    : '';
 }
 
 // NOTE(shimks) no metadata for: union, optional, nested array, any, enum,
@@ -120,61 +418,175 @@ export function metaToJsonProperty(meta: PropertyDefinition): JsonDefinition {
 /**
  * Converts a TypeScript class into a JSON Schema using TypeScript's
  * reflection API
- * @param ctor Constructor of class to convert from
+ * @param ctor - Constructor of class to convert from
  */
-export function modelToJsonSchema(ctor: Function): JsonDefinition {
-  const meta: ModelDefinition | {} = ModelMetadataHelper.getModelMetadata(ctor);
-  const result: JsonDefinition = {};
+export function modelToJsonSchema<T extends object>(
+  ctor: Function & {prototype: T},
+  jsonSchemaOptions: JsonSchemaOptions<T> = {},
+): JsonSchema {
+  const options = {...jsonSchemaOptions};
+  options.visited = options.visited ?? {};
+  options.optional = options.optional ?? [];
+  const partial = options.partial && !options.optional.length;
+
+  if (options.partial && !partial) {
+    debug('Overriding "partial" option with "optional" option');
+    delete options.partial;
+  }
+
+  debug('Creating schema for model %s', ctor.name);
+  debug('JSON schema options: %o', options);
+
+  const modelDef = ModelMetadataHelper.getModelMetadata(ctor);
 
   // returns an empty object if metadata is an empty object
-  if (!(meta instanceof ModelDefinition)) {
+  if (modelDef == null || Object.keys(modelDef).length === 0) {
     return {};
   }
 
-  result.title = meta.title || ctor.name;
+  const meta = modelDef as ModelDefinition;
+
+  debug('Model settings', meta.settings);
+
+  const title = buildSchemaTitle(ctor, meta, options);
+  if (options.visited[title]) return options.visited[title];
+
+  const result: JsonSchema = {title};
+  options.visited[title] = result;
+
+  result.type = 'object';
+
+  const descriptionSuffix = getDescriptionSuffix(ctor.name, options);
 
   if (meta.description) {
-    result.description = meta.description;
+    const formatSuffix = descriptionSuffix ? ` ${descriptionSuffix}` : '';
+
+    result.description = meta.description + formatSuffix;
+  } else if (descriptionSuffix) {
+    result.description = descriptionSuffix;
   }
 
   for (const p in meta.properties) {
-    if (!meta.properties[p].type) {
+    if (options.exclude?.includes(p as keyof T)) {
+      debug('Property % is excluded by %s', p, options.exclude);
       continue;
     }
 
-    result.properties = result.properties || {};
+    if (meta.properties[p].type == null) {
+      // Circular import of model classes can lead to this situation
+      throw new Error(
+        `Property ${ctor.name}.${p} does not have "type" in its definition`,
+      );
+    }
+
+    result.properties = result.properties ?? {};
     result.properties[p] = result.properties[p] || {};
 
-    const metaProperty = meta.properties[p];
-    const metaType = metaProperty.type;
+    const metaProperty = Object.assign({}, meta.properties[p]);
 
     // populating "properties" key
     result.properties[p] = metaToJsonProperty(metaProperty);
 
+    // handling 'required' metadata
+    const optional = options.optional.includes(p as keyof T);
+
+    if (metaProperty.required && !(partial || optional)) {
+      result.required = result.required ?? [];
+      result.required.push(p);
+    }
+
     // populating JSON Schema 'definitions'
-    if (typeof metaType === 'function' && isComplexType(metaType)) {
-      const propSchema = getJsonSchema(metaType);
+    // shimks: ugly type casting; this should be replaced by logic to throw
+    // error if itemType/type is not a string or a function
+    const resolvedType = resolveType(metaProperty.type) as string | Function;
+    const referenceType = isArrayType(resolvedType)
+      ? // shimks: ugly type casting; this should be replaced by logic to throw
+        // error if itemType/type is not a string or a function
+        resolveType(metaProperty.itemType as string | Function)
+      : resolvedType;
+
+    if (typeof referenceType !== 'function' || isBuiltinType(referenceType)) {
+      continue;
+    }
 
-      if (propSchema && Object.keys(propSchema).length > 0) {
-        result.definitions = result.definitions || {};
+    const propOptions = {...options};
+    if (propOptions.partial !== 'deep') {
+      // Do not cascade `partial` to nested properties
+      delete propOptions.partial;
+    }
+    if (propOptions.includeRelations === true) {
+      // Do not cascade `includeRelations` to nested properties
+      delete propOptions.includeRelations;
+    }
+    // `title` is the unique identity of a schema,
+    // it should be removed from the `options`
+    // when generating the relation or property schemas
+    delete propOptions.title;
 
-        // delete nested definition
-        if (propSchema.definitions) {
-          for (const key in propSchema.definitions) {
-            result.definitions[key] = propSchema.definitions[key];
-          }
-          delete propSchema.definitions;
-        }
+    const propSchema = getJsonSchema(referenceType, propOptions);
 
-        result.definitions[metaType.name] = propSchema;
+    // JSONSchema6Definition allows both boolean and JSONSchema6 types
+    if (typeof result.properties[p] !== 'boolean') {
+      const prop = result.properties[p] as JsonSchema;
+      const propTitle = propSchema.title ?? referenceType.name;
+      const targetRef = {$ref: `#/definitions/${propTitle}`};
+
+      if (prop.type === 'array' && prop.items) {
+        // Update $ref for array type
+        prop.items = targetRef;
+      } else {
+        result.properties[p] = targetRef;
       }
+      includeReferencedSchema(propTitle, propSchema);
     }
+  }
 
-    // handling 'required' metadata
-    if (metaProperty.required) {
-      result.required = result.required || [];
-      result.required.push(p);
+  result.additionalProperties = meta.settings.strict === false;
+  debug('  additionalProperties?', result.additionalProperties);
+
+  if (options.includeRelations) {
+    for (const r in meta.relations) {
+      result.properties = result.properties ?? {};
+      const relMeta = meta.relations[r];
+      const targetType = resolveType(relMeta.target);
+
+      // `title` is the unique identity of a schema,
+      // it should be removed from the `options`
+      // when generating the relation or property schemas
+      const targetOptions = {...options};
+      delete targetOptions.title;
+
+      const targetSchema = getJsonSchema(targetType, targetOptions);
+      const targetRef = {$ref: `#/definitions/${targetSchema.title}`};
+      const propDef = getNavigationalPropertyForRelation(relMeta, targetRef);
+
+      result.properties[relMeta.name] =
+        result.properties[relMeta.name] || propDef;
+      includeReferencedSchema(targetSchema.title!, targetSchema);
+    }
+  }
+
+  function includeReferencedSchema(name: string, schema: JsonSchema) {
+    if (!schema || !Object.keys(schema).length) return;
+
+    // promote nested definition to the top level
+    if (result !== schema?.definitions) {
+      for (const key in schema.definitions) {
+        if (key === title) continue;
+        result.definitions = result.definitions ?? {};
+        result.definitions[key] = schema.definitions[key];
+      }
+      delete schema.definitions;
     }
+
+    if (result !== schema) {
+      result.definitions = result.definitions ?? {};
+      result.definitions[name] = schema;
+    }
+  }
+
+  if (meta.jsonSchema) {
+    Object.assign(result, meta.jsonSchema);
   }
   return result;
 }