docs: add better examples and documentation (#391)

Co-authored-by: Alejandra Quetzalli  <[email protected]>

.github/workflows/pull-request-integration-testing.yml → .github/workflows/pull-request-example-testing.yml

@@ -22,14 +22,12 @@ jobs:
         run: cd examples && docker-compose up -d
       - name: Check running containers
         run: docker ps -a
-      - name: Build pubsub example and test clients can talk to each other
-        run: |
-          npm run generate:examples:pubSub
-          npm run test:examples:integration:pubSub
-      - name: Build request/reply example and test clients can talk to each other
-        run: |
-          npm run generate:examples:requestReply
-          npm run test:examples:integration:requestReply
+      - if: steps.packagejson.outputs.exists == 'true'
+        name: Generate new examples
+        run: npm run generate:examples
+      - if: steps.packagejson.outputs.exists == 'true'
+        name: Test examples
+        run: npm run test:examples
       - name: Dump docker logs on failure
         if: failure()
         uses: jwalton/gh-docker-logs@v1

.gitignore

@@ -1,4 +1,5 @@
 node_modules
 dist
 .DS_Store
-__transpiled
+__transpiled
+lib

README.md

@@ -8,58 +8,20 @@
   <em>This is a TypeScript/Node.js NATS template for the AsyncAPI generator.</em>
 </p>
 
-This template is for generating a TypeScript/Node.js wrapper for the NATS client based on your AsyncAPI document. The template is based on the [nats-ts](https://github.com/nats-io/nats.ts) library and can be used as both a TypeScript and Node.js library. 
+This template is for generating a TypeScript/Node.js wrapper for the NATS client based on your AsyncAPI document. The template is based on the [nats.js](https://github.com/nats-io/nats.js) library and can be used as both a TypeScript and Node.js library. 
 
-Have you found a bug or have an idea for improvement? Feel free to contribute! See [the contribution guidelines](#Contributing) how to do so.
+Have you found a bug or have an idea for improvement? Feel free to contribute! See [the contribution guidelines](#Contributing) for how to do so.
 
 # How to use
-Example generations can be found under [examples](./examples) which includes [publish and subscribe](./examples/publish%20subscribe) example as well as [request and reply](./examples/request%20reply).
+Example use-cases can be found under [examples](./examples).
 
 Information about the generated files and a description can be found under [the documentation folder](./docs/general.md).
+
 ## Requirements
 * @asyncapi/generator < v2.0.0 >v1.1.1
 
 Install the generator through [npm or run it from docker official installer](https://github.com/asyncapi/generator#install).
 
-## Example usage
-The leading examples are both in TypeScript and in Node.js since this template can be used for both. The example code will be used later in the documentation to explain the different features.
-
-Given any AsyncAPI file (`AsyncAPI.yml`) first generate the client with the [AsyncAPI generator](https://github.com/asyncapi/generator) such as 
-```bash
-ag --install --output ./nats-client ./AsyncAPI.yml @asyncapi/ts-nats-template --param "generateTestClient=true"  --param "promisifyReplyCallback=true"
-```
-
-Afterward, go into the generated folder `nats-client` and run the commands `npm i` and `npm run build`. The generated NATS client is now ready to be used in either TypeScript or Node.js.
-
-### TypeScript 
-
-```js
-import * as GeneratedClient from "./nats-client";
-const natsClient = new GeneratedClient.NatsAsyncApiClient();
-async function connect(){
-  try{
-    await natsClient.connect({url: "nats://demo.nats.io:4222", reconnectTimeWait: 1000, reconnect: true, maxReconnectAttempts: -1});
-  }catch(e){
-    console.log(e);
-  }
-}
-connect();
-```
-
-### Node.js
-```js
-const GeneratedClient = require("./nats-client");
-const natsClient = new GeneratedClient.NatsAsyncApiClient();
-async function connect(){
-  try{
-    await natsClient.connect({url: "nats://demo.nats.io:4222", reconnectTimeWait: 1000, reconnect: true, maxReconnectAttempts: -1});
-  }catch(e){
-    console.log(e);
-  }
-}
-connect();
-```
-
 ## Template Parameters
 These are the available template parameters:
 |Parameter|Type|Description|
@@ -78,7 +40,7 @@ These are the available template parameters:
 
 # Contributing
 
-Before contributing please read the [CONTRIBUTING](CONTRIBUTING.md) document.
+Before contributing, please read the [CONTRIBUTING](CONTRIBUTING.md) document.
 
 # Contributors ✨
 
@@ -101,16 +63,4 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
 <!-- markdownlint-restore -->
 <!-- prettier-ignore-end -->
 
-<!-- ALL-CONTRIBUTORS-LIST:END -->
-## Contributors ✨
-
-Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
-
-<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
-<!-- prettier-ignore-start -->
-<!-- markdownlint-disable -->
-<!-- markdownlint-restore -->
-<!-- prettier-ignore-end -->
-<!-- ALL-CONTRIBUTORS-LIST:END -->
-
-This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
+<!-- ALL-CONTRIBUTORS-LIST:END -->

components/test/publishSubscribe.js

@@ -69,15 +69,15 @@ const subscription = await ${subscribeClient}.subscribeTo${pascalCase(channelNam
 const tryAndWaitForResponse = new Promise((resolve, reject) => {
     let isReturned = false;
     setTimeout(() => {
-        if(!isReturned){
-            reject(new Error("Timeout"));
-        }
+      if(!isReturned){
+        reject(new Error("Timeout"));
+      }
     }, 3000)
     setInterval(async () => {
-        if(subscription.getReceived() === 1){
-            resolve(undefined);
-            isReturned = true
-        }
+      if(subscription.getReceived() === 1){
+        resolve(undefined);
+        isReturned = true
+      }
     }, 100);
 });
 await ${publishClient}.publishTo${pascalCase(channelName)}(publishMessage ${functionParameters});

components/test/requestReply.js

@@ -64,16 +64,16 @@ var replyMessage: ${replierClientMessageType} = ${replierClientMessageType}.unma
 var receiveMessage: ${requesterClientMessageType} = ${requesterClientMessageType}.unmarshal(${receiveMessageExample});
 ${exampleParameters}
 const replySubscription = await ${replierClient}.replyTo${pascalCase(channelName)}((err, msg 
-      ${replyCallbackParameters}) => {
-    return new Promise((resolve, reject) => {
-        receivedError = err;
-        receivedMsg = msg;
-        ${setReceivedVariable}
-        resolve(replyMessage);
-    })},
-    (err) => {console.log(err)}
-    ${functionParameters},
-    true
+  ${replyCallbackParameters}) => {
+  return new Promise((resolve, reject) => {
+    receivedError = err;
+    receivedMsg = msg;
+    ${setReceivedVariable}
+    resolve(replyMessage);
+  })},
+  (err) => {console.log(err)}
+  ${functionParameters},
+  true
 );
 var reply = await ${requesterClient}.request${pascalCase(channelName)}(receiveMessage ${functionParameters});
 expect(reply).to.be.deep.equal(replyMessage)

examples/README.md

@@ -0,0 +1,9 @@
+# Examples
+
+This directory contains a series of self-contained examples that you can use as starting points or snippets, to pull into your existing applications. All examples expect a NATS broker to connect to.
+
+The examples are as follows:
+
+- [simple-reply](./simple-reply) - A basic example of how to set up a reply in AsyncAPI and use the generated code.
+- [simple-request](./simple-request) - A basic example of how to send a request in AsyncAPI and use the generated code.
+