@asyncapi/generator 1.13.1 → 1.14.1

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,7 +26,15 @@ Reference API documentation for AsyncAPI Generator library.
         * [.hooks](#Generator+hooks) : `Object`
         * [.mapBaseUrlToFolder](#Generator+mapBaseUrlToFolder) : `Object`
         * [.templateParams](#Generator+templateParams) : `Object`
-        * [.generate(asyncapiDocument, [parseOptions])](#Generator+generate) ⇒ `Promise`
+        * [.generate(asyncapiDocument, [parseOptions])](#Generator+generate) ⇒ `Promise.<void>`
+        * [.validateAsyncAPIDocument(asyncapiDocument)](#Generator+validateAsyncAPIDocument)
+        * [.setupOutput()](#Generator+setupOutput)
+        * [.setupFSOutput()](#Generator+setupFSOutput) ⇒ `Promise.<void>`
+        * [.setLogLevel()](#Generator+setLogLevel) ⇒ `void`
+        * [.installAndSetupTemplate()](#Generator+installAndSetupTemplate) ⇒ `Promise.<{templatePkgName: string, templatePkgPath: string}>`
+        * [.configureTemplateWorkflow(parseOptions)](#Generator+configureTemplateWorkflow) ⇒ `Promise.<void>`
+        * [.handleEntrypoint()](#Generator+handleEntrypoint) ⇒ `Promise.<void>`
+        * [.executeAfterHook()](#Generator+executeAfterHook) ⇒ `Promise.<void>`
         * [.parseInput()](#Generator+parseInput)
         * [.configureTemplate()](#Generator+configureTemplate)
         * ~~[.generateFromString(asyncapiString, [parseOptions])](#Generator+generateFromString) ⇒ `Promise`~~
@@ -169,11 +177,19 @@ The template parameters. The structure for this object is based on each individu
 Generates files from a given template and an AsyncAPIDocument object.
 
 **Kind**: instance method of [`Generator`](#Generator)  
+**Returns**: `Promise.<void>` - A Promise that resolves when the generation is completed.  
 **Params**
 
 - 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.
+- [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 for the right parser depending on the template you are using.
 
+**Example**  
+```js
+await generator.generate(myAsyncAPIdocument);
+console.log('Done!');
+```
 **Example**  
 ```js
 generator
@@ -193,6 +209,118 @@ try {
 }
 ```
 
+<a name="Generator+validateAsyncAPIDocument"></a>
+
+### generator.validateAsyncAPIDocument
+Validates the provided AsyncAPI document.
+
+**Kind**: instance method of [`Generator`](#Generator)  
+**Throws**:
+
+- `Error` Throws an error if the document is not valid.
+
+**Since**: 10/9/2023 - 4:26:33 PM  
+**Params**
+
+- asyncapiDocument `*` - The AsyncAPI document to be validated.
+
+
+<a name="Generator+setupOutput"></a>
+
+* generator.setupOutput()** :
+Sets up the output configuration based on the specified output type.
+
+**Kind**: instance method of [`Generator`](#Generator)  
+**Throws**:
+
+- `Error` If 'output' is set to 'string' without providing 'entrypoint'.
+
+**Example**  
+```js
+const generator = new Generator();
+generator.setupOutput();
+```
+
+<a name="Generator+setupFSOutput"></a>
+
+* generator.setupFSOutput() ⇒ `Promise.<void>`** :
+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.
+
+**Kind**: instance method of [`Generator`](#Generator)  
+**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.
+
+
+<a name="Generator+setLogLevel"></a>
+
+* generator.setLogLevel() ⇒ `void`** :
+Sets the log level based on the debug option.
+
+If the debug option is enabled, the log level is set to 'debug'.
+
+**Kind**: instance method of [`Generator`](#Generator)  
+
+<a name="Generator+installAndSetupTemplate"></a>
+
+* generator.installAndSetupTemplate() ⇒ `Promise.<{templatePkgName: string, templatePkgPath: string}>`** :
+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.
+
+**Kind**: instance method of [`Generator`](#Generator)  
+**Returns**: `Promise.<{templatePkgName: string, templatePkgPath: string}>` - A promise that resolves to an object containing the name and path of the installed template.  
+
+<a name="Generator+configureTemplateWorkflow"></a>
+
+### generator.configureTemplateWorkflow
+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.
+
+**Kind**: instance method of [`Generator`](#Generator)  
+**Returns**: `Promise.<void>` - A promise that resolves when the configuration is completed.  
+**Params**
+
+- parseOptions `*` - Options for parsing the AsyncAPI document.
+
+
+<a name="Generator+handleEntrypoint"></a>
+
+* generator.handleEntrypoint() ⇒ `Promise.<void>`** :
+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.
+
+**Kind**: instance method of [`Generator`](#Generator)  
+**Returns**: `Promise.<void>` - A promise that resolves when the entrypoint logic is completed.  
+
+<a name="Generator+executeAfterHook"></a>
+
+* generator.executeAfterHook() ⇒ `Promise.<void>`** :
+Executes the 'generate:after' hook.
+
+Launches the after-hook to perform additional actions after code generation.
+
+**Kind**: instance method of [`Generator`](#Generator)  
+**Returns**: `Promise.<void>` - A promise that resolves when the after-hook execution is completed.  
+
 <a name="Generator+parseInput"></a>
 
 * generator.parseInput()** :

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asyncapi/generator",
-  "version": "1.13.1",
+  "version": "1.14.1",
   "description": "The AsyncAPI generator. It can generate documentation, code, anything!",
   "main": "./lib/generator.js",
   "bin": {
@@ -49,7 +49,7 @@
   "homepage": "https://github.com/asyncapi/generator",
   "dependencies": {
     "@asyncapi/generator-react-sdk": "^0.2.23",
-    "@asyncapi/parser": "2.1.0",
+    "@asyncapi/parser": "^2.1.1",
     "@npmcli/arborist": "^2.2.4",
     "@smoya/multi-parser": "^4.0.0",
     "ajv": "^8.12.0",