feat: get bundler ready to release (#17)

* chore: get bundler ready to release * doc: bundler example * doc: add example use case for bundler * doc: add API doc and use case example * chore: add jsdoc api documentation. Co-authored-by: Lukasz Gornicki <[email protected]>
asyncapi · Feb 7, 2022 · 1ee2313 · 1ee2313
1 parent 2a0197a
commit 1ee2313
Show file tree

Hide file tree

Showing 7 changed files with 1,254 additions and 22 deletions.
diff --git a/API.md b/API.md
@@ -0,0 +1,67 @@
+## Classes
+
+<dl>
+<dt><a href="#Document">Document</a></dt>
+<dd></dd>
+</dl>
+
+## Functions
+
+<dl>
+<dt><a href="#bundle">bundle(files, options)</a> ⇒ <code><a href="#Document">Document</a></code></dt>
+<dd></dd>
+</dl>
+
+<a name="Document"></a>
+
+## Document
+**Kind**: global class  
+
+* [Document](#Document)
+    * [new Document(parsedJSONList, [base])](#new_Document_new)
+    * [.json()](#Document+json) ⇒ <code>Object</code>
+    * [.yml()](#Document+yml) ⇒ <code>string</code>
+    * [.string()](#Document+string) ⇒ <code>string</code>
+
+<a name="new_Document_new"></a>
+
+### new Document(parsedJSONList, [base])
+
+| Param | Type |
+| --- | --- |
+| parsedJSONList | <code>Array.&lt;Object&gt;</code> | 
+| [base] | <code>Object</code> | 
+
+**Example**  
+```js
+const document = new Document(parsedJSONList, base);console.log(document.json()); // get json objectconsole.log(document.yml()); // get yaml stringconsole.log(document.string()); // get json string
+```
+<a name="Document+json"></a>
+
+### document.json() ⇒ <code>Object</code>
+**Kind**: instance method of [<code>Document</code>](#Document)  
+<a name="Document+yml"></a>
+
+### document.yml() ⇒ <code>string</code>
+**Kind**: instance method of [<code>Document</code>](#Document)  
+<a name="Document+string"></a>
+
+### document.string() ⇒ <code>string</code>
+**Kind**: instance method of [<code>Document</code>](#Document)  
+<a name="bundle"></a>
+
+## bundle(files, options) ⇒ [<code>Document</code>](#Document)
+**Kind**: global function  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| files | <code>Array.&lt;string&gt;</code> \| <code>Array.&lt;Object&gt;</code> | files that are to be bundled |
+| options | <code>Object</code> |  |
+| options.base | <code>string</code> \| <code>object</code> | base object whose prperties will be retained. |
+| options.parser | <code>Object</code> | asyncapi parser object |
+| options.validate | <code>boolean</code> | pass false to not validate file before merge |
+
+**Example**  
+```js
+const bundler = requrie('@asyncapi/bundler');const fs = require('fs');const path = requrie('path');const document = await bundler.bundle(fs.readFileSync(  path.resolve('./asyncapi.yaml', 'utf-8')));console.log(document.yml());
+```

diff --git a/README.md b/README.md
@@ -8,21 +8,178 @@
   <em>Bundle multiple Specificatin files into one</em>
 </p>
 
+<p align="center">
+<a href="https://github.com/asyncapi/bundler/blob/main/LICENSE"><img alt="GitHub license" src="https://img.shields.io/github/license/asyncapi/bundler"></a>
+<a href="https://github.com/asyncapi/bundler/actions/workflows/if-nodejs-pr-testing.yml">
+<img src="https://github.com/asyncapi/bundler/actions/workflows/if-nodejs-pr-testing.yml/badge.svg" alt="PR testing - if Node project"  />
+</a>
+<a href="https://www.npmjs.com/package/@asyncapi/bundler">
+<img alt="npm" src="https://img.shields.io/npm/dw/@asyncapi/bundler">
+</a>
+
+</p>
+
+<br>
+
+<!-- toc is generated with GitHub Actions do not remove toc markers  -->
+
+<!-- toc -->
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [Usage](#usage)
+- [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 - 
+
+<details>
+<summary>your specification file is divided into different smaller files and is using json `$ref` to reference components </summary>
+
+```yaml
+
+# asyncapi.yaml
+asyncapi: '2.2.0'
+info:
+  title: Account Service
+  version: 1.0.0
+  description: This service is in charge of processing user signups
+channels:
+  user/signup:
+    subscribe:
+      message:
+        $ref: './messages.yaml#/messages/UserSignedUp'
+
+#messages.yaml
+messages:
+  UserSignedUp:
+    payload:
+      type: object
+      properties:
+        displayName:
+          type: string
+          description: Name of the user
+        email:
+          type: string
+          format: email
+          description: Email of the user
+
+# After combining 
+asyncapi: 2.2.0
+info:
+  title: Account Service
+  version: 1.0.0
+  description: This service is in charge of processing user signups
+channels:
+  user/signedup:
+    subscribe:
+      message:
+        payload:
+          type: object
+          properties:
+            displayName:
+              type: string
+              description: Name of the user
+            email:
+              type: string
+              format: email
+              description: Email of the user
+
+```
 
+</details>
 
-## What does Bundler do?
-Combine multiple AsyncAPI spec files into one complete spec file or resolve external `$ref`'s in one file. 
+<details>
+<summary>you have different standalone specification files that define a larger system, see examples here </summary>
 
-As of now you can use AsyncAPI Bundler for two specific use cases - 
-- Merge different AsyncAPI specifications into one. 
-- Resolve all references from an single AsyncAPI document into a single file. 
+```yaml
+
+# signup.yaml 
+asyncapi: '2.2.0'
+info:
+  title: Account Service
+  version: 1.0.0
+  description: This service is in charge of processing user Signup 
+
+channels:
+  user/signedup:
+    subscribe:
+      message:
+        payload:
+          type: object
+          properties:
+            displayName:
+              type: string
+            email:
+              type: string
+              format: email
+
+
+# login.yaml
+asyncapi: '2.2.0'
+info:
+  title: Account Service
+  version: 1.0.0
+  description: This service is in charge of processing user signup
+
+channels:
+  user/loggenin:
+    subscribe:
+      message:
+        payload:
+          type: object
+          properties:
+            displayName:
+              type: string
+
+# After combining 
+# asyncapi.yaml 
+asyncapi: '2.2.0'
+info:
+  title: Account Service
+  version: 1.0.0
+  description: This service is in charge for processing user authentication 
+
+channles:
+  user/signedup:
+    subscribe:
+      message:
+        payload:
+          type: object
+          properties:
+            displayName:
+              type: string
+            email:
+              type: string
+              format: email
+  user/loggedin:
+    subscribe:
+      message:
+        payload:
+          type: object
+          properties:
+            displayName:
+              type: string
+```
+
+</details>
+
+<br>
+
+## Installation 
+
+```
+npm install @asyncapi/bundler
+```
 
 ## Usage 
 
 AsyncAPI-bundler could be easily used within your javascript projects as a Nodejs module. 
 
 ```js
-const bundler = require('asyncapi-bundler');
+const bundler = require('@asyncapi/bundler');
 const fs = require('fs');
 const path = require('path');
 
@@ -49,4 +206,3 @@ console.log(document.json()); // the complete bundled asyncapi document.
 | options.base | <code>string</code> \| <code>object</code> | base object whose prperties will be retained. |
 | options.parser | <code>Object</code> | asyncapi parser object |
 | options.validate | <code>boolean</code> | pass false to not validate file before merge |
-
diff --git a/lib/document.js b/lib/document.js
@@ -1,7 +1,24 @@
 const _ = require("lodash");
 const yaml = require("js-yaml");
 
+/**
+ * @class
+ * 
+ * @example
+ * 
+ * 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
+ */
+
 class Document {
+  /**
+   * 
+   * @param {Object[]} parsedJSONList 
+   * @param {Object} [base] 
+   */
   constructor(parsedJSONList, base) {
     this._doc = {};
     for (const { parsedJSON } of parsedJSONList) {
@@ -13,14 +30,23 @@ class Document {
     }
   }
 
+  /**
+   * @return {Object}
+   */
   json() {
     return this._doc;
   }
 
+  /**
+   * @return {string}
+   */
   yml() {
     return yaml.dump(this._doc);
   }
 
+  /**
+   * @return {string}
+   */
   string(){
     return JSON.stringify(this._doc);
   }

diff --git a/lib/index.js b/lib/index.js
@@ -8,6 +8,20 @@ const Document = require("./document");
  * @param {string | object} options.base base object whose prperties will be retained.
  * @param {Object} options.parser asyncapi parser object
  * @param {boolean} options.validate pass false to not validate file before merge
+ * 
+ * @return {Document}
+ * 
+ * @example
+ * 
+ * const bundler = requrie('@asyncapi/bundler');
+ * const fs = require('fs');
+ * const path = requrie('path');
+ * 
+ * const document = await bundler.bundle(fs.readFileSync(
+ *   path.resolve('./asyncapi.yaml', 'utf-8')
+ * ));
+ * 
+ * console.log(document.yml());
  */
 const bundle = async (files, options = {}) => {
   if (typeof options.base !== "undefined") {
@@ -31,6 +45,4 @@ const bundle = async (files, options = {}) => {
   return new Document(parsedJsons, options.base);
 };
 
-module.exports = {
-  bundle,
-};
+module.exports = bundle;