feat: migration of the codebase to TypeScript (#56)

Co-authored-by: Maciej Urbańczyk <[email protected]>

API.md

@@ -49,9 +49,9 @@
 ```js
 const document = new Document(parsedJSONList, base);
 
-console.log(document.json()); // get json object
-console.log(document.yml()); // get yaml string
-console.log(document.string()); // get json string
+console.log(document.json()); // get JSON object
+console.log(document.yml()); // get YAML string
+console.log(document.string()); // get JSON string
 ```
 <a name="Document+json"></a>
 
@@ -83,22 +83,26 @@ console.log(document.string()); // get json string
 
 | Param | Type | Description |
 | --- | --- | --- |
-| files | <code>Array.&lt;string&gt;</code> | <p>Array of stringified AsyncAPI documents in YAML format, that are to be bundled.</p> |
+| files | <code>Array.&lt;string&gt;</code> | <p>Array of stringified AsyncAPI documents in YAML format, that are to be bundled (or array of filepaths, resolved and fed through <code>Array.map()</code> and <code>fs.readFileSync</code>, which is the same, see <code>README.md</code>).</p> |
 | [options] | <code>Object</code> | |
 | [options.base] | <code>string</code> \| <code>object</code> | <p>Base object whose properties will be retained.</p> |
 | [options.referenceIntoComponents] | <code>boolean</code> | <p>Pass <code>true</code> to resolve external references to components.</p> |
 
 **Example** 
 ```js
-const bundle = require('@asyncapi/bundler');
-const fs = require('fs');
-const path = require('path');
+import { readFileSync, writeFileSync } from 'fs';
+import bundle from '@asyncapi/bundler';
 
-const document = await bundle(fs.readFileSync(
- path.resolve('./asyncapi.yaml', 'utf-8')
-));
+async function main() {
+ const document = await bundle([readFileSync('./main.yaml', 'utf-8')], {
+ referenceIntoComponents: true,
+ });
 
-console.log(document.yml());
+console.log(document.yml()); // the complete bundled AsyncAPI document
+writeFileSync('asyncapi.yaml', document.yml()); // the complete bundled AsyncAPI document
+}
+
+main().catch(e => console.error(e));
 ```
 <a name="bundle..resolvedJsons"></a>
 

README.md

@@ -12,12 +12,12 @@
 - [Installation](#installation)
 - [Usage](#usage)
  * [Resolving external references into components](#resolving-external-references-into-components)
-- [bundle(files, options)](#bundlefiles-options)
+- [bundle(files, [options])](#bundlefiles-options)
 
 <!-- tocstop -->
 
 ## Overview
-An official library that lets you bundle/merge your specification files into one. AsyncAPI bundler can help you if:
+An official library that lets you bundle/merge your specification files into one. AsyncAPI Bundler can help you if:
 
 <details>
 <summary>your specification file is divided into different smaller files and is using JSON `$ref` property to reference components </summary>
@@ -36,7 +36,7 @@ channels:
  message:
  $ref: './messages.yaml#/messages/UserSignedUp'
 
-#messages.yaml
+# messages.yaml
 messages:
  UserSignedUp:
  payload:
@@ -160,22 +160,25 @@ npm install @asyncapi/bundler
 
 ## Usage
 
-AsyncAPI bundler can be easily used within your JavaScript project as a Node.js module:
+AsyncAPI Bundler can be easily used within your TypeScript project:
 
-```js
-const bundle = require('@asyncapi/bundler');
-const fs = require('fs');
-const path = require('path');
+```ts
+import { readFileSync, writeFileSync } from 'fs';
+import bundle from '@asyncapi/bundler';
+
+async function main() {
+ const filePaths = ['./camera.yml','./audio.yml'];
+ const document = await bundle(
+ filePaths.map(filePath => readFileSync(filePath, 'utf-8')), {
+ base: readFileSync('./base.yml', 'utf-8'),
+ }
+ );
 
-const filePaths = ['./camera.yml','./audio.yml']
-const document = await bundle(
- filePaths.map(filePath => fs.readFileSync(path.resolve(filePath), 'utf-8')),
- {
- base: fs.readFileSync(path.resolve('./base.yml'), 'utf-8')
- }
-);
+ console.log(document.yml()); // the complete bundled AsyncAPI document
+ writeFileSync('asyncapi.yaml', document.yml()); // the complete bundled AsyncAPI document
+}
 
-console.log(document.json()); // the complete bundled AsyncAPI document
+main().catch(e => console.error(e));
 ```
 
 ### Resolving external references into components
@@ -185,19 +188,28 @@ You can resolve external references by moving them to Messages Object, under `co
 <summary>For example</summary>
 
 ```yml
-# asyncapi.yaml
-asyncapi: '2.4.0'
+# main.yaml
+asyncapi: 2.5.0
 info:
  title: Account Service
  version: 1.0.0
  description: This service is in charge of processing user signups
 channels:
- user/signup:
+ user/signedup:
  subscribe:
  message:
  $ref: './messages.yaml#/messages/UserSignedUp'
+ test:
+ subscribe:
+ message:
+ $ref: '#/components/messages/TestMessage'
+components:
+ messages:
+ TestMessage:
+ payload:
+ type: string
 
-#messages.yaml
+# messages.yaml
 messages:
  UserSignedUp:
  payload:
@@ -210,9 +222,15 @@ messages:
  type: string
  format: email
  description: Email of the user
+ UserLoggedIn:
+ payload:
+ type: object
+ properties:
+ id: string
 
-# After combining 
-asyncapi: 2.4.0
+# After combining
+# asyncapi.yaml
+asyncapi: 2.5.0
 info:
  title: Account Service
  version: 1.0.0
@@ -222,8 +240,15 @@ channels:
  subscribe:
  message:
  $ref: '#/components/messages/UserSignedUp'
-components: 
+ test:
+ subscribe:
+ message:
+ $ref: '#/components/messages/TestMessage'
+components:
  messages:
+ TestMessage:
+ payload:
+ type: string
  UserSignedUp:
  payload:
  type: object
@@ -235,33 +260,38 @@ components:
  type: string
  format: email
  description: Email of the user
+
 ```
 </details>
 
 </br>
 
 ```ts
-const bundle = require('@asyncapi/bundler')
-const fs = require('fs')
-const path = require('path')
+import { readFileSync, writeFileSync } from 'fs';
+import bundle from '@asyncapi/bundler';
 
-const document = await bundle(
- fs.readFileSync(path.resolve('./asyncapi.yml'), 'utf-8'),
- { referenceIntoComponents: true }
- );
+async function main() {
+ const document = await bundle([readFileSync('./main.yaml', 'utf-8')], {
+ referenceIntoComponents: true,
+ });
+
+ console.log(document.yml()); // the complete bundled AsyncAPI document
+ writeFileSync('asyncapi.yaml', document.yml()); // the complete bundled AsyncAPI document
+}
 
-console.log(document.json()); 
+main().catch(e => console.error(e));
+
 ```
 
 
 <a name="bundle"></a>
 
-## bundle(files, options)
+## bundle(files, [options])
 **Kind**: global function
 
 | Param | Type | Description |
 | --- | --- | --- |
-| files | <code>Array.&lt;string&gt; | Array of stringified AsyncAPI documents in YAML format, that are to be bundled. |
+| files | <code>Array.&lt;string&gt; | Array of stringified AsyncAPI documents in YAML format, that are to be bundled (or array of filepaths, resolved and fed through `Array.map()` and `fs.readFileSync`, which is the same). |
 | [options] | <code>Object</code> | |
 | [options.base] | <code>string</code> \| <code>object</code> | Base object whose properties will be retained. |
 | [options.referenceIntoComponents] | <code>boolean<code> | Pass `true` to resolve external references to components. |

example/asyncapi.yaml

@@ -1,10 +1,10 @@
-asyncapi: 2.2.0
+asyncapi: 2.5.0
 info:
  title: Account Service
  version: 1.0.0
  description: This service is in charge of processing user signups
 channels:
- user/signup:
+ user/signedup:
  subscribe:
  message:
  $ref: '#/components/messages/UserSignedUp'

example/audio.yml

@@ -0,0 +1,50 @@
+asyncapi: 2.0.0
+id: 'urn:zbos-mqtt-api'
+defaultContentType: application/json
+info:
+ title: Audio
+ version: 2.6.3
+ description: API for communication with ZBOS by Zora Robotics.
+ contact:
+ email: [email protected]
+channels:
+ zbos/audio/player/start:
+ publish:
+ summary: Play media
+ description: |
+ Play specific media from audio options
+ tags:
+ - name: Audio
+ description: All audio related topics.
+ message:
+ payload:
+ type: object
+ properties:
+ requestId:
+ type: string
+ url:
+ type: string
+ loop:
+ type: boolean
+ name: AudioOptions
+ examples:
+ - payload:
+ requestId: '1'
+ url: Url
+ loop: true
+ zbos/audio/player/stop:
+ publish:
+ summary: Stop media
+ description: ''
+ tags:
+ - name: Audio
+ description: All audio related topics.
+ message:
+ $ref: '#/components/messages/emptyMessage'
+components:
+ messages:
+ emptyMessage:
+ payload:
+ type: object
+ name: EmptyMessage
+ summary: Empty message

example/base.yml

@@ -0,0 +1,31 @@
+asyncapi: 2.0.0
+id: 'urn:zbos-mqtt-api'
+defaultContentType: 'application/json'
+info:
+ title: ZBOS MQTT API
+ version: 2.6.3
+ description: API for communication with ZBOS by Zora Robotics.
+ contact:
+ email: [email protected]
+servers:
+ local:
+ url: '127.0.0.1'
+ protocol: mqtt
+ description: This is the local robot broker.
+ variables:
+ port:
+ enum:
+ - '1883'
+ - '9001'
+ default: '1883'
+ cloud:
+ url: zbos-mqtt.zoracloud.com
+ protocol: mqtt
+ description: This is the cloud broker.
+ variables:
+ port:
+ enum:
+ - '1883'
+ - '1884'
+ - '9001'
+ - '9002'

example/bundle.ts

@@ -2,7 +2,7 @@ import { readFileSync, writeFileSync } from 'fs';
 import bundle from '@asyncapi/bundler';
 
 async function main() {
- const document = bundle([readFileSync('./main.yaml', 'utf-8')], {
+ const document = await bundle([readFileSync('./main.yaml', 'utf-8')], {
  referenceIntoComponents: true,
  });
  writeFileSync('asyncapi.yaml', document.yml());

example/camera.yml

@@ -0,0 +1,44 @@
+asyncapi: 2.0.0
+id: 'urn:zbos-mqtt-api'
+defaultContentType: application/json
+info:
+ title: Camera
+ version: 2.6.3
+ description: API for communication with ZBOS by Zora Robotics.
+ contact:
+ email: [email protected]
+channels:
+ zbos/camera/picture/event:
+ subscribe:
+ summary: 'event: Get picture'
+ description: ''
+ tags:
+ - name: Camera
+ description: All camera related topics.
+ message:
+ payload:
+ type: string
+ name: String
+ zbos/camera/picture/get:
+ publish:
+ summary: Get picture
+ description: ''
+ tags:
+ - name: Camera
+ description: All camera related topics.
+ message:
+ $ref: '#/components/messages/keyMessage'
+components:
+ messages:
+ keyMessage:
+ payload:
+ type: object
+ properties:
+ key:
+ type: string
+ description: Required random key
+ name: KeyResult
+ summary: Random key
+ examples:
+ - payload:
+ key: ABCxyz

example/main.yaml

@@ -1,10 +1,10 @@
-asyncapi: '2.2.0'
+asyncapi: 2.5.0
 info:
  title: Account Service
  version: 1.0.0
  description: This service is in charge of processing user signups
 channels:
- user/signup:
+ user/signedup:
  subscribe:
  message:
  $ref: './messages.yaml#/messages/UserSignedUp'