feat: ability to modify code gen constructs;

feat: --another-array-type cli option (Array<Type>);
docs: update CHANGELOG, README

Author: js2me

CHANGELOG.md

@@ -1,5 +1,16 @@
 # next release  
 
+# 10.1.0
+**feature**  
+everything which generate code gen about output typescript code now contains in [`src/code-gen-constructs`](src/code-gen-constructs.js).
+And this thing is available for end user modifications with using NodeJS Cli option `codeGenConstructs`.  
+It contains almost all which is not contains in `.eta`\ `.ejs` templates. For example: `Record<string, any>`, `readonly typeField?: value`, etc  
+
+feat: `--another-array-type` cli option (#414)  
+fix: path params with dot style (truck.id) (#413)  
+
+
+
 # 10.0.3  
 fix: CRLF -> LF (#423)  
 docs: add docs for addReadonly nodeJS api flag (#425)  

README.md

@@ -71,6 +71,8 @@ Options:
   --clean-output                clean output folder before generate api. WARNING: May cause data loss (default: false)
   --api-class-name <string>     name of the api class
   --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)
   -h, --help                    display help for command
 ```
 
@@ -122,6 +124,11 @@ generateApi({
   generateUnionEnums: false,
   addReadonly: false,
   extraTemplates: [],
+  anotherArrayType: false, 
+  codeGenConstructs: ({ Ts, JsDoc }) => ({
+    Ts: { ...Ts, RecordType: (key, value) => `MyRecord<key, value>` },
+    JsDoc: { ...JsDoc },
+  }),
   hooks: {
     onCreateComponent: (component) => {},
     onCreateRequestParams: (rawType) => {},

index.js

@@ -10,7 +10,8 @@ const { Command } = require("commander");
 const { resolve } = require("path");
 const { generateApi } = require("./src");
 const { version, name: packageName } = require("./package.json");
-const { TS_KEYWORDS, HTTP_CLIENT } = require("./src/constants");
+const { HTTP_CLIENT } = require("./src/constants");
+const { Ts } = require("./src/code-gen-constructs");
 
 const program = new Command(packageName);
 
@@ -61,13 +62,14 @@ const options = program
   .option("--disable-throw-on-error", "Do not throw an error when response.ok is not true", false)
   .option("--single-http-client", "Ability to send HttpClient instance to Api constructor", false)
   .option("--silent", "Output only errors to console", false)
-  .option("--default-response <type>", "default type for empty response schema", TS_KEYWORDS.VOID)
+  .option("--default-response <type>", "default type for empty response schema", Ts.Keyword.Void)
   .option("--type-prefix <string>", "data contract name prefix", "")
   .option("--type-suffix <string>", "data contract name suffix", "")
   .option("--clean-output", "clean output folder before generate api. WARNING: May cause data loss", false)
   .option("--api-class-name <string>", "name of the api class")
   .option("--patch", "fix up small errors in the swagger source definition", false)
   .option("--debug", "additional information about processes inside this tool", false)
+  .option("--another-array-type", "generate array types as Array<Type> (by default Type[])", false)
   .parse(process.argv)
   .opts();
 
@@ -107,6 +109,7 @@ generateApi({
   patch: !!options.patch,
   apiClassName: options.apiClassName,
   debug: options.debug,
+  anotherArrayType: options.anotherArrayType,
 }).catch((err) => {
   // NOTE collect all errors on top level and shows to users in any case
   console.error(err);

package.json

@@ -41,6 +41,7 @@
     "test:--js": "node tests/spec/js/test.js",
     "test:--js--axios": "node tests/spec/jsAxios/test.js",
     "test:--axios": "node tests/spec/axios/test.js",
+    "test:--another-array-type": "node tests/spec/another-array-type/test.js",
     "test:--object-types": "node tests/spec/object-types/test.js",
     "test:--axios--single-http-client": "node tests/spec/axiosSingleHttpClient/test.js",
     "test:--type-suffix--type-prefix": "node tests/spec/typeSuffixPrefix/test.js",

src/code-gen-constructs.js

@@ -0,0 +1,142 @@
+const _ = require("lodash");
+
+const Keyword = {
+  Number: "number",
+  String: "string",
+  Boolean: "boolean",
+  Any: "any",
+  Void: "void",
+  Unknown: "unknown",
+  Null: "null",
+  Undefined: "undefined",
+  Object: "object",
+  File: "File",
+  Date: "Date",
+  Type: "type",
+  Enum: "enum",
+  Interface: "interface",
+  Array: "Array",
+  Record: "Record",
+  Intersection: "&",
+  Union: "|",
+};
+
+const CodeGenKeyword = {
+  UtilRequiredKeys: "UtilRequiredKeys",
+};
+
+const Ts = {
+  Keyword,
+  CodeGenKeyword,
+  /**
+   * $A[] or Array<$A>
+   */
+  ArrayType: (content) => {
+    const { config } = require("./config");
+
+    if (config.anotherArrayType) {
+      return Ts.TypeWithGeneric(Ts.Keyword.Array, [content]);
+    }
+
+    return `${Ts.ExpressionGroup(content)}[]`;
+  },
+  /**
+   * "$A"
+   */
+  StringValue: (content) => `"${content}"`,
+  /**
+   * $A
+   */
+  BooleanValue: (content) => `${content}`,
+  /**
+   * $A
+   */
+  NumberValue: (content) => `${content}`,
+  /**
+   * $A
+   */
+  NullValue: (content) => content,
+  /**
+   * $A1 | $A2
+   */
+  UnionType: (contents) => _.join(_.uniq(contents), ` ${Ts.Keyword.Union} `),
+  /**
+   * ($A1)
+   */
+  ExpressionGroup: (content) => (content ? `(${content})` : ""),
+  /**
+   * $A1 & $A2
+   */
+  IntersectionType: (contents) => _.join(_.uniq(contents), ` ${Ts.Keyword.Intersection} `),
+  /**
+   * Record<$A1, $A2>
+   */
+  RecordType: (key, value) => Ts.TypeWithGeneric(Ts.Keyword.Record, [key, value]),
+  /**
+   * readonly $key?:$value
+   */
+  TypeField: ({ readonly, key, optional, value }) =>
+    _.compact([readonly && "readonly ", key, optional && "?", ": ", value]).join(""),
+  /**
+   * [key: $A1]: $A2
+   */
+  InterfaceDynamicField: (key, value) => `[key: ${key}]: ${value}`,
+  /**
+   * $A1 = $A2
+   */
+  EnumField: (key, value) => `${key} = ${value}`,
+  /**
+   * $A0.key = $A0.value,
+   * $A1.key = $A1.value,
+   * $AN.key = $AN.value,
+   */
+  EnumFieldsWrapper: (contents) => _.map(contents, ({ key, value }) => `  ${Ts.EnumField(key, value)}`).join(",\n"),
+  /**
+   * {\n $A \n}
+   */
+  ObjectWrapper: (content) => `{\n${content}\n}`,
+  /**
+   * /** $A *\/
+   */
+  MultilineComment: (contents, formatFn) =>
+    [
+      ...(contents.length === 1
+        ? [`/** ${contents[0]} */`]
+        : ["/**", ...contents.map((content) => ` * ${content}`), " */"]),
+    ].map((part) => `${formatFn ? formatFn(part) : part}\n`),
+  /**
+   * $A1<...$A2.join(,)>
+   */
+  TypeWithGeneric: (typeName, genericArgs) => {
+    return `${typeName}${genericArgs.length ? `<${genericArgs.join(",")}>` : ""}`;
+  },
+};
+
+const JsDoc = {
+  Deprecated: "@deprecated",
+  Format: "@format",
+  Min: "@min",
+  Max: "@max",
+  Pattern: "@pattern",
+  Example: "@example",
+  Description: "",
+  Title: "",
+  TextLine: (key, text) => _.compact([key, `${text === undefined ? "" : text}`]).join(" "),
+  ObjectFieldDescription: ({ title, description, deprecated, format, minimum, maximum, pattern, example }) => {
+    return _.compact([
+      JsDoc.TextLine(JsDoc.Title, title),
+      JsDoc.TextLine(JsDoc.Description, description),
+      !_.isUndefined(deprecated) && JsDoc.Deprecated,
+      !_.isUndefined(format) && JsDoc.TextLine(JsDoc.Format, format),
+      !_.isUndefined(minimum) && JsDoc.TextLine(JsDoc.Min, minimum),
+      !_.isUndefined(maximum) && JsDoc.TextLine(JsDoc.Max, maximum),
+      !_.isUndefined(pattern) && JsDoc.TextLine(JsDoc.Pattern, pattern),
+      !_.isUndefined(example) && JsDoc.TextLine(JsDoc.Example, _.isObject(example) ? JSON.stringify(example) : example),
+    ]).join("\n");
+  },
+};
+
+module.exports = {
+  Ts,
+  JsDoc,
+};

src/config.js

@@ -1,6 +1,7 @@
-const { HTTP_CLIENT, TS_KEYWORDS, PRETTIER_OPTIONS } = require("./constants");
+const { HTTP_CLIENT, PRETTIER_OPTIONS } = require("./constants");
 const { NameResolver } = require("./utils/resolveName");
 const packageJson = require("../package.json");
+const { Ts } = require("./code-gen-constructs");
 
 const config = {
   version: packageJson.version,
@@ -61,7 +62,7 @@ const config = {
     onFormatTypeName: (typeName, rawTypeName) => {},
     onFormatRouteName: (routeInfo, templateRouteName) => {},
   },
-  defaultResponseType: TS_KEYWORDS.VOID,
+  defaultResponseType: Ts.Keyword.Void,
   singleHttpClient: false,
   httpClientType: HTTP_CLIENT.FETCH,
   unwrapResponseData: false,
@@ -96,6 +97,7 @@ const config = {
   /** name of the main exported class */
   apiClassName: "Api",
   debug: false,
+  anotherArrayType: false,
   internalTemplateOptions: {
     addUtilRequiredKeysType: false,
   },

src/constants.js

@@ -1,28 +1,7 @@
-const TS_KEYWORDS = {
-  NUMBER: "number",
-  STRING: "string",
-  BOOLEAN: "boolean",
-  ANY: "any",
-  VOID: "void",
-  UNKNOWN: "unknown",
-  NULL: "null",
-  UNDEFINED: "undefined",
-  OBJECT: "object",
-  FILE: "File",
-  DATE: "Date",
-  TYPE: "type",
-  ENUM: "enum",
-  INTERFACE: "interface",
-  TYPE_AND_OPERATOR: " & ",
-  TYPE_OR_OPERATOR: " | ",
-};
-
-const TS_EXTERNAL = {
-  RECORD: "Record<string, any>",
-};
+const { Ts } = require("./code-gen-constructs");
 
-const JS_PRIMITIVE_TYPES = [TS_KEYWORDS.NUMBER, TS_KEYWORDS.STRING, TS_KEYWORDS.BOOLEAN];
-const JS_EMPTY_TYPES = [TS_KEYWORDS.NULL, TS_KEYWORDS.UNDEFINED];
+const JS_PRIMITIVE_TYPES = [Ts.Keyword.Number, Ts.Keyword.String, Ts.Keyword.Boolean];
+const JS_EMPTY_TYPES = [Ts.Keyword.Null, Ts.Keyword.Undefined];
 
 const RESERVED_QUERY_ARG_NAMES = ["query", "queryParams", "queryArg"];
 const RESERVED_BODY_ARG_NAMES = ["data", "body", "reqBody"];
@@ -51,11 +30,9 @@ const HTTP_CLIENT = {
 
 module.exports = {
   DEFAULT_BODY_ARG_NAME: "data",
-  SUCCESS_RESPONSE_STATUS_RANGE: [200, 300],
+  SUCCESS_RESPONSE_STATUS_RANGE: [200, 299],
   JS_PRIMITIVE_TYPES,
   JS_EMPTY_TYPES,
-  TS_KEYWORDS,
-  TS_EXTERNAL,
   SCHEMA_TYPES,
   HTTP_CLIENT,
   RESERVED_QUERY_ARG_NAMES,

src/index.js

@@ -22,6 +22,7 @@ const formatFileContent = require("./formatFileContent");
 const { logger } = require("./logger");
 const { ComponentTypeNameResolver } = require("./utils/resolveName");
 const { getPrettierOptions } = require("./prettierOptions");
+const CodeGenConstructs = require("./code-gen-constructs");
 
 module.exports = {
   constants: constants,
@@ -66,8 +67,18 @@ module.exports = {
     authorizationToken,
     apiClassName = config.apiClassName,
     debug = config.debug,
+    anotherArrayType = config.anotherArrayType,
+    codeGenConstructs,
   }) =>
     new Promise((resolve, reject) => {
+      const patchedCodeGenConstructs = codeGenConstructs ? codeGenConstructs(CodeGenConstructs) : CodeGenConstructs;
+      if (patchedCodeGenConstructs.Ts) {
+        Object.assign(CodeGenConstructs.Ts, patchedCodeGenConstructs.Ts);
+      }
+      if (patchedCodeGenConstructs.JsDoc) {
+        Object.assign(CodeGenConstructs.JsDoc, patchedCodeGenConstructs.JsDoc);
+      }
+
       addToConfig({
         defaultResponseAsSuccess,
         generateRouteTypes,
@@ -103,6 +114,7 @@ module.exports = {
         patch,
         apiClassName,
         debug,
+        anotherArrayType,
       });
       (spec
         ? convertSwaggerObject(spec, { patch })

src/render/utils/index.js

@@ -10,8 +10,11 @@ const {
 } = require("../../schema");
 const { formatters, inlineExtraFormatters } = require("../../typeFormatters");
 const { NameResolver } = require("../../utils/resolveName");
+const { Ts, JsDoc } = require("../../code-gen-constructs");
 
 module.exports = {
+  Ts,
+  JsDoc,
   formatDescription,
   internalCase,
   classNameCase,