@vkontakte/api-schema-typescript-generator 0.9.0 → 0.13.0

package/src/generators/APITypingsGenerator.ts

@@ -1,10 +1,11 @@
+import * as Schema from '../types/schema';
 import {
   Dictionary,
-  JSONSchemaMethodInfoInterface,
-  JSONSchemaMethodsDefinitionsInterface,
   ObjectType,
   RefsDictionary,
 } from '../types';
+import { generateEnumAsUnionType } from './enums';
+import { normalizeMethodInfo } from './methods';
 import { SchemaObject } from './SchemaObject';
 import {
   getInterfaceName, getMethodSection, getObjectNameByRef,
@@ -14,7 +15,7 @@ import {
 } from '../helpers';
 import { CodeBlocksArray, GeneratorResultInterface } from './BaseCodeBlock';
 import { TypeCodeBlock, TypeScriptCodeTypes } from './TypeCodeBlock';
-import { arrayToMap, isObject, sortArrayAlphabetically, uniqueArray } from '../utils';
+import { isObject, sortArrayAlphabetically, uniqueArray } from '../utils';
 import {
   baseAPIParamsInterfaceName,
   baseBoolIntRef,
@@ -25,7 +26,7 @@ import {
 import path from 'path';
 import { CommentCodeBlock } from './CommentCodeBlock';
 import { consoleLogError, consoleLogErrorAndExit, consoleLogInfo } from '../log';
-import { generateImportsBlock, generateStandaloneEnum } from '../generator';
+import { generateImportsBlock } from '../generator';
 import { generateTypeString } from './typeString';
 
 interface APITypingsGeneratorOptions {
@@ -43,7 +44,7 @@ interface APITypingsGeneratorOptions {
    */
   methodsPattern: string;
 
-  methodsDefinitions: JSONSchemaMethodsDefinitionsInterface;
+  methodsDefinitions: Schema.API;
   objects: Dictionary<SchemaObject>;
   responses: Dictionary<SchemaObject>;
 }
@@ -55,7 +56,7 @@ export class APITypingsGenerator {
     this.methodsPattern = prepareMethodsPattern(options.methodsPattern);
 
     this.methodsDefinitions = options.methodsDefinitions;
-    this.methodsList = options.methodsDefinitions.methods;
+    this.methodsList = options.methodsDefinitions.methods || [];
     this.objects = this.convertJSONSchemaDictionary(options.objects);
     this.responses = this.convertJSONSchemaDictionary(options.responses);
 
@@ -78,8 +79,8 @@ export class APITypingsGenerator {
   outDirPath!: APITypingsGeneratorOptions['outDirPath'];
   methodsPattern!: Dictionary<boolean>;
 
-  methodsDefinitions!: JSONSchemaMethodsDefinitionsInterface;
-  methodsList!: JSONSchemaMethodsDefinitionsInterface['methods'];
+  methodsDefinitions!: Schema.API;
+  methodsList!: NonNullable<Schema.API['methods']>;
   objects!: Dictionary<SchemaObject>;
   responses!: Dictionary<SchemaObject>;
 
@@ -117,7 +118,7 @@ export class APITypingsGenerator {
     this.resultFiles[path] = content;
   }
 
-  private appendToFileMap(section: string, imports: Dictionary<boolean>, codeBlocks: CodeBlocksArray) {
+  private appendToFileMap(section: string, imports: RefsDictionary, codeBlocks: CodeBlocksArray) {
     const methodFile = this.methodFilesMap[section] || {
       imports: {},
       codeBlocks: [],
@@ -150,10 +151,11 @@ export class APITypingsGenerator {
       if (allOfItem.ref && !this.visitedRefs[allOfItem.ref]) {
         this.visitedRefs[allOfItem.ref] = true;
         const refName = allOfItem.ref;
-        const objectName = getObjectNameByRef(refName);
-        allOfItem = this.objects[objectName];
 
-        if (!allOfItem) {
+        const tempAllOfItem = this.getObjectByRef(refName);
+        if (tempAllOfItem) {
+          allOfItem = tempAllOfItem;
+        } else {
           consoleLogErrorAndExit(`${refName} ref not found`);
         }
       }
@@ -180,11 +182,10 @@ export class APITypingsGenerator {
         if (allOfItem.properties) {
           additionalProperties = allOfItem.properties;
         } else if (allOfItem.ref) {
-          const objectName = getObjectNameByRef(allOfItem.ref);
-          const refObject = this.objects[objectName];
-
+          const refObject = this.getObjectByRef(allOfItem.ref);
           if (!refObject) {
             consoleLogErrorAndExit(`${object.name} ref object in allOf is not found`);
+            return;
           }
 
           additionalProperties = this.getObjectProperties(refObject, deep + 1);
@@ -206,7 +207,7 @@ export class APITypingsGenerator {
     }
   }
 
-  /*
+  /**
    * Filter properties with same name
    * If an object uses allOf, some nested objects may have the same properties
    */
@@ -224,11 +225,10 @@ export class APITypingsGenerator {
   }
 
   private getObjectInterfaceCode(object: SchemaObject): GeneratorResultInterface | false {
-    let imports: Dictionary<boolean> = {};
+    let imports: RefsDictionary = {};
     let codeBlocks: CodeBlocksArray = [];
 
     const properties = this.getObjectProperties(object);
-    const requiredProperties = arrayToMap(object.required);
 
     const codeBlock = new TypeCodeBlock({
       type: TypeScriptCodeTypes.Interface,
@@ -249,7 +249,9 @@ export class APITypingsGenerator {
         value,
         codeBlocks: newCodeBlocks,
         description,
-      } = generateTypeString(property, this.objects);
+      } = generateTypeString(property, this.objects, {
+        objectParentName: object.name,
+      });
 
       imports = { ...imports, ...newImports };
       codeBlocks = [...codeBlocks, ...newCodeBlocks];
@@ -258,7 +260,7 @@ export class APITypingsGenerator {
         name: property.name,
         description: [property.description, description].join(newLineChar),
         value,
-        isRequired: isPatternProperty(property.name) || requiredProperties[property.name],
+        isRequired: isPatternProperty(property.name) || property.isRequired,
       });
     });
 
@@ -278,7 +280,7 @@ export class APITypingsGenerator {
     }
 
     if (object.enum) {
-      const { codeBlocks } = generateStandaloneEnum(object);
+      const { codeBlocks } = generateEnumAsUnionType(object);
 
       return {
         codeBlocks: codeBlocks,
@@ -348,10 +350,14 @@ export class APITypingsGenerator {
     this.generateObjectsFromImports(imports);
   }
 
+  private getObjectByRef(ref: string): SchemaObject | undefined {
+    const refName = getObjectNameByRef(ref);
+    return this.objects[refName];
+  }
+
   private generateObjectsFromRefs(refs: RefsDictionary): void {
     Object.keys(refs).forEach((ref) => {
-      const refName = getObjectNameByRef(ref);
-      const refObject = this.objects[refName];
+      const refObject = this.getObjectByRef(ref);
       if (!refObject) {
         consoleLogInfo(`"${ref}" ref is not found`);
         return;
@@ -361,10 +367,9 @@ export class APITypingsGenerator {
     });
   }
 
-  private generateObjectsFromImports(imports: Dictionary<boolean>) {
+  private generateObjectsFromImports(imports: RefsDictionary) {
     Object.keys(imports).forEach((ref) => {
-      const refName = getObjectNameByRef(ref);
-      const refObject = this.objects[refName];
+      const refObject = this.getObjectByRef(ref);
       if (!refObject) {
         consoleLogInfo(`"${ref}" ref is not found`);
         return;
@@ -374,52 +379,11 @@ export class APITypingsGenerator {
     });
   }
 
-  private generateMethodParams(methodInfo: JSONSchemaMethodInfoInterface) {
+  private generateMethodParams(methodInfo: SchemaObject) {
     const section = getMethodSection(methodInfo.name);
     const interfaceName = `${methodInfo.name} params`;
 
-    const parametersRaw = Array.isArray(methodInfo.parameters) ? methodInfo.parameters : [];
-    const requiredParams = parametersRaw.reduce<Dictionary<boolean>>((acc, param) => {
-      if (param.required) {
-        acc[param.name] = true;
-      }
-      return acc;
-    }, {});
-
-    const properties = parametersRaw.map((paramRaw) => {
-      paramRaw = { ...paramRaw };
-
-      // For method params "boolean" type means 1 or 0
-      // Real "false" boolean value will be detected by API as true
-      if (paramRaw.type === 'boolean') {
-        delete paramRaw.type;
-        paramRaw.$ref = baseBoolIntRef;
-      }
-
-      // For parameters of the "array" type, VK API still accepts only a comma-separated string
-      // This may change in the future when the VK API starts accepting a json body
-      if (paramRaw.type === 'array') {
-        paramRaw.type = 'string';
-
-        if (!paramRaw.description) {
-          paramRaw.description = '';
-        }
-
-        if (paramRaw.items) {
-          if (paramRaw.items.$ref) {
-            this.generateObjectsFromRefs({
-              [paramRaw.items.$ref]: true,
-            });
-
-            paramRaw.description += newLineChar.repeat(2) + paramRaw.items.$ref;
-          }
-        }
-      }
-
-      return new SchemaObject(paramRaw.name, paramRaw, interfaceName);
-    });
-
-    let imports: Dictionary<boolean> = {};
+    let imports: RefsDictionary = {};
     let codeBlocks: CodeBlocksArray = [];
 
     const codeBlock = new TypeCodeBlock({
@@ -430,12 +394,12 @@ export class APITypingsGenerator {
       properties: [],
     });
 
-    properties.forEach((property) => {
+    methodInfo.parameters.forEach((property) => {
       const {
         imports: newImports,
         value,
         codeBlocks: newCodeBlocks,
-      } = generateTypeString(property, this.objects, { skipEnumNamesConstant: true });
+      } = generateTypeString(property, this.objects, { needEnumNamesConstant: false });
 
       imports = { ...imports, ...newImports };
       codeBlocks = [...codeBlocks, ...newCodeBlocks];
@@ -444,7 +408,7 @@ export class APITypingsGenerator {
         name: property.name,
         description: property.description,
         value,
-        isRequired: requiredParams[property.name],
+        isRequired: property.isRequired,
       });
     });
 
@@ -452,24 +416,22 @@ export class APITypingsGenerator {
     this.generateObjectsFromImports(imports);
   }
 
-  private getResponseObjectRef(object: SchemaObject): SchemaObject | undefined {
-    const objectName = getObjectNameByRef(object.ref);
+  private getResponseObjectRef(ref: string): SchemaObject | undefined {
+    const objectName = getObjectNameByRef(ref);
 
     if (this.responses[objectName]) {
       return this.responses[objectName];
-    } else if (this.objects[objectName]) {
-      return this.objects[objectName];
     }
 
-    return undefined;
+    return this.getObjectByRef(ref);
   }
 
   private getObjectCodeBlockAsType(object: SchemaObject): GeneratorResultInterface | false {
     let codeBlocks: CodeBlocksArray = [];
-    let imports: Dictionary<boolean> = {};
+    let imports: RefsDictionary = {};
 
     if (object.enum) {
-      const { codeBlocks: newCodeBlocks } = generateStandaloneEnum(object);
+      const { codeBlocks: newCodeBlocks } = generateEnumAsUnionType(object);
       codeBlocks = [
         ...newCodeBlocks,
       ];
@@ -501,38 +463,36 @@ export class APITypingsGenerator {
   }
 
   private getResponseCodeBlockAsType(object: SchemaObject, response: SchemaObject): GeneratorResultInterface | false {
-    let codeBlocks: CodeBlocksArray = [];
-    let imports: Dictionary<boolean> = {};
+    const {
+      imports,
+      value,
+      codeBlocks,
+      description,
+    } = generateTypeString(response, this.objects, {
+      objectParentName: ' ', // TODO: Refactor
+    });
 
-    if (response.enum) {
-      const { codeBlocks: newCodeBlocks } = generateStandaloneEnum(response);
-      codeBlocks = [
-        ...newCodeBlocks,
-      ];
-    } else {
-      const { imports: newImports, value, codeBlocks: newCodeBlocks } = generateTypeString(response, this.objects);
-      const codeBlock = new TypeCodeBlock({
-        type: TypeScriptCodeTypes.Type,
-        refName: object.name,
-        interfaceName: getInterfaceName(object.name),
-        description: object.description,
-        needExport: true,
-        properties: [],
-        value,
-      });
+    const codeBlock = new TypeCodeBlock({
+      type: TypeScriptCodeTypes.Type,
+      refName: object.name,
+      interfaceName: getInterfaceName(object.name),
+      description: [
+        object.description,
+        description || '',
+      ].join(newLineChar),
+      needExport: true,
+      properties: [],
+      value,
+    });
 
-      imports = newImports;
-      codeBlocks = [
+    return {
+      codeBlocks: [
         ...codeBlocks,
-        ...newCodeBlocks,
         codeBlock,
-      ];
-    }
-
-    return {
-      codeBlocks,
+      ],
       imports,
       value: '',
+      description,
     };
   }
 
@@ -549,59 +509,31 @@ export class APITypingsGenerator {
     };
 
     const objectName = getObjectNameByRef(object.ref);
-    let response: SchemaObject | undefined;
-
     if (nonBuildableRefs[objectName]) {
       return this.getObjectCodeBlockAsType(object);
-    } else if (this.responses[objectName]) {
-      response = this.responses[objectName];
-
-      const { properties = [] } = response;
-      const responseProperty = properties.find((property) => property.name === 'response');
-
-      if (responseProperty) {
-        response = responseProperty;
-        if (response.ref) {
-          return this.getResponseCodeBlockAsType(object, response);
-        }
-      } else {
-        // Maybe this is a crutch?
-        response.properties.forEach((property) => {
-          if (response && property.parentObjectName === response.name) {
-            response = property;
-            return true;
-          }
-
-          return false;
-        });
-      }
-    } else if (this.objects[objectName]) {
-      response = this.objects[objectName];
+    }
 
-      if (object.ref) {
-        return this.getResponseCodeBlockAsType(object, object);
-      }
+    let response = this.getResponseObjectRef(object.ref);
+    if (!response) {
+      consoleLogError(`response schema object "${object.name}" has no response`, object);
+      return false;
     }
 
-    // @ts-ignore
-    while (response && response.ref) {
-      response = this.getResponseObjectRef(response);
+    // VK API JSON Schema specific heuristic
+    if (response.properties.length === 1 && response.properties[0].name === 'response') {
+      response = response.properties[0];
     }
 
-    if (!response) {
-      consoleLogErrorAndExit(`"${object.name}" has no response`);
-      return false;
+    if (response.ref) {
+      return this.getResponseCodeBlockAsType(object, response);
     }
 
-    response.originalName = response.name;
+    response = response.clone();
     response.setName(object.name);
 
-    let result: GeneratorResultInterface | false;
-
     switch (response.type) {
       case 'object':
-        result = this.getObjectInterfaceCode(response);
-        break;
+        return this.getObjectInterfaceCode(response);
 
       case 'integer':
       case 'string':
@@ -610,11 +542,9 @@ export class APITypingsGenerator {
         return this.getResponseCodeBlockAsType(object, response);
 
       default:
-        consoleLogErrorAndExit(response.name, 'unknown type');
+        consoleLogErrorAndExit(response.name, 'unknown type', response.type);
         return false;
     }
-
-    return result;
   }
 
   public generateResponse(section: string, response: SchemaObject) {
@@ -629,39 +559,47 @@ export class APITypingsGenerator {
     this.generateObjectsFromImports(imports);
   }
 
-  private generateMethodParamsAndResponses(methodInfo: JSONSchemaMethodInfoInterface) {
-    const { name } = methodInfo;
-    const section = getMethodSection(name);
+  private generateMethodParamsAndResponses(method: Schema.Method) {
+    const { name: methodName } = method;
+    const section = getMethodSection(methodName);
 
-    if (!isObject(methodInfo.responses)) {
-      consoleLogErrorAndExit(`"${name}" "responses" field is not an object.`);
+    if (!isObject(method.responses)) {
+      consoleLogErrorAndExit(`"${methodName}" "responses" field is not an object.`);
       return;
     }
 
-    if (Object.keys(methodInfo.responses).length === 0) {
-      consoleLogErrorAndExit(`"${name}" "responses" field is empty.`);
+    if (Object.keys(method.responses).length === 0) {
+      consoleLogErrorAndExit(`"${methodName}" "responses" field is empty.`);
       return;
     }
 
     // Comment with method name for visual sections in file
-    const methodNameComment = new CommentCodeBlock([name]);
-    if (methodInfo.description) {
+    const methodNameComment = new CommentCodeBlock([methodName]);
+    if (method.description) {
       methodNameComment.appendLines([
         '',
-        methodInfo.description,
+        method.description,
       ]);
     }
     this.appendToFileMap(section, {}, [methodNameComment]);
 
-    this.generateMethodParams(methodInfo);
+    const {
+      method: normalizedMethod,
+      parameterRefs,
+    } = normalizeMethodInfo(method);
+
+    method = normalizedMethod;
+    this.generateObjectsFromRefs(parameterRefs);
+
+    this.generateMethodParams(new SchemaObject(method.name, method));
 
-    Object.entries(methodInfo.responses).forEach(([responseName, responseObject]) => {
-      if (this.ignoredResponses[name] && this.ignoredResponses[name][responseName]) {
+    Object.entries(method.responses).forEach(([responseName, responseObject]) => {
+      if (this.ignoredResponses[methodName] && this.ignoredResponses[methodName][responseName]) {
         return;
       }
 
-      responseObject.name = `${name}_${responseName}`;
-      this.generateResponse(section, new SchemaObject(responseObject.name, responseObject));
+      const name = `${methodName}_${responseName}`;
+      this.generateResponse(section, new SchemaObject(name, responseObject));
     });
   }
 

package/src/generators/BaseCodeBlock.ts

@@ -1,4 +1,4 @@
-import { Dictionary } from '../types';
+import { RefsDictionary } from '../types';
 
 export abstract class BaseCodeBlock {
   toString(): string {
@@ -10,7 +10,7 @@ export type CodeBlocksArray = BaseCodeBlock[];
 
 export interface GeneratorResultInterface {
   codeBlocks: CodeBlocksArray;
-  imports: Dictionary<boolean>;
+  imports: RefsDictionary;
   value: string;
   description?: string;
 }

package/src/generators/SchemaObject.ts

@@ -1,3 +1,4 @@
+import { EnumLikeArray } from '../types';
 import { isObject, isString } from '../utils';
 import {
   transformPatternPropertyName,
@@ -45,6 +46,10 @@ export class SchemaObject {
       this.required = [];
     }
 
+    if (typeof object.required === 'boolean') {
+      this.isRequired = object.required;
+    }
+
     this.properties = [];
 
     if (object.properties) {
@@ -53,6 +58,14 @@ export class SchemaObject {
       });
     }
 
+    this.parameters = [];
+
+    if (Array.isArray(object.parameters)) {
+      object.parameters.forEach((parameter: any) => {
+        this.parameters.push(new SchemaObject(parameter.name, parameter, `${name} param`));
+      });
+    }
+
     if (object.patternProperties) {
       Object.entries(object.patternProperties).forEach(([propertyName, property]: [string, any]) => {
         this.properties.push(new SchemaObject(transformPatternPropertyName(propertyName), property, name));
@@ -70,25 +83,20 @@ export class SchemaObject {
     if (Array.isArray(object.allOf) && object.allOf.length > 0) {
       this.allOf = object.allOf.map((item: any) => new SchemaObject(name, item));
     }
-
-    // Crutch
-    // if (this.oneOf && this.oneOf.length === 1) {
-    //   this.allOf = [this.oneOf[0]];
-    //   this.oneOf = undefined;
-    // }
   }
 
   name!: string;
-  originalName!: string;
   parentObjectName!: string;
 
   type!: string | string[];
-  readonly description!: string;
-  readonly ref!: string;
+  description!: string;
+  ref!: string;
   required!: string[];
-  readonly enum!: Array<string | number>;
-  readonly enumNames!: Array<string | number>;
+  isRequired!: boolean;
+  readonly enum!: EnumLikeArray;
+  readonly enumNames!: EnumLikeArray;
   properties!: SchemaObject[];
+  parameters!: SchemaObject[];
   readonly items!: SchemaObject;
   readonly oneOf!: SchemaObject[];
   readonly allOf!: SchemaObject[];
@@ -97,7 +105,13 @@ export class SchemaObject {
     this.name = name;
 
     if (Array.isArray(this.properties)) {
-      this.properties.forEach((property) => property.parentObjectName = name);
+      this.properties.forEach((property) => {
+        property.parentObjectName = name;
+      });
     }
   }
+
+  public clone() {
+    return Object.assign(Object.create(Object.getPrototypeOf(this)), this) as NonNullable<SchemaObject>;
+  }
 }

package/src/generators/TypeCodeBlock.ts

@@ -1,8 +1,8 @@
 import { BaseCodeBlock } from './BaseCodeBlock';
 import { newLineChar } from '../constants';
-import { areQuotesNeededForProperty } from '../helpers';
+import { areQuotesNeededForProperty, joinCommentLines } from '../helpers';
 import { consoleLogErrorAndExit } from '../log';
-import { quoteJavaScriptValue, trimArray, trimStringDoubleSpaces } from '../utils';
+import { quoteJavaScriptValue, trimStringDoubleSpaces } from '../utils';
 
 export enum TypeScriptCodeTypes {
   Interface = 'interface',
@@ -89,15 +89,11 @@ export class TypeCodeBlock extends BaseCodeBlock {
         `  ${quoteChar}${property.name}${quoteChar}${divider} ${value}${lineEnd}`,
       ];
 
-      const propertyDescriptionLines = trimArray((property.description || '').trim().split(newLineChar));
-      if (propertyDescriptionLines.length) {
-        propertyCode.unshift([
-          '  /**',
-          ...propertyDescriptionLines.map((line) => {
-            return '   ' + `* ${line}`.trim();
-          }),
-          '   */',
-        ].join(newLineChar));
+      if (property.description) {
+        const commentLines = joinCommentLines(2, property.description);
+        if (commentLines.length) {
+          propertyCode.unshift(commentLines.join(newLineChar));
+        }
       }
 
       return propertyCode.join(newLineChar);
@@ -112,18 +108,17 @@ export class TypeCodeBlock extends BaseCodeBlock {
     let before: string[] = [];
     let code = '';
 
+    if (this.refName) {
+      before.push(`// ${this.refName}`);
+    }
+
     if (this.description) {
       before = [
-        '/**',
-        ` * ${this.description}`,
-        ' */',
+        ...before,
+        ...joinCommentLines(0, this.description),
       ];
     }
 
-    if (this.refName) {
-      before.push(`// ${this.refName}`);
-    }
-
     switch (this.type) {
       case TypeScriptCodeTypes.Interface: {
         if (!hasProperties) {