feat: initial intent API implementation

[jonaslagoni]

This is the first part of the intent API implementation.

I have only implemented the root IntentAsyncAPIDocument as I thought this was a great time to allow other contributors to help out if they want to, by creating first good issues. Even though we might need to place a time constraint on when they need to be done (in order to have enough time to evaluate the intents before releasing).

Questions and Decisions

1. How should we interact with the raw AsyncAPI document?
   • Currently, I have decided to stay with our current model and reuse that. This also means that users can have access to them if that is what they desire. Instead of just raw JSON. This can be done through intent.rawDocument().
2. How should we define operation types?
   • Currently, I have decided to use the following OperationTypes, that forced me to change the Operation.type() -> Operation.types()
3. How much of the old intents and model utils should we keep (anonymousNaming, iterators, customValidators)?
   • Currently, I have kept everything as is and just moved them around. See below.

What changed

• New intent models were created under ./lib/models
• Moved all version 2 relevant code into ./lib/version2 this includes:
  • The version 2 models were moved from ./lib/models to ./lib/version2/models, the same goes for their related tests.
  • Version 2 specific validation rules was moved from ./lib/customValidators.js to ./lib/version2/customValidators.js, same goes for their related tests. Also in terms of when to check for them -> https://github.com/jonaslagoni/parser-js/blob/660b9643b652b94b1961b8e67e4a9b1f64a405d5/lib/parser.js#L217
  • Version 2 specific anonymous naming was moved from ./lib/anonymousNaming.js to ./lib/version2/anonymousNaming.js.
  • Version 2 specific iterators was moved from ./lib/iterators.js to ./lib/version2/iterators.js.
• Adapted parser implementation and tests to use the new intent API

Todo:

• Change merge into branch to ???
• Make tests for IntentAsyncAPIDocument

Todo once merged:

• Figure out what to do with message conversion for custom schema formats
  • Figure out how to handle schemas, especially with @magicmatatjahu potential any schema suggestion in the spec.
• Based on the discussion 2, change the Operation.type() -> Operation.types() in parser-api repo.
• Create good first issues for the rest of the implementation to do as much parallel development as possible.
• Port the implementation to TS
• Create pre-release generator to start utilizing it right away

Related issue(s)

Fixes #401

[smoya]

I added a new commit with the implementation for the suggestions @fmvilas made here.
I ended up creating an intermediate object for channels, operations, and messages.

cc @jonaslagoni

[smoya]

I think we would also need to introduce methods for getting objects by their ID, like document.channel(<channel_id>), document.operation(<operation_id>), document.server(<server_name>).

Edit: this is covered by document.channels().filterById(), document.operation().filterById(), document.messages().filterById(), document.servers().filterById()

[smoya]

• Added IntentServers object with same style as IntentChannels, IntentOperations, and ` IntentMessages).
• Added a id() method on the following models:
  • Channel -> returns key on the map for 2.x.x
  • Operation -> returns operation id for 2.x.x
  • Message -> returns uid for 2.x.x
  • Server -> returns key on the map for 2.x.x
• Removed document.channel(<channel_name>) method in favor of document.channels().filterById(<name>).

[smoya]

I'm thinking about introducing an isEmpty() method to all those intermediate objects, so we can remove the document.hasChannels-like methods.
The point is that isEmpty is the opposite of what we previously had (emptiness vs fullness) so not sure what others think about.

[fmvilas]

I'm thinking about introducing an isEmpty() method to all those intermediate objects, so we can remove the document.hasChannels-like methods. The point is that isEmpty is the opposite of what we previously had (emptiness vs fullness) so not sure what others think about.

I think it's a good idea 👍

Operation -> returns operation id for 2.x.x

An operation might not contain an operationId, so it's possible we get undefined. However, in v3, the "operationId" is mandatory (it's implicit), so I wonder if we shouldn't be generating operation ids for those operations that don't have one defined. This way we can make sure we never return undefined in any version.

[sonarqubecloud]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
No Duplication information

[smoya]

I wonder if we shouldn't be generating operation ids for those operations that don't have one defined. This way we can make sure we never return undefined in any version.

Yeah, I think it makes sense. Would you also suggest we write it as a rule for all parser implementations (Parser-API) ? So the return type should be only string and never empty then.

[fmvilas]

Would you also suggest we write it as a rule for all parser implementations (Parser-API) ?

I think so. Not sure how far we should get into implementation details other than the API surface but definitely something to take into account. In any case, if we say that operations MUST always have an ID, implementations will have to generate them 😄

[smoya]

@jonaslagoni would you mind converting this issue into a draft? As this is just a POC, I don't think it makes sense to keep it as a regular PR.

[github-actions]

This pull request has been automatically marked as stale because it has not had recent activity 😴

It will be closed in 120 days if no further activity occurs. To unstale this pull request, add a comment with detailed explanation.

There can be many reasons why some specific pull request has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this pull request forward. Connect with us through one of many communication channels we established here.

Thank you for your patience ❤️

[smoya]

@jonaslagoni We can close this one as all this work is being done on the next-major branch.