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

package/src/generators/enums.ts

@@ -0,0 +1,150 @@
+import { newLineChar } from '../constants';
+import { getEnumPropertyName, getInterfaceName, joinOneOfValues } from '../helpers';
+import { RefsDictionaryType } from '../types';
+import { quoteJavaScriptValue } from '../utils';
+import { CodeBlocksArray, GeneratorResultInterface } from './BaseCodeBlock';
+import { SchemaObject } from './SchemaObject';
+import { TypeCodeBlock, TypeScriptCodeTypes } from './TypeCodeBlock';
+
+export function isNumericEnum(object: SchemaObject): boolean {
+  return object.enum.some((value) => !!+value);
+}
+
+export function getEnumNamesIdentifier(name: string) {
+  if (!name) {
+    throw new Error('[getEnumNamesIdentifier] empty name');
+  }
+
+  return `${name} enumNames`.trim();
+}
+
+export function generateEnumConstantObject(object: SchemaObject, objectName: string, enumNames: Array<string | number>) {
+  const enumInterfaceName = getInterfaceName(objectName);
+
+  const codeBlock = new TypeCodeBlock({
+    type: TypeScriptCodeTypes.ConstantObject,
+    refName: objectName,
+    interfaceName: enumInterfaceName,
+    needExport: true,
+    properties: [],
+  });
+
+  enumNames.forEach((name, index) => {
+    codeBlock.addProperty({
+      name: getEnumPropertyName(name.toString()),
+      value: object.enum[index],
+      wrapValue: true,
+    });
+  });
+
+  return codeBlock;
+}
+
+/**
+ * Generates enum as union type with constant object if necessary
+ */
+export function generateEnumAsUnionType(object: SchemaObject): GeneratorResultInterface {
+  const { codeBlocks, value, description } = generateInlineEnum(object, {
+    refName: getEnumNamesIdentifier(object.name),
+  });
+
+  const unionType = new TypeCodeBlock({
+    type: TypeScriptCodeTypes.Type,
+    refName: object.name,
+    interfaceName: getInterfaceName(object.name),
+    description: [
+      object.description,
+      description,
+    ].join(newLineChar),
+    needExport: true,
+    properties: [],
+    value,
+  });
+
+  codeBlocks.push(unionType);
+
+  return {
+    codeBlocks,
+    imports: {},
+    value: '',
+  };
+}
+
+function getEnumNames(object: SchemaObject) {
+  let { enumNames } = object;
+
+  const isNumeric = isNumericEnum(object);
+  const needEnumNamesDescription = !!enumNames;
+
+  if (!enumNames) {
+    const canUseEnumNames = !isNumeric;
+    if (canUseEnumNames) {
+      enumNames = [...object.enum];
+    }
+  }
+
+  return {
+    isNumericEnum: isNumeric,
+    needEnumNamesDescription,
+    enumNames: Array.isArray(enumNames) && enumNames.length ? enumNames : undefined,
+  };
+}
+
+interface GenerateInlineEnumOptions {
+  objectParentName?: string;
+  needEnumNamesConstant?: boolean;
+  refType?: RefsDictionaryType.Generate;
+  refName?: string;
+}
+
+export function generateInlineEnum(object: SchemaObject, options: GenerateInlineEnumOptions = {}): GeneratorResultInterface {
+  const {
+    isNumericEnum,
+    enumNames,
+    needEnumNamesDescription,
+  } = getEnumNames(object);
+
+  options = {
+    needEnumNamesConstant: isNumericEnum,
+    ...options,
+  };
+
+  const codeBlocks: CodeBlocksArray = [];
+  let descriptionLines: string[] = [];
+
+  if (enumNames) {
+    if (needEnumNamesDescription) {
+      if (isNumericEnum && options.refName) {
+        descriptionLines.push('');
+        descriptionLines.push('@note This enum have auto-generated constant with keys and values');
+        descriptionLines.push(`@see ${getInterfaceName(options.refName)}`);
+      }
+
+      descriptionLines.push('');
+
+      enumNames.forEach((name, index) => {
+        const value = object.enum[index];
+
+        if (needEnumNamesDescription) {
+          descriptionLines.push(`\`${value}\` — ${name}`);
+        }
+      });
+    }
+
+    if (isNumericEnum && options.needEnumNamesConstant) {
+      const enumName = getEnumNamesIdentifier(`${options.objectParentName || ''} ${object.name}`);
+
+      const codeBlock = generateEnumConstantObject(object, enumName, enumNames);
+      codeBlocks.push(codeBlock);
+    }
+  }
+
+  const values = object.enum.map((value) => quoteJavaScriptValue(value));
+
+  return {
+    codeBlocks,
+    imports: {},
+    value: joinOneOfValues(values, true),
+    description: descriptionLines.join(newLineChar),
+  };
+}

package/src/generators/methods.ts

@@ -0,0 +1,49 @@
+import { baseBoolIntRef, newLineChar } from '../constants';
+import { getInterfaceName, getObjectNameByRef } from '../helpers';
+import { RefsDictionary, RefsDictionaryType } from '../types';
+import * as Schema from '../types/schema';
+
+interface NormalizeMethodInfoResult {
+  method: Schema.Method;
+  parameterRefs: RefsDictionary;
+}
+
+/**
+ * Patches for method definition
+ */
+export function normalizeMethodInfo(method: Schema.Method): NormalizeMethodInfoResult {
+  const parameterRefs: RefsDictionary = {};
+
+  method.parameters?.forEach((parameter) => {
+    // For method params "boolean" type means 1 or 0
+    // Real "false" boolean value will be detected by API as true
+    if (parameter.type === 'boolean') {
+      delete parameter.type;
+      parameter.$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 (parameter.type === 'array') {
+      parameter.type = 'string';
+    }
+
+    if (!parameter.description) {
+      parameter.description = '';
+    }
+
+    if (parameter.items && parameter.items.$ref) {
+      const ref = parameter.items?.$ref;
+      parameterRefs[ref] = RefsDictionaryType.Generate;
+
+      parameter.description += newLineChar.repeat(2) + [
+        `@see ${getInterfaceName(getObjectNameByRef(ref))} (${ref})`,
+      ].join(newLineChar);
+    }
+  });
+
+  return {
+    method,
+    parameterRefs,
+  };
+}

package/src/generators/typeString.ts

@@ -1,7 +1,3 @@
-import { CodeBlocksArray, GeneratorResultInterface } from './BaseCodeBlock';
-import { SchemaObject } from './SchemaObject';
-import { Dictionary } from '../types';
-import { getInterfaceName, getObjectNameByRef, joinOneOfValues, resolvePrimitiveTypesArray } from '../helpers';
 import {
   baseBoolIntRef,
   baseOkResponseRef,
@@ -10,14 +6,32 @@ import {
   PropertyType,
   scalarTypes,
 } from '../constants';
-import { isString } from '../utils';
+import { generateInlineEnum } from './enums';
+import {
+  formatArrayDepth,
+  getInterfaceName,
+  getObjectNameByRef,
+  joinOneOfValues,
+  resolvePrimitiveTypesArray,
+} from '../helpers';
 import { consoleLogErrorAndExit } from '../log';
-import { generateInlineEnum } from '../generator';
+import { Dictionary, RefsDictionary, RefsDictionaryType } from '../types';
+import { isString } from '../utils';
+import { CodeBlocksArray, GeneratorResultInterface } from './BaseCodeBlock';
+import { SchemaObject } from './SchemaObject';
+
+interface GenerateTypeStringOptions {
+  objectParentName?: string;
+  /**
+   * Determines whether enums will be inline to type value or them will be as separate interface block
+   */
+  needEnumNamesConstant?: boolean;
+}
 
 function generateBaseType(object: SchemaObject, options: GenerateTypeStringOptions): GeneratorResultInterface {
   let codeBlocks: CodeBlocksArray = [];
   let typeString = 'any /* default type */';
-  let imports: Record<string, boolean> = {};
+  let imports: RefsDictionary = {};
   let description: string | undefined = '';
 
   if (object.enum) {
@@ -29,7 +43,7 @@ function generateBaseType(object: SchemaObject, options: GenerateTypeStringOptio
       // TODO: Refactor
       // section_object_name -> property_name -> items => section_object_name_property_name_items enumNames
       objectParentName: options.objectParentName || object.parentObjectName,
-      skipEnumNamesConstant: options.skipEnumNamesConstant,
+      needEnumNamesConstant: options.needEnumNamesConstant,
     });
 
     typeString = value;
@@ -57,14 +71,6 @@ function generateBaseType(object: SchemaObject, options: GenerateTypeStringOptio
   };
 }
 
-interface GenerateTypeStringOptions {
-  objectParentName?: string;
-  /**
-   * Determines whether enums will be inline to type value or them will be as separate interface block
-   */
-  skipEnumNamesConstant?: boolean;
-}
-
 export function generateTypeString(
   object: SchemaObject,
   objects: Dictionary<SchemaObject>,
@@ -72,9 +78,14 @@ export function generateTypeString(
 ): GeneratorResultInterface {
   let codeBlocks: CodeBlocksArray = [];
   let typeString = 'any /* default type */';
-  let imports: Dictionary<boolean> = {};
+  let imports: RefsDictionary = {};
   let description: string | undefined = '';
 
+  options = {
+    needEnumNamesConstant: true,
+    ...options,
+  };
+
   if (object.oneOf) {
     const values = object.oneOf.map((oneOfObject) => {
       const { value, imports: newImports } = generateTypeString(oneOfObject, objects);
@@ -104,8 +115,8 @@ export function generateTypeString(
         consoleLogErrorAndExit(`Error, object for "${refName}" ref is not found.`);
       }
 
-      imports[refName] = true;
-      typeString = getInterfaceName(refName) + '[]'.repeat(depth);
+      imports[refName] = RefsDictionaryType.GenerateAndImport;
+      typeString = formatArrayDepth(getInterfaceName(refName), depth);
     } else {
       const {
         value,
@@ -118,18 +129,11 @@ export function generateTypeString(
         objectParentName: object.parentObjectName,
       });
 
-      if (value.endsWith('\'') || value.includes('|')) {
-        typeString = `Array<${value}>` + '[]'.repeat(depth - 1); // Need decrement depth value because of Array<T> has its own depth
-      } else {
-        typeString = value + '[]'.repeat(depth);
-      }
-
+      typeString = formatArrayDepth(value, depth);
       description = newDescription;
       imports = { ...imports, ...newImports };
       codeBlocks = [...codeBlocks, ...newCodeBlocks];
     }
-  } else if (object.type) {
-    return generateBaseType(object, options);
   } else if (object.ref) {
     const refName = getObjectNameByRef(object.ref);
 
@@ -145,13 +149,12 @@ export function generateTypeString(
 
       default: {
         const refObject = objects[refName];
-
         if (!refObject) {
           consoleLogErrorAndExit(`Error, object for "${refName}" ref is not found.`);
         }
 
         if (refObject.enum) {
-          imports[refName] = true;
+          imports[refName] = RefsDictionaryType.GenerateAndImport;
           typeString = getInterfaceName(refName);
         } else if (refObject.oneOf) {
           const values = refObject.oneOf.map((oneOfObject) => {
@@ -164,11 +167,13 @@ export function generateTypeString(
         } else if (isString(refObject.type) && scalarTypes[refObject.type] && !refObject.ref) {
           typeString = scalarTypes[refObject.type];
         } else {
-          imports[refName] = true;
+          imports[refName] = RefsDictionaryType.GenerateAndImport;
           typeString = getInterfaceName(refName);
         }
       }
     }
+  } else if (object.type) {
+    return generateBaseType(object, options);
   }
 
   return {

package/src/helpers.ts

@@ -1,6 +1,6 @@
 import fs, { promises as fsPromises } from 'fs';
 import path from 'path';
-import { capitalizeFirstLetter } from './utils';
+import { capitalizeFirstLetter, trimArray } from './utils';
 import { newLineChar, primitiveTypes, spaceChar } from './constants';
 import { Dictionary } from './types';
 import { consoleLogErrorAndExit } from './log';
@@ -125,6 +125,39 @@ export function transformPatternPropertyName(name: string): string {
   return '[key: string] /* default pattern property name */';
 }
 
+export function joinCommentLines(indent = 2, ...description: Array<string | string[]>): string[] {
+  let descriptionLines: string[] = [];
+
+  description.forEach((entry) => {
+    if (typeof entry === 'string') {
+      descriptionLines = [
+        ...descriptionLines,
+        ...trimArray((entry || '').trim().split(newLineChar)),
+      ];
+    } else if (Array.isArray(entry)) {
+      descriptionLines = [
+        ...descriptionLines,
+        ...entry,
+      ];
+    }
+  });
+
+  descriptionLines = trimArray(descriptionLines);
+  if (!descriptionLines.length) {
+    return [];
+  }
+
+  const indentSpaces = spaceChar.repeat(indent);
+
+  return [
+    `${indentSpaces}/**`,
+    ...descriptionLines.map((line) => {
+      return indentSpaces + ' ' + `* ${line}`.trim();
+    }),
+    `${indentSpaces} */`,
+  ];
+}
+
 export function joinOneOfValues(values: Array<string | number>, primitive?: boolean) {
   const joined = values.join(' | ');
 
@@ -136,6 +169,14 @@ export function joinOneOfValues(values: Array<string | number>, primitive?: bool
   }
 }
 
+export function formatArrayDepth(value: string, depth: number) {
+  if (value.endsWith('\'') || value.includes('|')) {
+    return `Array<${value}>` + '[]'.repeat(depth - 1); // Need decrement depth value because of Array<T> has its own depth
+  } else {
+    return value + '[]'.repeat(depth);
+  }
+}
+
 export function resolvePrimitiveTypesArray(types: string[]): string | null {
   const isEveryTypePrimitive = types.every((type) => !!primitiveTypes[type]);
   if (isEveryTypePrimitive) {

package/src/log.ts

@@ -6,7 +6,7 @@ function getInspectArgs(args: any[]) {
     if (typeof arg === 'object') {
       return inspect(arg, {
         showHidden: false,
-        depth: null,
+        depth: 10,
         colors: true,
       });
     } else {

package/src/types/schema.ts

@@ -0,0 +1,152 @@
+export type Format = 'json' | 'int32' | 'int64';
+
+/**
+ * Enum values text representations
+ */
+export type EnumNames = [string, ...string[]];
+
+/**
+ * This interface was referenced by `undefined`'s JSON-Schema definition
+ * via the `patternProperty` "^[a-zA-Z0-9_]+$".
+ */
+export type ResponseProperty = {
+  [k: string]: unknown;
+};
+
+/**
+ * Possible custom errors
+ */
+export type MethodErrors = Array<{
+  $ref?: string;
+}>;
+
+/**
+ * VK API declaration
+ */
+export interface API {
+  errors?: {
+    [k: string]: Error;
+  };
+  methods?: Method[];
+  definitions?: {
+    [k: string]: Response;
+  };
+  $schema?: string;
+  title?: string;
+  description?: string;
+  termsOfService?: string;
+  version?: string;
+}
+
+/**
+ * This interface was referenced by `undefined`'s JSON-Schema definition
+ * via the `patternProperty` "^[a-z][a-z0-9_]+$".
+ */
+export interface Error {
+  /**
+   * Error code
+   */
+  code: number;
+  /**
+   * Error description
+   */
+  description: string;
+  /**
+   * Array of error subcodes
+   */
+  subcodes?: ErrorSubcode[];
+  global?: boolean;
+  disabled?: boolean;
+}
+
+export interface ErrorSubcode {
+  subcode?: number;
+  description?: string;
+  $comment?: string;
+  $ref?: string;
+}
+
+export interface Method {
+  /**
+   * Method name
+   */
+  name: string;
+  /**
+   * Method description
+   */
+  description?: string;
+  timeout?: number;
+  /**
+   * Input parameters for method
+   */
+  access_token_type: Array<'open' | 'user' | 'group' | 'service'>;
+  /**
+   * Input parameters for method
+   */
+  parameters?: Parameter[];
+  /**
+   * References to response objects
+   */
+  responses: {
+    [k: string]: Response;
+  };
+  emptyResponse?: boolean;
+  errors?: MethodErrors;
+}
+
+export interface Parameter {
+  /**
+   * Parameter name
+   */
+  name: string;
+  format?: Format;
+  /**
+   * Parameter type
+   */
+  type: 'array' | 'boolean' | 'integer' | 'number' | 'string';
+  items?: {
+    $ref: string;
+  };
+  maxItems?: number;
+  minItems?: number;
+  maximum?: number;
+  minimum?: number;
+  $ref?: string;
+  enum?: [unknown, ...unknown[]];
+  enumNames?: EnumNames;
+  /**
+   * Default property value
+   */
+  default?: {
+    [k: string]: unknown;
+  };
+  required?: boolean;
+  maxLength?: number;
+  minLength?: number;
+  /**
+   * Parameter description
+   */
+  description?: string;
+}
+
+/**
+ * This interface was referenced by `undefined`'s JSON-Schema definition
+ * via the `patternProperty` "^([a-zA-Z0-9_]+)?[rR]esponse$".
+ *
+ * This interface was referenced by `undefined`'s JSON-Schema definition
+ * via the `patternProperty` "^([a-zA-Z0-9_]+)?[rR]esponse$".
+ */
+export interface Response {
+  type?: string;
+  description?: string;
+  allOf?: Response[];
+  items?: any[];
+  required?: unknown[];
+  title?: string;
+  oneOf?: unknown[];
+  $ref?: string;
+  properties?: {
+    [k: string]: ResponseProperty;
+  };
+  additionalProperties?: boolean;
+}

package/src/types.ts

@@ -2,49 +2,17 @@ export interface Dictionary<T> {
   [key: string]: T;
 }
 
-export type RefsDictionary = Dictionary<true>;
+export enum RefsDictionaryType {
+  GenerateAndImport,
+  Generate,
+}
+
+export type RefsDictionary = Record<string, RefsDictionaryType>;
+
+export type EnumLikeArray = Array<string | number>;
 
 export enum ObjectType {
   Object = 'object',
   Response = 'response',
   Params = 'params',
 }
-
-export interface JSONSchemaPropertyInterface {
-  type?: 'integer' | 'string' | 'boolean' | 'array';
-  items?: JSONSchemaPropertyInterface;
-  $ref?: string;
-  minimum?: number;
-  format?: 'uri';
-  description?: string;
-}
-
-export interface JSONSchemaObjectInterface {
-  type: 'object';
-  properties?: JSONSchemaPropertyInterface[];
-  required?: string[];
-}
-
-export interface JSONSchemaMethodParameter extends JSONSchemaPropertyInterface {
-  name: string;
-  required?: boolean;
-}
-
-export interface JSONSchemaMethodsDefinitionsInterface {
-  $schema: string;
-  version: string;
-  title: string;
-  description: string;
-  termsOfService: string;
-  methods: JSONSchemaMethodInfoInterface[];
-}
-
-export interface JSONSchemaMethodInfoInterface {
-  name: string;
-  description?: string;
-  access_token_type?: string[];
-  parameters?: JSONSchemaMethodParameter[];
-  responses: Dictionary<Dictionary<string>>;
-  errors?: Array<Dictionary<any>>;
-  emptyResponse?: boolean;
-}