Merge branch 'master' into cli.js-deprecation

.github/workflows/update-docs-in-website.yml

@@ -5,7 +5,7 @@ on:
     branches:
       - 'master'
     paths:
-      - 'docs/*.md'
+      - 'apps/generator/docs/*.md'
 
 jobs:
   Make-PR:
@@ -37,10 +37,10 @@ jobs:
         run: |
           rm -r ./markdown/docs/tools/generator
           mkdir -p ./markdown/docs/tools/generator
-          rm ../generator/docs/README.md
-          rm -r ../generator/docs/jsdoc2md-handlebars
+          rm ../generator/apps/generator/docs/README.md
+          rm -r ../generator/apps/generator/docs/jsdoc2md-handlebars
           printf "%s\ntitle: Generator\nweight: 3\n%s" "---" "---"> ../generator/docs/_section.md
-          mv ../generator/docs/*.md ./markdown/docs/tools/generator
+          mv ../generator/apps/generator/docs/*.md ./markdown/docs/tools/generator
       - name: Commit and push
         working-directory: ./website
         run: |

apps/generator/.gitignore

@@ -15,6 +15,7 @@ output
 out/
 coverage
 test/temp/integrationTestResult
+test/temp/reactTemplate
 test/test-project/package-lock.json
 test/test-project/verdaccio/storage/
 test/test-project/storage/

apps/generator/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @asyncapi/generator
 
+## 2.4.1
+
+### Patch Changes
+
+- 3a372c4: Removed the source-map-support package from the AsyncAPI Generator, as it is no longer required for version 2, which now supports Node.js version 18.12.0 and above.
+
+## 2.4.0
+
+### Minor Changes
+
+- 46114d8: Add `compile` option to enable rerun of transpilation of templates build with react engine. It is set to `true` by default. In future major releases it will be set to `false` and we will explain how to publish template to include transpilation files by default. Transpiled files are already included in [`html-template`](https://github.com/asyncapi/html-template/pull/575). It means that you can run generator for `html-template` (it's latest version) with `compile=false` and this will improve the speed of HTML generation for you.
+
 ## 2.3.0
 
 ### Minor Changes

apps/generator/docs/file-templates.md

@@ -3,7 +3,11 @@ title: "File templates"
 weight: 140
 ---
 
-It is possible to generate files for each specific object in your AsyncAPI documentation. For example, you can specify a filename like `$$channel$$.js` to generate a file for each channel defined in your AsyncAPI. The following file-template names and extra variables in them are available:
+## Generating files with the Nunjucks render engine
+
+> **Note**: This section applies only to the Nunjucks render engine. For information on using the React render engine, refer to the [Generating files with the React render engine](#generating-files-with-the-react-render-engine) section below.
+
+It is possible to generate files for each specific object in your AsyncAPI documentation using the Nunjucks render engine. For example, you can specify a filename like `$$channel$$.js` to generate a file for each channel defined in your AsyncAPI. The following file-template names and extra variables are available:
 
    - `$$channel$$`, within the template-file you have access to two variables [`channel`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#channel) and [`channelName`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#channels). Where the `channel` contains the current channel being rendered.
    - `$$message$$`, within the template-file you have access to two variables [`message`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#message) and [`messageName`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#message). Where `message` contains the current message being rendered.
@@ -25,7 +29,7 @@ Schema name is '{{schemaName}}' and properties are:
 {% endfor %}
 ```
 
-With following AsyncAPI:
+With the following AsyncAPI:
 ```
 components:
   schemas: 
@@ -53,15 +57,82 @@ Schema name is 'people' and properties are:
 - id
 ```
 
-### React
+> You can see an example of a file template that uses the Nunjucks render engine [here](https://github.com/asyncapi/template-for-generator-templates/tree/nunjucks/template/schemas).
+
+## Generating files with the React render engine
 
-The above way of rendering **file templates** works for both `nunjucks` and `react` render engines, but `react` also has another, more generic way to render multiple files. It is enough to return an array of `File` components in the rendering component. See the following example:
+The above method of rendering **file templates** only works for the Nunjucks render engine. To use the React render engine, you need to follow a different approach. The React render engine allows for a more generic way to render multiple files by returning an array of `File` components in the rendering component. This can be particularly useful for complex templates or when you need to generate a large number of files with varying content.
+
+### Example 1: Rendering hardcoded files
+
+The following is a simple hardcoded example of how to render multiple files using the React render engine:
 
 ```tsx
+import { File} from "@asyncapi/generator-react-sdk";
+
 export default function({ asyncapi }) {
   return [
     <File name={`file1.html`}>Content</File>,
     <File name={`file2.html`}>Content</File>
   ]
 }
-```
+```
+
+### Example 2: Rendering files based on the AsyncAPI Schema
+
+In practice, to render the multiple files, that are generated from the data defined in your AsyncAPI, you'll iterate over the array of schemas and generate a file for each schema as shown in the example below:
+
+```js
+import { File} from "@asyncapi/generator-react-sdk";
+
+/*
+ * To render multiple files, it is enough to return an array of `File` components in the rendering component, like in following example.
+ */
+export default function({ asyncapi }) {
+  const schemas = asyncapi.allSchemas();
+  const files = [];
+  // schemas is an instance of the Map
+  schemas.forEach((schema) => {
+
+    files.push(
+      // We return a react file component and each time we do it, the name of the generated file will be a schema name
+      // Content of the file will be a variable representing schema
+      <File name={`${schema.id()}.js`}>
+        const { schema.id() } = { JSON.stringify(schema._json, null, 2) }
+      </File>
+    );
+  });
+  return files;
+}
+```
+
+### Example 3: Rendering files for each channel
+
+Additionally, you can generate multiple files for each channel defined in your AsyncAPI specification using the React render engine as shown in the example below:
+
+```js
+import { File, Text } from "@asyncapi/generator-react-sdk";
+
+
+export default function ({ asyncapi }) {
+  const files = [];
+
+  // Generate files for channels
+  asyncapi.channels().forEach((channel) => {
+    const channelName = channel.id();
+
+    files.push(
+      <File name={`${channelName}.md`}>
+        <Text newLines={2}># Channel: {channelName}</Text>
+        <Text>
+          {channel.hasDescription() && `${channel.description()}`}
+        </Text>
+      </File>
+    );
+  });
+  return files;
+}
+```
+The code snippet above uses the `Text` component to write file content to the `.md` markdown file. The `newline` property is used to ensure that the content isn't all rendered in one line in the markdown file. In summary, the code snippet above is a practical guide on generating properly formatted multiline Markdown files for each channel in an AsyncAPI document.
+
+> You can see an example of a file template that uses the React render engine [here](https://github.com/asyncapi/template-for-generator-templates/blob/master/template/schemas/schema.js).

apps/generator/lib/generator.js

@@ -27,7 +27,6 @@ const {
   fetchSpec,
   isReactTemplate,
   isJsFile,
-  registerSourceMap,
   getTemplateDetails,
   convertCollectionToObject,
 } = require('./utils');
@@ -47,7 +46,7 @@ const DEFAULT_TEMPLATES_DIR = path.resolve(ROOT_DIR, 'node_modules');
 
 const TRANSPILED_TEMPLATE_LOCATION = '__transpiled';
 const TEMPLATE_CONTENT_DIRNAME = 'template';
-const GENERATOR_OPTIONS = ['debug', 'disabledHooks', 'entrypoint', 'forceWrite', 'install', 'noOverwriteGlobs', 'output', 'templateParams', 'mapBaseUrlToFolder', 'url', 'auth', 'token', 'registry'];
+const GENERATOR_OPTIONS = ['debug', 'disabledHooks', 'entrypoint', 'forceWrite', 'install', 'noOverwriteGlobs', 'output', 'templateParams', 'mapBaseUrlToFolder', 'url', 'auth', 'token', 'registry', 'compile'];
 const logMessage = require('./logMessages');
 
 const shouldIgnoreFile = filePath =>
@@ -57,8 +56,6 @@ const shouldIgnoreDir = dirPath =>
   dirPath === '.git'
   || dirPath.startsWith(`.git${path.sep}`);
 
-registerSourceMap();
-
 class Generator {
   /**
    * Instantiates a new Generator object.
@@ -86,20 +83,22 @@ class Generator {
    * @param {Boolean} [options.forceWrite=false] Force writing of the generated files to given directory even if it is a git repo with unstaged files or not empty dir. Default is set to false.
    * @param {Boolean} [options.install=false] Install the template and its dependencies, even when the template has already been installed.
    * @param {Boolean} [options.debug=false] Enable more specific errors in the console. At the moment it only shows specific errors about filters. Keep in mind that as a result errors about template are less descriptive.
+   * @param {Boolean} [options.compile=true] Whether to compile the template or use the cached transpiled version provided by template in '__transpiled' folder
    * @param {Object<String, String>} [options.mapBaseUrlToFolder] Optional parameter to map schema references from a base url to a local base folder e.g. url=https://schema.example.com/crm/  folder=./test/docs/ .
    * @param {Object} [options.registry]           Optional parameter with private registry configuration
    * @param {String} [options.registry.url]       Parameter to pass npm registry url
    * @param {String} [options.registry.auth]      Optional parameter to pass npm registry username and password encoded with base64, formatted like username:password value should be encoded
    * @param {String} [options.registry.token]     Optional parameter to pass npm registry auth token that you can grab from .npmrc file
    */
 
-  constructor(templateName, targetDir, { templateParams = {}, entrypoint, noOverwriteGlobs, disabledHooks, output = 'fs', forceWrite = false, install = false, debug = false, mapBaseUrlToFolder = {}, registry = {}} = {}) {
+  constructor(templateName, targetDir, { templateParams = {}, entrypoint, noOverwriteGlobs, disabledHooks, output = 'fs', forceWrite = false, install = false, debug = false, mapBaseUrlToFolder = {}, registry = {}, compile = true } = {}) {
     const options = arguments[arguments.length - 1];
     this.verifyoptions(options);
     if (!templateName) throw new Error('No template name has been specified.');
     if (!entrypoint && !targetDir) throw new Error('No target directory has been specified.');
     if (!['fs', 'string'].includes(output)) throw new Error(`Invalid output type ${output}. Valid values are 'fs' and 'string'.`);
-
+    /** @type {Boolean} Whether to compile the template or use the cached transpiled version provided by template in '__transpiled' folder. */
+    this.compile = compile;
     /** @type {Object} Npm registry information. */
     this.registry = registry;
     /** @type {String} Name of the template to generate. */
@@ -393,7 +392,7 @@ class Generator {
    * Configure the templates based the desired renderer.
    */
   async configureTemplate() {
-    if (isReactTemplate(this.templateConfig)) {
+    if (isReactTemplate(this.templateConfig) && this.compile) {
       await configureReact(this.templateDir, this.templateContentDir, TRANSPILED_TEMPLATE_LOCATION);
     } else {
       this.nunjucks = configureNunjucks(this.debug, this.templateDir);

apps/generator/lib/logMessages.js

@@ -46,6 +46,10 @@ function conditionalFilesMatched(relativeSourceFile) {
   return `${relativeSourceFile} was not generated because condition specified for this file in template configuration in conditionalFiles matched.`;
 }
 
+function compileEnabled(dir, output_dir) {
+  return `Transpilation of files ${dir} into ${output_dir} started.`;
+}
+
 module.exports = {
   TEMPLATE_INSTALL_FLAG_MSG,
   TEMPLATE_INSTALL_DISK_MSG,
@@ -59,5 +63,6 @@ module.exports = {
   templateSuccessfullyInstalled,
   relativeSourceFileNotGenerated,
   conditionalFilesMatched,
+  compileEnabled,
   skipOverwrite
 };

apps/generator/lib/renderer/react.js

@@ -16,9 +16,11 @@ const reactExport = module.exports;
  * @param {string} templateLocation located for thetemplate
  * @param {string} templateContentDir where the template content are located
  * @param {string} transpiledTemplateLocation folder for the transpiled code
+ * @param {Boolean} compile Whether to compile the template files or used the cached transpiled version provided by the template in the '__transpiled' folder
  */
 reactExport.configureReact = async (templateLocation, templateContentDir, transpiledTemplateLocation) => {
   const outputDir = path.resolve(templateLocation, `./${transpiledTemplateLocation}`);
+  log.debug(logMessage.compileEnabled(templateContentDir, outputDir));
   await AsyncReactSDK.transpileFiles(templateContentDir, outputDir, {
     recursive: true
   });

apps/generator/lib/utils.js

@@ -134,16 +134,6 @@ utils.isAsyncFunction = (fn) => {
   return fn && fn.constructor && fn.constructor.name === 'AsyncFunction';
 };
 
-/**
- * Register `source-map-support` package.
- * This package provides source map support for stack traces in Node - also for transpiled code from TS.
- *
- * @private
- */
-utils.registerSourceMap = () => {
-  require('source-map-support').install();
-};
-
 /**
  * Register TypeScript transpiler. It enables transpilation of TS filters and hooks on the fly.
  *

apps/generator/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asyncapi/generator",
-  "version": "2.3.0",
+  "version": "2.4.1",
   "description": "The AsyncAPI generator. It can generate documentation, code, anything!",
   "main": "./lib/generator.js",
   "bin": {
@@ -74,7 +74,6 @@
     "resolve-pkg": "^2.0.0",
     "semver": "^7.3.2",
     "simple-git": "^3.3.0",
-    "source-map-support": "^0.5.19",
     "ts-node": "^10.9.1",
     "typescript": "^4.9.3"
   },
@@ -87,6 +86,7 @@
     "jsdoc-to-markdown": "^7.1.1",
     "markdown-toc": "^1.2.0",
     "rimraf": "^3.0.2",
-    "unixify": "^1.0.0"
+    "unixify": "^1.0.0",
+    "fs-extra": "9.1.0"
   }
 }

apps/generator/test/generator.test.js

@@ -26,6 +26,7 @@ describe('Generator', () => {
       expect(gen.forceWrite).toStrictEqual(false);
       expect(gen.install).toStrictEqual(false);
       expect(gen.templateParams).toStrictEqual({});
+      expect(gen.compile).toStrictEqual(true);
     });
 
     it('works with all the params', () => {
@@ -39,6 +40,7 @@ describe('Generator', () => {
         templateParams: {
           test: true,
         },
+        compile: false,
       });
       expect(gen.templateName).toStrictEqual('testTemplate');
       expect(gen.targetDir).toStrictEqual(__dirname);
@@ -48,6 +50,7 @@ describe('Generator', () => {
       expect(gen.output).toStrictEqual('string');
       expect(gen.forceWrite).toStrictEqual(true);
       expect(gen.install).toStrictEqual(true);
+      expect(gen.compile).toStrictEqual(false);
       expect(() => gen.templateParams.test).toThrow('Template parameter "test" has not been defined in the package.json file under generator property. Please make sure it\'s listed there before you use it in your template.');
 
       // Mock params on templateConfig so it doesn't fail.