@asyncapi/generator 1.13.0 → 1.14.0

package/Dockerfile

@@ -1,3 +1,5 @@
+ARG ASYNCAPI_GENERATOR_VERSION=1.10.9
+
 FROM node:14-alpine
 
 WORKDIR /app
@@ -14,6 +16,6 @@ RUN apk --update add git chromium && \
     rm /var/cache/apk/*
 
 # Installing latest released npm package
-RUN npm install -g @asyncapi/generator
+RUN npm install -g @asyncapi/generator@$ASYNCAPI_GENERATOR_VERSION
 
 ENTRYPOINT [ "ag" ]

package/docs/api.md

@@ -26,10 +26,10 @@ Reference API documentation for AsyncAPI Generator library.
         * [.hooks](#Generator+hooks) : `Object`
         * [.mapBaseUrlToFolder](#Generator+mapBaseUrlToFolder) : `Object`
         * [.templateParams](#Generator+templateParams) : `Object`
-        * [.originalAsyncAPI](#Generator+originalAsyncAPI) : `String`
-        * [.generate(asyncapiDocument)](#Generator+generate) ⇒ `Promise`
+        * [.generate(asyncapiDocument, [parseOptions])](#Generator+generate) ⇒ `Promise`
+        * [.parseInput()](#Generator+parseInput)
         * [.configureTemplate()](#Generator+configureTemplate)
-        * [.generateFromString(asyncapiString, [parseOptions])](#Generator+generateFromString) ⇒ `Promise`
+        * ~~[.generateFromString(asyncapiString, [parseOptions])](#Generator+generateFromString) ⇒ `Promise`~~
         * [.generateFromURL(asyncapiURL)](#Generator+generateFromURL) ⇒ `Promise`
         * [.generateFromFile(asyncapiFile)](#Generator+generateFromFile) ⇒ `Promise`
         * [.installTemplate([force])](#Generator+installTemplate)
@@ -163,13 +163,6 @@ The template parameters. The structure for this object is based on each individu
 
 **Kind**: instance property of [`Generator`](#Generator)  
 
-<a name="Generator+originalAsyncAPI"></a>
-
-* generator.originalAsyncAPI : `String`** :
-AsyncAPI string to use as a source.
-
-**Kind**: instance property of [`Generator`](#Generator)  
-
 <a name="Generator+generate"></a>
 
 ### generator.generate
@@ -178,7 +171,8 @@ Generates files from a given template and an AsyncAPIDocument object.
 **Kind**: instance method of [`Generator`](#Generator)  
 **Params**
 
-- asyncapiDocument `AsyncAPIDocument` - AsyncAPIDocument object to use as source.
+- asyncapiDocument `AsyncAPIDocument` | `string` - AsyncAPIDocument object to use as source.
+- [parseOptions] `Object` ` = {}` - AsyncAPI Parser parse options. Check out [@asyncapi/parser](https://www.github.com/asyncapi/parser-js) for more information. Remember to use the right options to the right parser depending on the template you are using.
 
 **Example**  
 ```js
@@ -199,6 +193,13 @@ try {
 }
 ```
 
+<a name="Generator+parseInput"></a>
+
+* generator.parseInput()** :
+Parse the generator input based on the template `templateConfig.apiVersion` value.
+
+**Kind**: instance method of [`Generator`](#Generator)  
+
 <a name="Generator+configureTemplate"></a>
 
 * generator.configureTemplate()** :
@@ -208,7 +209,9 @@ Configure the templates based the desired renderer.
 
 <a name="Generator+generateFromString"></a>
 
-### generator.generateFromString
+### ~~generator.generateFromString~~
+***Deprecated***
+
 Generates files from a given template and AsyncAPI string.
 
 **Kind**: instance method of [`Generator`](#Generator)  

package/lib/generator.js

@@ -139,6 +139,11 @@ class Generator {
   /**
    * Generates files from a given template and an AsyncAPIDocument object.
    *
+   * @async
+   * @example
+   * await generator.generate(myAsyncAPIdocument);
+   * console.log('Done!');
+   * 
    * @example
    * generator
    *   .generate(myAsyncAPIdocument)
@@ -155,48 +160,162 @@ class Generator {
    *   console.error(e);
    * }
    *
-   * @param  {AsyncAPIDocument | string} asyncapiDocument AsyncAPIDocument object to use as source.
-   * @param  {Object} [parseOptions={}] AsyncAPI Parser parse options. Check out {@link https://www.github.com/asyncapi/parser-js|@asyncapi/parser} for more information. Remember to use the right options to the right parser depending on the template you are using.
-   * @return {Promise}
+   * @param {AsyncAPIDocument | string} asyncapiDocument - AsyncAPIDocument object to use as source.
+   * @param {Object} [parseOptions={}] - AsyncAPI Parser parse options.
+   *   Check out {@link https://www.github.com/asyncapi/parser-js|@asyncapi/parser} for more information.
+   *   Remember to use the right options for the right parser depending on the template you are using.
+   * @return {Promise<void>} A Promise that resolves when the generation is completed.
    */
-  // eslint-disable-next-line sonarjs/cognitive-complexity
   async generate(asyncapiDocument, parseOptions = {}) {
+    this.validateAsyncAPIDocument(asyncapiDocument);
+    this.setupOutput();
+    this.setLogLevel();
+
+    await this.installAndSetupTemplate();
+    await this.configureTemplateWorkflow(parseOptions);
+    await this.handleEntrypoint();
+    await this.executeAfterHook();
+  }
+
+  /**
+   * Validates the provided AsyncAPI document.
+   *
+   * @param {*} asyncapiDocument - The AsyncAPI document to be validated.
+   * @throws {Error} Throws an error if the document is not valid.
+   * @since 10/9/2023 - 4:26:33 PM
+   */
+  validateAsyncAPIDocument(asyncapiDocument) {
     const isAlreadyParsedDocument = isAsyncAPIDocument(asyncapiDocument);
     const isParsableCompatible = asyncapiDocument && typeof asyncapiDocument === 'string';
+
     if (!isAlreadyParsedDocument && !isParsableCompatible) {
       throw new Error('Parameter "asyncapiDocument" must be a non-empty string or an already parsed AsyncAPI document.');
     }
+
     this.asyncapi = this.originalAsyncAPI = asyncapiDocument;
+  }
 
+  /**
+   * Sets up the output configuration based on the specified output type.
+   *
+   * @example
+   * const generator = new Generator();
+   * generator.setupOutput();
+   *
+   * @throws {Error} If 'output' is set to 'string' without providing 'entrypoint'.
+   */
+  setupOutput() {
     if (this.output === 'fs') {
-      xfs.mkdirpSync(this.targetDir);
-      if (!this.forceWrite) await this.verifyTargetDir(this.targetDir);
+      this.setupFSOutput();
     } else if (this.output === 'string' && this.entrypoint === undefined) {
       throw new Error('Parameter entrypoint is required when using output = "string"');
     }
+  }
+
+  /**
+   * Sets up the file system (FS) output configuration.
+   *
+   * This function creates the target directory if it does not exist and verifies
+   * the target directory if forceWrite is not enabled.
+   *
+   * @async
+   * @returns {Promise<void>} A promise that fulfills when the setup is complete.
+   *
+   * @throws {Error} If verification of the target directory fails and forceWrite is not enabled.
+   */
+  async setupFSOutput() {
+    // Create directory if not exists
+    xfs.mkdirpSync(this.targetDir);
 
+    // Verify target directory if forceWrite is not enabled
+    if (!this.forceWrite) {
+      await this.verifyTargetDir(this.targetDir);
+    }
+  }
+
+  /**
+   * Sets the log level based on the debug option.
+   *
+   * If the debug option is enabled, the log level is set to 'debug'.
+   *
+   * @returns {void}
+   */
+  setLogLevel() {
     if (this.debug) log.setLevel('debug');
+  }
 
+  /**
+   * Installs and sets up the template for code generation.
+   *
+   * This function installs the specified template using the provided installation option,
+   * sets up the necessary directory paths, loads the template configuration, and returns
+   * information about the installed template.
+   *
+   * @async
+   * @returns {Promise<{ templatePkgName: string, templatePkgPath: string }>}
+   *   A promise that resolves to an object containing the name and path of the installed template.
+   */
+  async installAndSetupTemplate() {
     const { name: templatePkgName, path: templatePkgPath } = await this.installTemplate(this.install);
+
     this.templateDir = templatePkgPath;
     this.templateName = templatePkgName;
     this.templateContentDir = path.resolve(this.templateDir, TEMPLATE_CONTENT_DIRNAME);
+
     await this.loadTemplateConfig();
 
-    await this.parseInput(this.asyncapi, parseOptions);
+    return { templatePkgName, templatePkgPath };
+  }
 
+  /**
+   * Configures the template workflow based on provided parsing options.
+   *
+   * This function performs the following steps:
+   * 1. Parses the input AsyncAPI document using the specified parse options.
+   * 2. Validates the template configuration and parameters.
+   * 3. Configures the template based on the parsed AsyncAPI document.
+   * 4. Registers filters, hooks, and launches the 'generate:before' hook if applicable.
+   *
+   * @async
+   * @param {*} parseOptions - Options for parsing the AsyncAPI document.
+   * @returns {Promise<void>} A promise that resolves when the configuration is completed.
+   */
+  async configureTemplateWorkflow(parseOptions) {
+    // Parse input and validate template configuration
+    await this.parseInput(this.asyncapi, parseOptions);
     validateTemplateConfig(this.templateConfig, this.templateParams, this.asyncapi);
     await this.configureTemplate();
 
     if (!isReactTemplate(this.templateConfig)) {
       await registerFilters(this.nunjucks, this.templateConfig, this.templateDir, FILTERS_DIRNAME);
     }
+
     await registerHooks(this.hooks, this.templateConfig, this.templateDir, HOOKS_DIRNAME);
     await this.launchHook('generate:before');
+  }
 
+  /**
+   * Handles the logic for the template entrypoint.
+   *
+   * If an entrypoint is specified:
+   * - Resolves the absolute path of the entrypoint file.
+   * - Throws an error if the entrypoint file doesn't exist.
+   * - Generates a file or renders content based on the output type.
+   * - Launches the 'generate:after' hook if the output is 'fs'.
+   *
+   * If no entrypoint is specified, generates the directory structure.
+   *
+   * @async
+   * @returns {Promise<void>} A promise that resolves when the entrypoint logic is completed.
+   */
+  async handleEntrypoint() {
     if (this.entrypoint) {
       const entrypointPath = path.resolve(this.templateContentDir, this.entrypoint);
-      if (!(await exists(entrypointPath))) throw new Error(`Template entrypoint "${entrypointPath}" couldn't be found.`);
+
+      if (!(await exists(entrypointPath))) {
+        throw new Error(`Template entrypoint "${entrypointPath}" couldn't be found.`);
+      }
+
       if (this.output === 'fs') {
         await this.generateFile(this.asyncapi, path.basename(entrypointPath), path.dirname(entrypointPath));
         await this.launchHook('generate:after');
@@ -205,10 +324,21 @@ class Generator {
       }
     } else {
       await this.generateDirectoryStructure(this.asyncapi);
-      await this.launchHook('generate:after');
     }
   }
 
+  /**
+   * Executes the 'generate:after' hook.
+   *
+   * Launches the after-hook to perform additional actions after code generation.
+   *
+   * @async
+   * @returns {Promise<void>} A promise that resolves when the after-hook execution is completed.
+   */
+  async executeAfterHook() {
+    await this.launchHook('generate:after');
+  }
+
   /**
    * Parse the generator input based on the template `templateConfig.apiVersion` value.
    */

package/lib/parser.js

@@ -8,17 +8,18 @@ const parser = module.exports;
  * Convert the template defined value `apiVersion: 'v1'` to only contain the numeric value `1`.
  */
 parser.sanitizeTemplateApiVersion = (apiVersion) => {
+  if (!apiVersion) return;
   if (apiVersion && apiVersion.length > 1) {
-    return apiVersion.substring(1);
+    return Number(apiVersion.substring(1));
   }
-  return apiVersion;
+  return Number(apiVersion);
 };
 
 parser.parse = async (asyncapi, oldOptions, generator) => {
   let apiVersion = this.sanitizeTemplateApiVersion(generator.templateConfig.apiVersion);
   // Defaulting to apiVersion v1 to convert it to the Parser-API v1 afterwards.
   if (!this.usesNewAPI(generator.templateConfig)) {
-    apiVersion = '1';
+    apiVersion = 1;
   }
   const options = convertOldOptionsToNew(oldOptions, generator);
   const parser = NewParser(apiVersion, {parserOptions: options, includeSchemaParsers: true});
@@ -34,7 +35,7 @@ parser.parse = async (asyncapi, oldOptions, generator) => {
  * If the template expect one of the Parser-API versions, it must be above 0
  */
 parser.usesNewAPI = (templateConfig = {}) => {
-  return Number(this.sanitizeTemplateApiVersion(templateConfig.apiVersion)) > 0;
+  return this.sanitizeTemplateApiVersion(templateConfig.apiVersion) > 0;
 };
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asyncapi/generator",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "The AsyncAPI generator. It can generate documentation, code, anything!",
   "main": "./lib/generator.js",
   "bin": {
@@ -51,7 +51,7 @@
     "@asyncapi/generator-react-sdk": "^0.2.23",
     "@asyncapi/parser": "2.1.0",
     "@npmcli/arborist": "^2.2.4",
-    "@smoya/multi-parser": "3.0.0",
+    "@smoya/multi-parser": "^4.0.0",
     "ajv": "^8.12.0",
     "chokidar": "^3.4.0",
     "commander": "^6.1.0",