BREAKING_CHANGE: fully rewrite render Eta templates process, overriding only one template(#166), template path prefixes

Author: js2me

.vscode/launch.json

@@ -35,6 +35,14 @@
       "cwd": "${workspaceFolder}",
       "runtimeExecutable": "npm",
       "runtimeArgs": ["run-script", "node:debug"]
+    },
+    {
+      "name": "Debug partialTemplates test",
+      "type": "node",
+      "request": "launch",
+      "cwd": "${workspaceFolder}",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["run-script", "test:partialBaseTemplate"]
     }
   ]
 }

CHANGELOG.md

@@ -1,5 +1,11 @@
 # next release  
 
+BREAKING_CHANGES:  
+- Ability to override only one template (issue #166, thanks @Nihisil)  
+
+Features:  
+- template path prefixes `@base`, `@default`, `@modular` (using in Eta templates, `includeFile()`, see README.md)  
+
 # 5.1.7  
 
 Fixes:  

README.md

@@ -144,9 +144,24 @@ How to use it:
 1. copy swagger-typescript-api templates into your place in project
     - from [/templates/default](https://github.com/acacode/swagger-typescript-api/tree/next/templates/default) for single api file  
     - from [/templates/modular](https://github.com/acacode/swagger-typescript-api/tree/next/templates/modular) for multiple api files (with `--modular` option)  
+    - from [/templates/base](https://github.com/acacode/swagger-typescript-api/tree/next/templates/base) for base templates (templates using both in default and modular)  
 1. add `--templates PATH_TO_YOUR_TEMPLATES` option  
 2. modify [ETA](https://eta.js.org/docs/syntax) templates as you like  
 
+NOTE:  
+  Eta has special directive to render template in your Eta templates - `includeFile(pathToTemplate, payload)`  
+  If you want to use some default templates from this tool you can use path prefixes: `@base`, `@default`, `@modular`.  
+  Examples:
+    - `includeFile("@base/data-contracts.eta", configuration)`  
+    - `includeFile("@default/api.eta", configuration)`  
+    - `includeFile("@default/procedure-call.eta", configuration)`  
+    - `includeFile("@modular/api.eta", configuration)`  
+    - `includeFile("@modular/procedure-call.eta", configuration)`  
+    - `includeFile("@base/route-docs.eta", configuration)`  
+    - `includeFile("@base/route-name.eta", configuration)`  
+    - `includeFile("@base/route-type.eta", configuration)`  
+    - `includeFile("@base/route-types.eta", configuration)`  
+
 ### **`--module-name-index`**  
 This option should be used in cases when you have api with one global prefix like `/api`   
 Example:   

package.json

@@ -29,7 +29,9 @@
     "test:--extract-request-params": "node tests/spec/extractRequestParams/test.js",
     "test:--enum-names-as-values": "node tests/spec/enumNamesAsValues/test.js",
     "test:--default-response": "node tests/spec/defaultResponse/test.js",
-    "test:--js": "node tests/spec/js/test.js"
+    "test:--js": "node tests/spec/js/test.js",
+    "test:partialBaseTemplate": "node tests/spec/partialBaseTemplate/test.js",
+    "test:partialDefaultTemplate": "node tests/spec/partialDefaultTemplate/test.js"
   },
   "author": "acacode",
   "license": "MIT",

src/config.js

@@ -49,6 +49,20 @@ const config = {
   },
   defaultResponseType: constants.TS_KEYWORDS.VOID,
   singleHttpClient: false,
+  templatePaths: {
+    /** `templates/base` */
+    base: "",
+    /** `templates/default` */
+    default: "",
+    /** `templates/modular` */
+    modular: "",
+    /** usage path if `--templates` option is not set */
+    original: "",
+    /** custom path to templates (`--templates`) */
+    custom: "",
+  },
+  /** Record<templateName, templateContent> */
+  templatesToRender: {},
 };
 
 /** needs to use data everywhere in project */

src/files.js

@@ -4,7 +4,9 @@ const { resolve } = require("path");
 const { filePrefix } = require("./filePrefix");
 const makeDir = require("make-dir");
 
-const getFileContent = (path) => fs.readFileSync(path, { encoding: "UTF-8" });
+const getFileContent = (path) => {
+  return fs.readFileSync(path, { encoding: "UTF-8" });
+};
 
 const pathIsDir = (path) => {
   if (!path) return false;

src/index.js

@@ -15,7 +15,7 @@ const { getSwaggerObject, fixSwaggerScheme, convertSwaggerObject } = require("./
 const { createComponentsMap, filterComponentsMap } = require("./components");
 const { createFile, pathIsExist, pathIsDir, createDir, cleanDir } = require("./files");
 const { addToConfig, config } = require("./config");
-const { getTemplates } = require("./templates");
+const { getTemplates, getTemplatePaths } = require("./templates");
 const constants = require("./constants");
 const { generateOutputFiles } = require("./output");
 
@@ -66,6 +66,10 @@ module.exports = {
       });
       (spec ? convertSwaggerObject(spec) : getSwaggerObject(input, url, disableStrictSSL))
         .then(({ usageSchema, originalSchema }) => {
+          const templatePaths = getTemplatePaths(config);
+
+          addToConfig({ templatePaths });
+
           const templatesToRender = getTemplates(config);
 
           console.log("☄️  start generating your typescript api");

src/templates.js

@@ -1,44 +1,74 @@
 const _ = require("lodash");
 const Eta = require("eta");
 const { getFileContent, pathIsExist } = require("./files");
+const { config, addToConfig } = require("./config");
 const { resolve } = require("path");
 
-const getTemplates = ({ templates, modular }) => {
-  const originalTemplatesPath = resolve(
-    __dirname,
-    modular ? "../templates/modular" : "../templates/default",
-  );
+/**
+ * name - project template name,
+ * fileName - template file name,
+ */
+const TEMPLATE_INFOS = [
+  { name: "api", fileName: "api.eta" },
+  { name: "dataContracts", fileName: "data-contracts.eta" },
+  { name: "httpClient", fileName: "http-client.eta" },
+  { name: "routeTypes", fileName: "route-types.eta" },
+  { name: "routeName", fileName: "route-name.eta" },
+];
+
+const getTemplatePaths = ({ templates, modular }) => {
+  const baseTemplatesPath = resolve(__dirname, "../templates/base");
+  const defaultTemplatesPath = resolve(__dirname, "../templates/default");
+  const modularTemplatesPath = resolve(__dirname, "../templates/modular");
+  const originalTemplatesPath = modular ? modularTemplatesPath : defaultTemplatesPath;
   const customTemplatesPath = templates ? resolve(process.cwd(), templates) : originalTemplatesPath;
 
-  console.log(`✨ try to read templates from directory "${customTemplatesPath}"`);
+  return {
+    /** `templates/base` */
+    base: baseTemplatesPath,
+    /** `templates/default` */
+    default: defaultTemplatesPath,
+    /** `templates/modular` */
+    modular: modularTemplatesPath,
+    /** usage path if `--templates` option is not set */
+    original: originalTemplatesPath,
+    /** custom path to templates (`--templates`) */
+    custom: customTemplatesPath,
+  };
+};
+
+const getTemplates = ({ templatePaths }) => {
+  console.log(`✨ try to read templates from directory "${templatePaths.custom}"`);
 
   Eta.configure({
-    views: customTemplatesPath,
+    views: templatePaths.custom,
   });
 
-  const templatePaths = {
-    api: "./api.eta",
-    dataContracts: "./data-contracts.eta",
-    httpClient: "./http-client.eta",
-    routeTypes: "./route-types.eta",
-    routeName: "./route-name.eta",
-  };
-
   const templatesMap = _.reduce(
-    templatePaths,
-    (acc, pathToTemplate, key) => {
-      const customFullPath = resolve(customTemplatesPath, pathToTemplate)
+    TEMPLATE_INFOS,
+    (acc, { fileName, name }) => {
+      const customFullPath = resolve(templatePaths.custom, "./", fileName);
       let fileContent = pathIsExist(customFullPath) && getFileContent(customFullPath);
 
       if (!fileContent) {
-        console.log(
-          `❗❗❗ ${_.lowerCase(key)} template not found in ${pathToTemplate}\n` +
-            `Code generator will use the default template`,
-        );
-        fileContent = getFileContent(resolve(originalTemplatesPath, pathToTemplate));
+        const baseFullPath = resolve(templatePaths.base, "./", fileName);
+        const originalFullPath = resolve(templatePaths.original, "./", fileName);
+
+        if (pathIsExist(baseFullPath)) {
+          fileContent = getFileContent(baseFullPath);
+        } else {
+          console.log(
+            `❗❗❗ ${_.lowerCase(name)} template not found in ${customFullPath}\n` +
+              `Code generator will use the default template`,
+          );
+        }
+
+        if (pathIsExist(originalFullPath)) {
+          fileContent = getFileContent(originalFullPath);
+        }
       }
 
-      acc[key] = fileContent;
+      acc[name] = fileContent;
 
       return acc;
     },
@@ -48,13 +78,46 @@ const getTemplates = ({ templates, modular }) => {
   return templatesMap;
 };
 
+const getTemplateContent = (path) => {
+  let fixedPath = _.endsWith(path, ".eta") ? path : `${path}.eta`;
+
+  _.keys(config.templatePaths).forEach((key) => {
+    if (_.startsWith(fixedPath, `@${key}`)) {
+      fixedPath = resolve(_.replace(fixedPath, `@${key}`, config.templatePaths[key]));
+    }
+  });
+
+  if (pathIsExist(fixedPath)) {
+    return getFileContent(fixedPath);
+  }
+
+  const customPath = resolve(config.templatePaths.custom, fixedPath);
+
+  if (pathIsExist(customPath)) {
+    return getFileContent(customPath);
+  }
+
+  const originalPath = resolve(config.templatePaths.original, fixedPath);
+
+  if (pathIsExist(originalPath)) {
+    return getFileContent(originalPath);
+  }
+
+  return "";
+};
+
 const renderTemplate = (template, configuration, options) => {
   if (!template) return "";
 
-  return Eta.render(template, configuration, { async: false, ...(options || {}) });
+  return Eta.render(template, configuration, {
+    async: false,
+    ...(options || {}),
+    includeFile: (path, payload) => renderTemplate(getTemplateContent(path), payload),
+  });
 };
 
 module.exports = {
   getTemplates,
+  getTemplatePaths,
   renderTemplate,
 };

templates/default/data-contracts.eta renamed to templates/base/data-contracts.eta

@@ -3,7 +3,7 @@ const { route, utils, config } = it;
 const { _, classNameCase, require } = utils;
 const { query, payload, pathParams, headers } = route.request;
 
-const routeDocs = includeFile("./route-docs", { config, route, utils });
+const routeDocs = includeFile("@base/route-docs", { config, route, utils });
 const routeNamespace = classNameCase(route.routeName.usage);
 
 %>

templates/default/http-client.eta renamed to templates/base/http-client.eta

@@ -7,14 +7,14 @@ const { utils, config, routes } = it;
 
 <% routes.outOfModule && routes.outOfModule.forEach(({ routes = [] }) => { %>
     <% routes.forEach((route) => { %>
-        <%~ includeFile('./route-type.eta', { route, utils, config }) %>
+        <%~ includeFile('@base/route-type.eta', { route, utils, config }) %>
     <% }) %>
 <% }) %>
 
 <% routes.combined && routes.combined.forEach(({ routes = [], moduleName }) => { %>
     export namespace <%~ moduleName %> {
     <% routes.forEach((route) => { %>
-        <%~ includeFile('./route-type.eta', { route, utils, config }) %>
+        <%~ includeFile('@base/route-type.eta', { route, utils, config }) %>
     <% }) %>
     }
 

templates/default/route-docs.eta renamed to templates/base/route-docs.eta

@@ -4,7 +4,7 @@ const { requestBodyInfo, responseBodyInfo } = route;
 const { _, getInlineParseContent, getParseContent, parseSchema, getComponentByRef, require } = utils;
 const { parameters, path, method, payload, params, query, formData, security, requestParams } = route.request;
 const { type, errorType, contentTypes } = route.response;
-const routeDocs = includeFile("./route-docs", { config, route, utils });
+const routeDocs = includeFile("@base/route-docs", { config, route, utils });
 const queryName = (query && query.name) || "query";
 const pathParams = _.values(parameters);