Merge pull request #451 from acacode/next

Release 12.0.0

Author: js2me

CHANGELOG.md

@@ -1,5 +1,55 @@
 # next release
 
+## 12.0.0  
+
+new hooks:  
+```ts
+/** calls before parse\process route path */
+onPreBuildRoutePath: (routePath: string) => string | void;
+/** calls after parse\process route path */
+onBuildRoutePath: (data: BuildRoutePath) => BuildRoutePath | void;
+/** calls before insert path param name into string path interpolation */
+onInsertPathParam: (paramName: string, index: number, arr: BuildRouteParam[], resultRoute: string) => string | void;
+/** calls before parse any kind of schema */
+onPreParseSchema: (originalSchema: any, typeName: string, schemaType: string) => any;
+```  
+BREAKING_CHANGE: add ability to custom prefix for autofix invalid enum keys, invalid type names with nodejs options (`fixInvalidTypeNamePrefix: string`, `fixInvalidEnumKeyPrefix: string`)  
+BREAKING_CHANGE: by default all component enum schemas (even numeric) extracting as `enum` TS constructions (#344)   
+feature: ability to extract all enums from nested types\interfaces to `enum` TS construction using `--extract-enums` option (#344)   
+feature: ability to modify route path params before insert them into string (request url, #446, with using hook `onInsertPathParam`)  
+feature: (nodejs) ability to add prefix\suffix for type names and enum keys  
+```ts
+typePrefix?: string;
+typeSuffix?: string;
+enumKeyPrefix?: string;
+enumKeySuffix?: string;
+```
+feature: ability to customize resolving process of the extracting type names (`extractingOptions` nodejs option)  
+```ts
+extractingOptions = {
+  // requestBodySuffix: ["Payload", "Body", "Input"],
+  // or
+  // requestBodyNameResolver: (typeName, reservedNames) => string;
+
+  // requestParamsSuffix: ["Params"],
+  // or
+  // requestParamsNameResolver: (typeName, reservedNames) => string;
+
+  // responseBodySuffix: ["Data", "Result", "Output"],
+  // or
+  // responseBodyNameResolver: (typeName, reservedNames) => string;
+
+  // responseErrorSuffix: ["Error", "Fail", "Fails", "ErrorData", "HttpError", "BadResponse"],
+  // or
+  // responseErrorNameResolver: (typeName, reservedNames) => string;
+}
+```
+docs: update docs for `extraTemplates` option  
+fix: problem with default name of single api file (Api.ts)  
+fix: problem based with tuple types (#445)  
+fix: problem with `defaultResponseType` declaration type  
+
+
 # 11.1.3  
 
 fix: problems with `text/*` content types (axios, fetch http clients) (thanks @JochenDiekenbrock, #312, #443)  
@@ -214,7 +264,7 @@ const primitiveTypes = {
     },
     array: ({ items, ...schemaPart }, parser) => {
       const content = parser.getInlineParseContent(items);
-      return parser.checkAndAddNull(schemaPart, Ts.ArrayType(content));
+      return parser.safeAddNullToType(schemaPart, Ts.ArrayType(content));
     },
   }
 ```
@@ -456,7 +506,7 @@ Features:
 - `--type-suffix` option. Allows to set suffix for data contract name. (issue #191, thanks @the-ult)  
 - `--type-prefix` option. Allows to set prefix for data contract name. (issue #191, thanks @the-ult)  
   Examples [here](./spec/typeSuffixPrefix/schema.ts)  
-- `onFormatTypeName(usageTypeName, rawTypeName)` hook. Allow to format data contract names as you want.  
+- `onFormatTypeName(usageTypeName, rawTypeName, schemaType)` hook. Allow to format data contract names as you want.  
 
 Internal:  
 - rename and split `checkAndRenameModelName` -> `formatModelName`, `fixModelName`  

README.md

@@ -76,11 +76,12 @@ Options:
   --type-prefix <string>        data contract name prefix (default: "")
   --type-suffix <string>        data contract name suffix (default: "")
   --clean-output                clean output folder before generate api. WARNING: May cause data loss (default: false)
-  --api-class-name <string>     name of the api class
+  --api-class-name <string>     name of the api class (default: "Api")
   --patch                       fix up small errors in the swagger source definition (default: false)
   --debug                       additional information about processes inside this tool (default: false)
   --another-array-type          generate array types as Array<Type> (by default Type[]) (default: false)
   --sort-types                  sort fields and types (default: false)
+  --extract-enums               extract all enums from inline interface\type content to typescript enum construction (default: false)
   -h, --help                    display help for command
 
 Commands:
@@ -144,9 +145,20 @@ generateApi({
   generateUnionEnums: false,
   typePrefix: '',
   typeSuffix: '',
+  enumKeyPrefix: '',
+  enumKeySuffix: '',
   addReadonly: false,
+  extractingOptions: {
+    requestBodySuffix: ["Payload", "Body", "Input"],
+    requestParamsSuffix: ["Params"],
+    responseBodySuffix: ["Data", "Result", "Output"],
+    responseErrorSuffix: ["Error", "Fail", "Fails", "ErrorData", "HttpError", "BadResponse"],
+  },
+  /** allow to generate extra files based with this extra templates, see more below */
   extraTemplates: [],
-  anotherArrayType: false, 
+  anotherArrayType: false,
+  fixInvalidTypeNamePrefix: "Type",
+  fixInvalidEnumKeyPrefix: "Value", 
   codeGenConstructs: (constructs) => ({
     ...constructs,
     RecordType: (key, value) => `MyRecord<key, value>`
@@ -163,8 +175,9 @@ generateApi({
     onCreateRoute: (routeData) => {},
     onCreateRouteName: (routeNameInfo, rawRouteInfo) => {},
     onFormatRouteName: (routeInfo, templateRouteName) => {},
-    onFormatTypeName: (typeName, rawTypeName) => {},
+    onFormatTypeName: (typeName, rawTypeName, schemaType) => {},
     onInit: (configuration) => {},
+    onPreParseSchema: (originalSchema, typeName, schemaType) => {},
     onParseSchema: (originalSchema, parsedSchema) => {},
     onPrepareConfig: (currentConfiguration) => {},
   }
@@ -245,8 +258,13 @@ with `--module-name-index 0` Api class will have one property `api`
 When we change it to `--module-name-index 1` then Api class have two properties `fruits` and `vegetables`  
 
 ### **`--module-name-first-tag`**  
-This option will group your API operations based on their first tag - mirroring how the Swagger UI groups displayed operations
+This option will group your API operations based on their first tag - mirroring how the Swagger UI groups displayed operations  
 
+### `extraTemplates` (NodeJS option)  
+type `(Record<string, any> & { name: string, path: string })[]`  
+This thing allow you to generate extra ts\js files based on extra templates (one extra template for one ts\js file)   
+[Example here](https://github.com/acacode/swagger-typescript-api/tree/next/tests/spec/extra-templates)    
+ 
 
 ## `generate-templates` command    
 This command allows you to generate source templates which using with option `--templates`
@@ -433,7 +451,7 @@ generateApi({
         },
         array: (schema, parser) => {
             const content = parser.getInlineParseContent(schema.items);
-            return parser.checkAndAddNull(schema, `(${content})[]`);
+            return parser.safeAddNullToType(schema, `(${content})[]`);
         },
     })
 })

index.d.ts

@@ -106,7 +106,7 @@ interface GenerateApiParamsBase {
   /**
    * default type for empty response schema (default: "void")
    */
-  defaultResponseType?: boolean;
+  defaultResponseType?: string;
   /**
    * Ability to send HttpClient instance to Api constructor
    */
@@ -136,6 +136,22 @@ interface GenerateApiParamsBase {
   primitiveTypeConstructs?: (struct: PrimitiveTypeStruct) => Partial<PrimitiveTypeStruct>;
 
   codeGenConstructs?: (struct: CodeGenConstruct) => Partial<CodeGenConstruct>;
+
+  /** extract all enums from nested types\interfaces to `enum` construction */
+  extractEnums?: boolean;
+  /** prefix string value needed to fix invalid type names (default: 'Type') */
+  fixInvalidTypeNamePrefix?: string;
+  /** prefix string value needed to fix invalid enum keys (default: 'Value') */
+  fixInvalidEnumKeyPrefix?: string;
+  /** prefix string value for enum keys */
+  enumKeyPrefix?: string;
+  /** suffix string value for enum keys */
+  enumKeySuffix?: string;
+  /** prefix string value for type names */
+  typePrefix?: string;
+  /** suffix string value for type names */
+  typeSuffix?: string;
+  extractingOptions?: Partial<ExtractingOptions>;
 }
 
 type CodeGenConstruct = {
@@ -212,9 +228,39 @@ interface GenerateApiParamsFromSpecLiteral extends GenerateApiParamsBase {
 
 export type GenerateApiParams = GenerateApiParamsFromPath | GenerateApiParamsFromUrl | GenerateApiParamsFromSpecLiteral;
 
+type BuildRouteParam = {
+  /** {bar} */
+  $match: string;
+  name: string;
+  required: boolean;
+  type: "string";
+  description: string;
+  schema: {
+    type: string;
+  };
+  in: "path" | "query";
+};
+
+type BuildRoutePath = {
+  /** /foo/{bar}/baz */
+  originalRoute: string;
+  /** /foo/${bar}/baz */
+  route: string;
+  pathParams: BuildRouteParam[];
+  queryParams: BuildRouteParam[];
+};
+
 export interface Hooks {
+  /** calls before parse\process route path */
+  onPreBuildRoutePath: (routePath: string) => string | void;
+  /** calls after parse\process route path */
+  onBuildRoutePath: (data: BuildRoutePath) => BuildRoutePath | void;
+  /** calls before insert path param name into string path interpolation */
+  onInsertPathParam: (paramName: string, index: number, arr: BuildRouteParam[], resultRoute: string) => string | void;
   /** calls after parse schema component */
   onCreateComponent: (component: SchemaComponent) => SchemaComponent | void;
+  /** calls before parse any kind of schema */
+  onPreParseSchema: (originalSchema: any, typeName: string, schemaType: string) => any;
   /** calls after parse any kind of schema */
   onParseSchema: (originalSchema: any, parsedSchema: any) => any | void;
   /** calls after parse route (return type: customized route (ParsedRoute), nothing change (void), false (ignore this route)) */
@@ -228,7 +274,7 @@ export interface Hooks {
   /** customize request params (path params, query params) */
   onCreateRequestParams?: (rawType: SchemaComponent["rawTypeData"]) => SchemaComponent["rawTypeData"] | void;
   /** customize name of model type */
-  onFormatTypeName?: (typeName: string, rawTypeName?: string) => string | void;
+  onFormatTypeName?: (typeName: string, rawTypeName?: string, schemaType?: "type-name" | "enum-key") => string | void;
   /** customize name of route (operationId), you can do it with using onCreateRouteName too */
   onFormatRouteName?: (routeInfo: RawRouteInfo, templateRouteName: string) => string | void;
 }
@@ -376,6 +422,17 @@ export enum SCHEMA_TYPES {
 
 type MAIN_SCHEMA_TYPES = SCHEMA_TYPES.PRIMITIVE | SCHEMA_TYPES.OBJECT | SCHEMA_TYPES.ENUM;
 
+type ExtractingOptions = {
+  requestBodySuffix: string[];
+  responseBodySuffix: string[];
+  responseErrorSuffix: string[];
+  requestParamsSuffix: string[];
+  requestBodyNameResolver: (name: string, reservedNames: string) => string | undefined;
+  responseBodyNameResolver: (name: string, reservedNames: string) => string | undefined;
+  responseErrorNameResolver: (name: string, reservedNames: string) => string | undefined;
+  requestParamsNameResolver: (name: string, reservedNames: string) => string | undefined;
+};
+
 export interface GenerateApiConfiguration {
   apiConfig: {
     baseUrl: string;
@@ -411,6 +468,8 @@ export interface GenerateApiConfiguration {
     singleHttpClient: boolean;
     typePrefix: string;
     typeSuffix: string;
+    enumKeyPrefix: string;
+    enumKeySuffix: string;
     patch: boolean;
     cleanOutput: boolean;
     debug: boolean;
@@ -420,7 +479,10 @@ export interface GenerateApiConfiguration {
     addReadonly: boolean;
     extractResponseBody: boolean;
     extractResponseError: boolean;
-    defaultResponseType: boolean;
+    extractEnums: boolean;
+    fixInvalidTypeNamePrefix: string;
+    fixInvalidEnumKeyPrefix: string;
+    defaultResponseType: string;
     toJS: boolean;
     disableThrowOnError: boolean;
     silent: boolean;
@@ -452,6 +514,7 @@ export interface GenerateApiConfiguration {
     routeNameDuplicatesMap: Map<string, string>;
     apiClassName: string;
     requestOptions?: import("node-fetch").RequestInit;
+    extractingOptions: ExtractingOptions;
   };
   modelTypes: ModelType[];
   rawModelTypes: SchemaComponent[];

index.js

@@ -37,7 +37,7 @@ const program = cli({
     {
       flags: "-n, --name <string>",
       description: "name of output typescript api file",
-      default: `${codeGenBaseConfig.apiClassName}.ts`,
+      default: codeGenBaseConfig.fileName,
     },
     {
       flags: "-t, --templates <string>",
@@ -202,6 +202,11 @@ const program = cli({
       description: "sort fields and types",
       default: codeGenBaseConfig.sortTypes,
     },
+    {
+      flags: "--extract-enums",
+      description: "extract all enums from inline interface\\type content to typescript enum construction",
+      default: codeGenBaseConfig.extractEnums,
+    },
   ],
 });