feat!: enable usage of generated app as a library without its code modification

[kaushik-rishi]

Related issue(s)
#219

[github-actions]

Welcome to AsyncAPI. Thanks a lot for creating your first pull request. Please check out our contributors guide useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.

[derberg]

you should also modify template/src/api/index.js file and at the end of the file add exports.app = app;

additionally please extend the readme, by adding a new section, with h3 under the CLI section called Adding custom code and:

• write explanation that it is recommended to not modify the code of generated application but rather use it as an API to start a server and register additional custom code
• provide this example code

// You require the generated server. Running this code starts the server
// App exposes API to send messages
const { app } = require('./output/src/api/index');
// Requiring generated handler that you should use if you want to react on consumed messages
const receiveLightMeasurementHandler = require('./output/src/api/handlers/smartylighting-streetlights-1-0-event-{streetlightId}-lighting-measured');
// Requiring generated handler that you should use if you want to react on produced messages
const sendDimLightHandler = require('./output/src/api/handlers/smartylighting-streetlights-1-0-action-{streetlightId}-dim');

/**
 *
 * 
 * Example of how to work with generated code as a consumer
 *
 * 
*/

// Writing your custom logic that should be triggered when your app receives as message from a given channel
function triggeredByLightMeasurementHandler(message) {
  console.log('reading message in triggeredByLightMeasurementHandler', message.payload);

  console.log('sending another message in triggeredByLightMeasurementHandler to another channel');
  app.send({percentage: 1}, {}, 'smartylighting/streetlights/1/0/action/1/dim');   
}

// Registering your custom logic in a channel-specific handler
// triggeredByLightMeasurementHandler function is called once the app gets message sent to the channel like:
// "mqtt pub -t 'smartylighting/streetlights/1/0/event/123/lighting/measured' -h 'test.mosquitto.org' -m '{"id": 1, "lumens": 3, "sentAt": "2017-06-07T12:34:32.000Z"}'"
receiveLightMeasurementHandler.registerMiddleware(triggeredByLightMeasurementHandler);

/**
 * 
 * 
 * Example of how to process a message before it is sent to the broker
 * 
 * 
 */

// Writing your custom logic that should be triggered when your app receives as message from a given channel
function triggeredByDimLight(message) {
  console.log('reading message in triggeredByDimLight before it is sent to the broker', message.payload.percentage);
}

// Registering your custom logic in a channel-specific handler
// triggeredByDimLight function is called once the app sends a message to the channel
// For example "triggeredByLightMeasurementHandler" sends a message to some channel using "app.send" and before it is sent, you want to perform some other actions
sendDimLightHandler.registerMiddleware(triggeredByDimLight);

/**
 * 
 * 
 * Example of how to produce a message using API of generated app independently from the handlers
 * 
 * 
*/

(function myLoop (i) {
  setTimeout(() => {
    console.log('producing custom message');
    app.send({percentage: 1}, {}, 'smartylighting/streetlights/1/0/action/1/turn/on');   
    if (--i) myLoop(i);
  }, 1000);
}(3));

• explain that anyone can run this code and test by sending a custom message mqtt pub -t 'smartylighting/streetlights/1/0/event/123/lighting/measured' -h 'test.mosquitto.org' -m '{"id": 1, "lumens": 3, "sentAt": "2017-06-07T12:34:32.000Z"}'

---

last but not least change the PR title to feat!: as this is going to be a breaking change and we need to release it as new major

also call it like feat!: make it possible to use generated app without its code modification -> title should say not want you did but what it changed

you could also extend the description of the PR with the example code sample to showcase what is the change

[kaushik-rishi]

@derberg can you please review 🙂 ?

[kaushik-rishi]

@derberg
The end goal is to use it as a library like require("nodejs-my-template").
In such a case, it doesn't make any sense to import the handlers from their respective files like require('./output/src/api/handlers/smartylighting-streetlights-1-0-action-{streetlightId}-dim');

🤔 Thinking from a user point of view, I'd rather be happy if I can access all the handlers by just importing the library, The ideal end usage should look something like this

const { client } = require("./server-library")

client.init();
client.subscribeToSmartylightingStreetlights10EventLightingMeasuredHandler.registerMiddleware((messagge) => {
    console.log("hit the subscribe payload", messagge.payload);
})

the code should ideally look more shorter, if not for the long name smartylighting...blablabla 😄

[derberg]

the code should ideally look more shorter, if not for the long name smartylighting

yeah, in both cases, path or function name, the name is crap 😄 but afaik it is because we do not have explicitly a channel name added to https://bit.ly/asyncapi

Thinking from a user point of view, I'd rather be happy if I can access all the handlers by just importing the library, The ideal end usage should look something like this

yes, eventually this is what we should target:

• see how to make it easy to just require as library
• generate client too, so we do not have to do app.send({percentage: 1}, {}, 'smartylighting/streetlights/1/0/action/1/dim'); but client.sendDimLight({percentage: 1}) or similar

---

thing is that these improvements ideas popped up only because we started this refactoring to enable easier testing. So I suggest you just create an issue so we do not forget:

1. get followup and name it as ideas for next major
2. merge this PR as v1
3. introduce tests
4. rewrite to react
5. rewrite to use new Parser API
6. rewrite to use AsyncAPI v3
7. look into point 1

[derberg]

Lemme know if you agree with suggested plan, and I merge

[kaushik-rishi]

Sure, will create the issue.
There's an edge case i just found out, for which this refactor doesn't hold good.

If there's a route which has both the publish and subscribe operations on a single channel/route, the middlewares and registerMiddleware functions will be the same for both the publish and subscribe methods.

Example AsyncAPI File -> https://github.com/kaushik-rishi/templates-collection-nodejs-templates/blob/master/mqtt-pub-sub-single-route-new-template/asyncapi.yaml

Example generated code -> https://github.com/kaushik-rishi/templates-collection-nodejs-templates/blob/master/mqtt-pub-sub-single-route-new-template/src/api/handlers/smartylighting-streetlights-1-0-action-%7BstreetlightId%7D-turn-on.js

[derberg]

you also have to update snapshots for tests: npm run test:updateSnapshot

and yeah, good catch about pub/sub
just make sure const middlewares = []; is unique per operation, simply make sure there are 2 separate arrays

[kaushik-rishi]

Sure :), the arrays and the functions should be different as well.
About the tests, I will update them 👍

[kaushik-rishi]

I’ve updated the docs with the new way to use the library/template. Currently i feel using operationId for the function names is fine, in the path forward i’d like to move the operationId into using the channel’s name in pascal / camel case or whatever, but i’d like to do it after we start rewriting the templates to new react renderer template.
Also updated snapshot tests

Path forward

• get the first regression test up and running integrated with github actions
• start rewrite to reactjs

@derberg

[kaushik-rishi]

@derberg ready to merge 🙂

[derberg]

well done 👏🏼

[derberg]

@kaushik-rishi linter ain't happy https://github.com/asyncapi/nodejs-template/actions/runs/6371925771/job/17311872498?pr=220

[sonarcloud]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
No Duplication information

[kaushik-rishi]

@derberg oops! fixed it.

[derberg]

WELL DONE 👏🏼

[derberg]

/rtm

[asyncapi-bot]

🎉 This PR is included in version 1.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[derberg]

@allcontributors please add @kaushik-rishi for code,docs,test

[allcontributors]

@derberg

I've put up a pull request to add @kaushik-rishi! 🎉