refactor: interface and implementations for each major spec version

[smoya]

Description

The new Intent-driven API is made for keeping retro compatibility and also avoiding breaking changes as much as we can.
This means we should use the same API interface, but keep implementation logic that can differ between different AsyncAPI Spec versions.

This POC is just one suggestion on how we can handle that in the most simple way, avoiding error-prone solutions, overengineered and/or unmaintainable code.

My suggestion is about creating interfaces (actually TypeScript Interfaces) for all the models required for implementing the Intent-Driven API (See https://github.com/asyncapi/parser-api/blob/master/docs/v1.md).
Then, implementation classes per each major AsyncAPI Version, e.g. v2, v3, etc.

The code changed on this PR tries to illustrate that, having the interfaces located at src/models and all implementations under a directory, e.g. src/models/v2 and src/models/v3, meaning v2.x and v3.x spec major versions respectively.

For using one model or the other, we would just need to implement a factory pattern in a function that, based on the version of the provided AsyncAPI document when calling the parse method, will instantiate one or another model. That's all since the interface will be always the same, the only thing that changes is the implementation.

PROS

• The code is cleaner, all details of implementation are inside each major implementation, no need to do any arcane magic checking versions.
• Less error-prone, all implementations can be tested with a very robust test suite.
• Code is isolated, a bug in one major version implementation won't affect others.
• Scalable, just copy-paste one version and change all you need.

CONS

• Code is duplicated, meaning that the codebase will increase (on each AsyncAPI spec major version).

I would like to know WDYT about it. cc @magicmatatjahu @Souvikns @jonaslagoni

Related issue(s)

• Implement Parser-API (Intent-Driven) #401
• Migrate project to TypeScript #482

[magicmatatjahu]

I see places to improve :)

[magicmatatjahu]

contact() should return ContactInterface not V2Contact etc

[smoya]

It seems it is not necessary to do that since the returned type already implements the interface.
I'm coming from Go land, where it is standard to return the implementation types rather than the interface ones (even though from my point of view, I could find pros and cons in all ways).
I couldn't find examples of this in TS besides a few. I'm happy to change it if you consider it should be done.

[Souvikns]

What I understand for spec version v3 parser will use V3AsyncAPIDocument, but with a newer spec release if we update the models(the interface) then the older parser will also have to implement that change, and if it does will the old parser face any issue.

[magicmatatjahu]

I'm not a fan of calling things v2 v3 etc. of course we can and should have aliases, but the classes themselves can be called License, Contact etc without those prefixes. If we import or export them then we should use prefixes (but i prefer suffixes), but for models of the same version we should use normal names. Example implementation:

// mdoels/v2/contact.ts
export class Contact extends BaseModel implements ContactInterface {
  ...
} 

export { Contact as ContactV2 }

// models/v2/index.ts
export { ContactV2 } from './contact';

// models/index.ts
export * from './v2';

and of course please write single factory to show how we should handle different classes across versions. I more or less know, but this will help other people :)

That's all I have so far and I don't see any other problems. I like the idea and if something will be wrong, we will change it in the code :)

[smoya]

and of course please write single factory to show how we should handle different classes across versions. I more or less know, but this will help other people :)

This is a thing now

[smoya]

What I understand for spec version v3 parser will use V3AsyncAPIDocument, but with a newer spec release if we update the models(the interface) then the older parser will also have to implement that change, and if it does will the old parser face any issue.

The Interface will not change as far as https://github.com/asyncapi/parser-api/blob/master/docs/v1.md doesn't change.
Of course it will evolve in the future and we will need to update the interface and implementations. At some point, we will drop support for old versions as we are currently doing (e.g. we do not support v1 spec 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'm not a fan of calling things v2 v3 etc. of course we can and should have aliases, but the classes themselves can be called License, Contact etc without those prefixes.

I finally implemented this change as it also will help reusing code later on.

[magicmatatjahu]

Awesome! I don't see any problems, now 😆 Of course the errors themselves (their description) need to be improved, but it's not the most important thing right now :)

🚀

[smoya]

/rtm