@asyncapi/converter 0.6.0

package/README.md

@@ -0,0 +1,60 @@
+# AsyncAPI Converter
+
+Convert [AsyncAPI](https://asyncapi.com) documents older to newer versions.
+
+## Installation
+
+```sh
+npm i -g @asyncapi/converter
+```
+
+## Usage
+
+### From CLI
+
+Minimal example:
+
+```sh
+asyncapi-converter streetlights.yml
+
+# Result:
+asyncapi: '2.0.0'
+channels:
+...
+```
+
+Specify the application id:
+
+```sh
+asyncapi-converter --id=urn:com.asynapi.streetlights streetlights.yml
+
+# Result:
+asyncapi: '2.0.0'
+id: 'urn:com.asynapi.streetlights'
+...
+```
+
+Save the result in a file:
+
+```sh
+asyncapi-converter streetlights.yml > streetlights2.yml
+```
+
+### As a package
+
+```js
+const { convert } = require('@asyncapi/converter')
+
+try {
+  const asyncapi = fs.readFileSync('streetlights.yml', 'utf-8')
+  console.log(convert(asyncapi, '2.0.0', {
+      id: 'urn:com.asyncapi.streetlights'
+  }))
+} catch (e) {
+  console.error(e)
+}
+```
+
+## Known missing features
+
+* When converting from 1.x to 2.x, Streaming APIs (those using `stream` instead of `topics` or `events`) are converted correctly but information about framing type and delimiter is missing until a [protocolInfo](https://github.com/asyncapi/extensions-catalog/issues/1) for that purpose is created.

package/cli.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const fs = require('fs');
+const program = require('commander');
+const packageInfo = require('./package.json');
+const converter = require('./lib');
+
+const red = text => `\x1b[31m${text}\x1b[0m`;
+
+let asyncapiFile;
+let version;
+
+const showErrorAndExit = err => {
+  console.error(red('Something went wrong:'));
+  console.error(red(err.stack || err.message));
+  process.exit(1);
+};
+
+program
+  .version(packageInfo.version)
+  .arguments('<document> [version]')
+  .action((asyncAPIPath, v) => {
+    asyncapiFile = path.resolve(asyncAPIPath);
+    version = v;
+  })
+  .option('--id <id>', 'application id (defaults to a generated one)')
+  .parse(process.argv);
+
+if (!asyncapiFile) {
+  console.error(red('> Path to AsyncAPI file not provided.'));
+  program.help(); // This exits the process
+}
+if (!version) {
+  version = '2.1.0';
+}
+
+try {
+  const asyncapi = fs.readFileSync(asyncapiFile, 'utf-8');
+  console.log(converter.convert(asyncapi, version, {
+    id: program.id,
+  }));
+} catch (e) {
+  showErrorAndExit(e);
+}
+
+process.on('unhandledRejection', showErrorAndExit);

package/lib/helpers.js

@@ -0,0 +1,91 @@
+const _ = require('lodash');
+const yaml = require('js-yaml');
+const helpers = module.exports;
+
+helpers.serialize = (text) => {
+    try {
+        return {
+            isYAML: true,
+            parsed: yaml.safeLoad(text)
+        };
+    } catch (e) {
+        try {
+            return {
+                isYAML: false,
+                parsed: JSON.parse(text)
+            };
+        } catch (err) {
+            throw new Error('AsyncAPI document must be a valid JSON or YAML document.');
+        }
+    }
+};
+
+helpers.dotsToSlashes = topic => topic.replace(/\./g, '/');
+
+helpers.eventToChannel = event => {
+    const out = {};
+    if (event.receive) {
+        out.publish = {
+            message: {
+                oneOf: event.receive
+            }
+        }
+    }
+    if (event.send) {
+        out.subscribe = {
+            message: {
+                oneOf: event.send
+            }
+        }
+    }
+
+    return out;
+};
+
+helpers.streamToChannel = event => {
+    const out = {};
+    if (event.read) {
+        out.publish = {
+            message: {
+                oneOf: event.read
+            }
+        }
+    }
+    if (event.write) {
+        out.subscribe = {
+            message: {
+                oneOf: event.write
+            }
+        }
+    }
+
+    return out;
+};
+
+const objectToSchema = obj => {
+    const schema = { type: 'object', properties: {} };
+    _.each(obj, (prop, propName) => {
+        schema.properties[propName] = prop;
+    });
+    return obj;
+};
+
+helpers.convertMessage = message => {
+    if (message.oneOf) {
+        message.oneOf.forEach(m => {
+            if (m.protocolInfo) {
+                m.bindings = m.protocolInfo;
+                delete m.protocolInfo;
+            }
+            
+            if (m.headers) m.headers = objectToSchema(m.headers);
+        });
+    } else {
+        if (message.protocolInfo) {
+            message.bindings = message.protocolInfo;
+            delete message.protocolInfo;
+        }
+
+        if (message.headers) message.headers = objectToSchema(message.headers);
+    }
+}

package/lib/index.js

@@ -0,0 +1,204 @@
+const yaml = require('js-yaml');
+const _ = require('lodash');
+const {
+  serialize,
+  dotsToSlashes,
+  eventToChannel,
+  streamToChannel,
+  convertMessage,
+} = require('./helpers');
+
+const lib = module.exports;
+
+/**
+ * Value for key (version) represents the function which converts specification from previous version to the given as key.
+ */
+const conversions = {
+  '1.0.0': undefined,
+  '1.1.0': from__1_0_0__to__1_1_0,
+  '1.2.0': from__1_1_0__to__1_2_0,
+  '2.0.0-rc1': from__1_2_0__to__2_0_0_rc1,
+  '2.0.0-rc2': from__2_0_0_rc1__to__2_0_0_rc2,
+  '2.0.0': from__2_0_0_rc2__to__2_0_0,
+  '2.1.0': from__2_0_0__to__2_1_0,
+  '2.2.0': from__2_1_0__to__2_2_0,
+}
+const conversionVersions = Object.keys(conversions);
+
+lib.convert = (asyncapi, version, options = {}) => {
+  const { isYAML, parsed } = serialize(asyncapi);
+  if (parsed === undefined) return '';
+
+  let fromVersion = conversionVersions.indexOf(parsed.asyncapi);
+  const toVersion = conversionVersions.indexOf(version);
+
+  if (fromVersion === -1 || toVersion === -1) {
+    console.error(`Cannot convert from ${parsed.asyncapi} to ${version}.`);
+    return;
+  }
+  if (fromVersion > toVersion) {
+    console.error(`Cannot downgrade from ${parsed.asyncapi} to ${version}.`);
+    return;
+  }
+  if (fromVersion === toVersion) {
+    console.error(`Cannot convert to the same version.`);
+    return;
+  }
+
+  // add 1 to `fromVersion` because we convert from previous to next
+  fromVersion++;
+  let converted = parsed;
+  for (let i = fromVersion; i <= toVersion; i++) {
+    const fn = conversions[conversionVersions[i]];
+    converted = fn(converted, options);
+  }
+
+  if (isYAML) {
+    converted = yaml.safeDump(converted, { skipInvalid: true });
+  }
+  return converted;
+};
+
+function from__1_0_0__to__1_1_0(asyncapi) {
+  return asyncapi;
+}
+
+function from__1_1_0__to__1_2_0(asyncapi) {
+  return asyncapi;
+}
+
+function from__1_2_0__to__2_0_0_rc1(asyncapi1, options) { // NOSONAR
+  const result = asyncapi1;
+
+  result.asyncapi = '2.0.0-rc1';
+  result.id = options.id || `urn:${asyncapi1.info.title.toLowerCase().split(' ').join('.')}`;
+  
+  if (asyncapi1.servers) {
+    const security = asyncapi1.security;
+    result.servers = asyncapi1.servers.map(server => {
+      const { scheme, schemeVersion, ...rest } = server;
+      
+      const out = {
+        ...rest,
+        ...{
+          protocol: scheme,
+        }
+      };
+
+      if (schemeVersion) out.protocolVersion = schemeVersion;
+
+      if (security) {
+        out.security = security;
+      }
+
+      return out;
+    });
+  }
+  
+  if (asyncapi1.topics) {
+    result.channels = _.mapKeys(result.topics, (_, topicName) => dotsToSlashes(`${asyncapi1.baseTopic ? `${asyncapi1.baseTopic}.` : ''}${topicName}`));
+    _.map(result.channels, ch => {
+      if (ch.publish) {
+        ch.publish = { message: ch.publish };
+      }
+      if (ch.subscribe) {
+        ch.subscribe = { message: ch.subscribe };
+      }
+    });
+  } else if (asyncapi1.stream) {
+    result.channels = {
+      '/': streamToChannel(asyncapi1.stream),
+    };
+  } else if (asyncapi1.events) {
+    result.channels = {
+      '/': eventToChannel(asyncapi1.events),
+    };
+  }
+  
+  delete result.topics;
+  delete result.stream;
+  delete result.events;
+  delete result.baseTopic;
+  delete result.security;
+
+  return result;
+}
+
+function from__2_0_0_rc1__to__2_0_0_rc2(asyncapi2rc1, options) { // NOSONAR
+  const result = asyncapi2rc1;
+
+  result.asyncapi = '2.0.0-rc2';
+  result.id = result.id || options.id;
+  
+  if (asyncapi2rc1.servers) {
+    const serverMap = {};
+    asyncapi2rc1.servers.forEach((server, index) => {
+      if (server.baseChannel) delete server.baseChannel;
+      const name = index === 0 ? 'default' : `server${index}`;
+      serverMap[name] = server;
+    });
+    result.servers = serverMap;
+  }
+  
+  if (result.channels) {
+    _.each(result.channels, (channel, channelName) => {
+      if (channel.parameters) {
+        const parametersMap = {};
+        const paramNames = channelName.match(/\{([^\}]{1,100})\}/g).map(p => p.substr(1, p.length - 2));
+        channel.parameters.forEach((parameter, index) => {
+          const name = parameter.name || paramNames[index];
+          if (parameter.name) delete parameter.name;
+          parametersMap[name] = parameter;
+        });
+        channel.parameters = parametersMap;
+      }
+
+      if (channel.publish && channel.publish.message) {
+        const message = channel.publish.message;
+        convertMessage(message);
+      }
+      
+      if (channel.subscribe && channel.subscribe.message) {
+        const message = channel.subscribe.message;
+        convertMessage(message);
+      }
+
+      if (channel.protocolInfo) {
+        channel.bindings = channel.protocolInfo;
+        delete channel.protocolInfo;
+      }
+
+      if (channel.publish && channel.publish.protocolInfo) {
+        channel.publish.bindings = channel.publish.protocolInfo;
+        delete channel.publish.protocolInfo;
+      }
+
+      if (channel.subscribe && channel.subscribe.protocolInfo) {
+        channel.subscribe.bindings = channel.subscribe.protocolInfo;
+        delete channel.subscribe.protocolInfo;
+      }
+    }); 
+  }
+
+  if (!options.id) delete result.id;
+  return result;
+}
+
+function from__2_0_0_rc2__to__2_0_0(asyncapi2rc2, options) {
+  const result = asyncapi2rc2;
+  if (!options.id) delete result.id;
+  result.asyncapi = '2.0.0';
+  return result;
+}
+
+function from__2_0_0__to__2_1_0(asyncapi2) {
+  const result = asyncapi2;
+  result.asyncapi = '2.1.0';
+  return result;
+}
+
+function from__2_1_0__to__2_2_0(asyncapi2) {
+  const result = asyncapi2;
+  result.asyncapi = '2.2.0';
+  return result;
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+	"name": "@asyncapi/converter",
+	"version": "0.6.0",
+	"description": "Convert AsyncAPI documents from older to newer versions.",
+	"bin": {
+		"asyncapi-converter": "cli.js"
+	},
+	"main": "lib/index.js",
+	"scripts": {
+		"test": "mocha",
+		"lint": "echo 'no linter configured yet'",
+		"release": "semantic-release",
+		"generate:assets": "echo 'No additional assets need to be generated at the moment'",
+		"bump:version": "npm --no-git-tag-version --allow-same-version version $VERSION"
+	},
+	"keywords": [
+		"asyncapi",
+		"upgrade",
+		"version",
+		"convert"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/asyncapi/converter-js.git"
+	},
+	"bugs": {
+		"url": "https://github.com/asyncapi/converter-js/issues"
+	},
+	"homepage": "https://github.com/asyncapi/converter-js#readme",
+	"publishConfig": {
+		"access": "public"
+	},
+	"author": "Fran Mendez <fmvilas@gmail.com> (fmvilas.com)",
+	"license": "Apache-2.0",
+	"dependencies": {
+		"commander": "^2.20.0",
+		"js-yaml": "^3.13.1",
+		"lodash": "^4.17.15",
+		"mocha": "^6.1.4"
+	},
+	"devDependencies": {
+		"@semantic-release/commit-analyzer": "^8.0.1",
+		"@semantic-release/github": "^7.0.4",
+		"@semantic-release/npm": "^7.0.3",
+		"@semantic-release/release-notes-generator": "^9.0.1",
+		"conventional-changelog-conventionalcommits": "^4.2.3",
+		"semantic-release": "^17.0.4"
+	},
+	"release": {
+		"branches": [
+			"master"
+		],
+		"plugins": [
+			[
+				"@semantic-release/commit-analyzer",
+				{
+					"preset": "conventionalcommits"
+				}
+			],
+			[
+				"@semantic-release/release-notes-generator",
+				{
+					"preset": "conventionalcommits"
+				}
+			],
+			"@semantic-release/npm",
+			"@semantic-release/github"
+		]
+	}
+}

package/test/index.js

@@ -0,0 +1,194 @@
+const assert = require('assert');
+const fs = require('fs');
+const path = require("path");
+const { convert } = require('../lib');
+
+describe('#convert', () => {
+    it('should not convert to lowest version', () => {
+        const result = convert(`asyncapi: '2.1.0'`, '2.0.0');
+        assert.strictEqual(result, undefined);
+    });
+
+    it('should not convert from non existing version', () => {
+        const result = convert(`asyncapi: '2.0.0-rc3'`, '2.1.0');
+        assert.strictEqual(result, undefined);
+    });
+
+    it('should not convert to this same version', () => {
+        const result = convert(`asyncapi: '2.1.0'`, '2.1.0');
+        assert.strictEqual(result, undefined);
+    });
+
+    it('should convert from 1.0.0 to 2.0.0-rc1', () => {
+        const input = fs.readFileSync(path.resolve(__dirname, 'input', '1.0.0', 'streetlights.yml'), 'utf8');
+        const output = fs.readFileSync(path.resolve(__dirname, 'output', '2.0.0-rc1', 'streetlights.yml'), 'utf8');
+        const result = convert(input, '2.0.0-rc1');
+        assertResults(output, result);
+    });
+    
+    it('should convert from 1.1.0 to 2.0.0-rc1', () => {
+        const input = fs.readFileSync(path.resolve(__dirname, 'input', '1.1.0', 'streetlights.yml'), 'utf8');
+        const output = fs.readFileSync(path.resolve(__dirname, 'output', '2.0.0-rc1', 'streetlights.yml'), 'utf8');
+        const result = convert(input, '2.0.0-rc1');
+        assertResults(output, result);
+    });
+    
+    it('should convert from 1.2.0 to 2.0.0-rc1', () => {
+        const input = fs.readFileSync(path.resolve(__dirname, 'input', '1.2.0', 'streetlights.yml'), 'utf8');
+        const output = fs.readFileSync(path.resolve(__dirname, 'output', '2.0.0-rc1', 'streetlights.yml'), 'utf8');
+        const result = convert(input, '2.0.0-rc1');
+        assertResults(output, result);
+    });
+    
+    it('should convert from 1.2.0 to 2.0.0-rc1 - stream', () => {
+        const input = fs.readFileSync(path.resolve(__dirname, 'input', '1.2.0', 'gitter-streaming.yml'), 'utf8');
+        const output = fs.readFileSync(path.resolve(__dirname, 'output', '2.0.0-rc1', 'gitter-streaming.yml'), 'utf8');
+        const result = convert(input, '2.0.0-rc1');
+        assertResults(output, result);
+    });
+    
+    it('should convert from 1.2.0 to 2.0.0-rc1 - events', () => {
+        const input = fs.readFileSync(path.resolve(__dirname, 'input', '1.2.0', 'slack-rtm.yml'), 'utf8');
+        const output = fs.readFileSync(path.resolve(__dirname, 'output', '2.0.0-rc1', 'slack-rtm.yml'), 'utf8');
+        const result = convert(input, '2.0.0-rc1');
+        assertResults(output, result);
+    });
+    
+    it('should convert from 1.0.0 to 2.0.0-rc2', () => {
+        const input = fs.readFileSync(path.resolve(__dirname, 'input', '1.0.0', 'streetlights.yml'), 'utf8');
+        const output = fs.readFileSync(path.resolve(__dirname, 'output', '2.0.0-rc2', 'streetlights.yml'), 'utf8');
+        const result = convert(input, '2.0.0-rc2');
+        assertResults(output, result);
+    });
+    
+    it('should convert from 1.1.0 to 2.0.0-rc2', () => {
+        const input = fs.readFileSync(path.resolve(__dirname, 'input', '1.1.0', 'streetlights.yml'), 'utf8');
+        const output = fs.readFileSync(path.resolve(__dirname, 'output', '2.0.0-rc2', 'streetlights.yml'), 'utf8');
+        const result = convert(input, '2.0.0-rc2');
+        assertResults(output, result);
+    });
+    
+    it('should convert from 1.2.0 to 2.0.0-rc2 - stream', () => {
+        const input = fs.readFileSync(path.resolve(__dirname, 'input', '1.2.0', 'gitter-streaming.yml'), 'utf8');
+        const output = fs.readFileSync(path.resolve(__dirname, 'output', '2.0.0-rc2', 'gitter-streaming.yml'), 'utf8');
+        const result = convert(input, '2.0.0-rc2');
+        assertResults(output, result);
+    });
+    
+    it('should convert from 1.2.0 to 2.0.0-rc2 - events', () => {
+        const input = fs.readFileSync(path.resolve(__dirname, 'input', '1.2.0', 'slack-rtm.yml'), 'utf8');
+        const output = fs.readFileSync(path.resolve(__dirname, 'output', '2.0.0-rc2', 'slack-rtm.yml'), 'utf8');
+        const result = convert(input, '2.0.0-rc2');
+        assertResults(output, result);
+    });
+
+    it('should convert from 1.2.0 to 2.0.0-rc2', () => {
+        const input = fs.readFileSync(path.resolve(__dirname, 'input', '1.2.0', 'streetlights.yml'), 'utf8');
+        const output = fs.readFileSync(path.resolve(__dirname, 'output', '2.0.0-rc2', 'streetlights.yml'), 'utf8');
+        const result = convert(input, '2.0.0-rc2');
+        assertResults(output, result);
+    });
+
+    it('should convert from 1.0.0 to 2.0.0', () => {
+        const input = fs.readFileSync(path.resolve(__dirname, 'input', '1.0.0', 'streetlights.yml'), 'utf8');
+        const output = fs.readFileSync(path.resolve(__dirname, 'output', '2.0.0', 'streetlights.yml'), 'utf8');
+        const result = convert(input, '2.0.0');
+        assertResults(output, result);
+    });
+
+    it('should convert from 1.1.0 to 2.0.0', () => {
+        const input = fs.readFileSync(path.resolve(__dirname, 'input', '1.1.0', 'streetlights.yml'), 'utf8');
+        const output = fs.readFileSync(path.resolve(__dirname, 'output', '2.0.0', 'streetlights.yml'), 'utf8');
+        const result = convert(input, '2.0.0');
+        assertResults(output, result);
+    });
+
+    it('should convert from 1.2.0 to 2.0.0', () => {
+        const input = fs.readFileSync(path.resolve(__dirname, 'input', '1.2.0', 'streetlights.yml'), 'utf8');
+        const output = fs.readFileSync(path.resolve(__dirname, 'output', '2.0.0', 'streetlights.yml'), 'utf8');
+        const result = convert(input, '2.0.0');
+        assertResults(output, result);
+    });
+
+    it('should convert from 2.0.0-rc1 to 2.0.0', () => {
+        const input = fs.readFileSync(path.resolve(__dirname, 'input', '2.0.0-rc1', 'streetlights.yml'), 'utf8');
+        const output = fs.readFileSync(path.resolve(__dirname, 'output', '2.0.0', 'streetlights.yml'), 'utf8');
+        const result = convert(input, '2.0.0');
+        assertResults(output, result);
+    });
+
+    it('should convert from 2.0.0-rc2 to 2.0.0', () => {
+        const input = fs.readFileSync(path.resolve(__dirname, 'input', '2.0.0-rc2', 'streetlights.yml'), 'utf8');
+        const output = fs.readFileSync(path.resolve(__dirname, 'output', '2.0.0', 'streetlights.yml'), 'utf8');
+        const result = convert(input, '2.0.0');
+        assertResults(output, result);
+    });
+
+    it('should convert from 1.0.0 to 2.1.0', () => {
+        const input = fs.readFileSync(path.resolve(__dirname, 'input', '1.0.0', 'streetlights.yml'), 'utf8');
+        const output = fs.readFileSync(path.resolve(__dirname, 'output', '2.1.0', 'streetlights.yml'), 'utf8');
+        const result = convert(input, '2.1.0');
+        assertResults(output, result);
+    });
+
+    it('should convert from 1.1.0 to 2.1.0', () => {
+        const input = fs.readFileSync(path.resolve(__dirname, 'input', '1.1.0', 'streetlights.yml'), 'utf8');
+        const output = fs.readFileSync(path.resolve(__dirname, 'output', '2.1.0', 'streetlights.yml'), 'utf8');
+        const result = convert(input, '2.1.0');
+        assertResults(output, result);
+    });
+
+    it('should convert from 1.2.0 to 2.1.0', () => {
+        const input = fs.readFileSync(path.resolve(__dirname, 'input', '1.2.0', 'streetlights.yml'), 'utf8');
+        const output = fs.readFileSync(path.resolve(__dirname, 'output', '2.1.0', 'streetlights.yml'), 'utf8');
+        const result = convert(input, '2.1.0');
+        assertResults(output, result);
+    });
+
+    it('should convert from 2.0.0-rc1 to 2.1.0', () => {
+        const input = fs.readFileSync(path.resolve(__dirname, 'input', '2.0.0-rc1', 'streetlights.yml'), 'utf8');
+        const output = fs.readFileSync(path.resolve(__dirname, 'output', '2.1.0', 'streetlights.yml'), 'utf8');
+        const result = convert(input, '2.1.0');
+        assertResults(output, result);
+    });
+
+    it('should convert from 2.0.0-rc2 to 2.1.0', () => {
+        const input = fs.readFileSync(path.resolve(__dirname, 'input', '2.0.0-rc2', 'streetlights.yml'), 'utf8');
+        const output = fs.readFileSync(path.resolve(__dirname, 'output', '2.1.0', 'streetlights.yml'), 'utf8');
+        const result = convert(input, '2.1.0');
+        assertResults(output, result);
+    });
+
+    it('should convert from 2.0.0 to 2.1.0', () => {
+        const input = fs.readFileSync(path.resolve(__dirname, 'input', '2.0.0', 'streetlights.yml'), 'utf8');
+        const output = fs.readFileSync(path.resolve(__dirname, 'output', '2.1.0', 'streetlights.yml'), 'utf8');
+        const result = convert(input, '2.1.0');
+        assertResults(output, result);
+    });
+
+    it('should convert from 2.0.0 to 2.2.0', () => {
+        const input = fs.readFileSync(path.resolve(__dirname, 'input', '2.0.0', 'streetlights.yml'), 'utf8');
+        const output = fs.readFileSync(path.resolve(__dirname, 'output', '2.2.0', 'streetlights.yml'), 'utf8');
+        const result = convert(input, '2.2.0');
+        assertResults(output, result);
+    });
+
+    it('should convert from 2.1.0 to 2.2.0', () => {
+        const input = fs.readFileSync(path.resolve(__dirname, 'input', '2.1.0', 'streetlights.yml'), 'utf8');
+        const output = fs.readFileSync(path.resolve(__dirname, 'output', '2.2.0', 'streetlights.yml'), 'utf8');
+        const result = convert(input, '2.2.0');
+        assertResults(output, result);
+    });
+});
+
+/*
+  It is a helper required for testing on windows. It can't be solved by editor configuration and the end line setting because expected result is converted during tests.
+  We need to remove all line breaks from the string
+*/
+function removeLineBreaks(str) {
+    return str.replace(/\r?\n|\r/g, '')
+}
+
+function assertResults(output, result){
+    assert.strictEqual(removeLineBreaks(output), removeLineBreaks(result));
+}