adds support for type discriminator during deserialization

[baywet]

Summary

fixes #648

What I thought would be a rather short PR ended up being much larger than anticipated. The background story is that because of the type system in Go, I add to introduce interfaces generation support in Kiota CodeDOM. Which led to a whole bunch of refactoring so we don't have to duplicate things like import statements, refiners logic, writing methods prototypes etc...
Because of the TypeScript limitations on static methods, I also had to introduce global functions and do a bunch of refactoring.
This PR is adding new capabilities to the Kiota engine, which is overall a good thing for Kiota to support additional scenarios and languages. Apologies to the reviewers, this is going to be large.

To illustrate what this does, let's take the example of /groups/id/members which returns a collection of directory objects. User, Service Principal, Group and many other types derive from directory object. Before this change, everything was deserialized to a directory object, and the additional properties available on derived types (like userPrincipalName for user) would end up in the additional data manager.
After that change, and once the conversion lib releases, the SDK will use the newly introduced factories for each model types to read in the odata.type (contains values like #microsoft.graph.user) property and instantiate the derived type when possible. Making pattern matching possible in the client code and access to derived types properties easier.

Generation diff

microsoft/kiota-samples#513

using this description (see outlook item)
microsoftgraph/msgraph-sdk-powershell#1060

Global todo

• move the discriminator mappings property from code class to code method
• introduce a new factory method type
• add a common refiner to add usings for discriminator mappings
• add a common refiner to add usings for factory methods in request executors
• check that code block end is not adding unecessary closings for php/ruby/java/ts/csharp/python
• unit tests for interface cloning refiners
• update conceptual documentation
• ping php and python teams to reflect the updates
• update the ruby checklist to reflect the updates
• changelog entry

CSharp todo

• update parse node interface to take the new factories as parameters
• update deserializer method gen to pass the factory for the properties
• remove the new constraint on generic types for request adapter
• add factory to request adapter as parameter
• update request executor to pass the factory + update unit tests
• bump abstractions, http and serialization packages
• implement factory method generation + unit tests
• remove the get object value that relies on new generic type constraint in parse node
• rename the get error value method into get object value
• use refiner method to add reference to types in discriminator mapping
• implement using the factory + discriminator property name in getObjectValue

Go todo

• update parse node interface to take the new factories as parameters
• update deserializer method gen to pass the factory for the properties
• add factory to request adapter as parameter
• update request executor to pass the factory + update unit tests
• bump abstractions, http and serialization packages
• implement factory method generation + unit tests
• use refiner method to add reference to types in discriminator mapping
• implement using the factory + discriminator property name in getObjectValue

Java todo

• update parse node interface to take the new factories as parameters
• update deserializer method gen to pass the factory for the properties
• add factory to request adapter as parameter
• update request executor to pass the factory + update unit tests
• bump abstractions, http and serialization packages
• implement factory method generation + unit tests
• use refiner method to add reference to types in discriminator mapping
• implement using the factory + discriminator property name in getObjectValue

TypeScript todo

• update parse node interface to take the new factories as parameters
• update deserializer method gen to pass the factory for the properties
• add factory to request adapter as parameter
• update request executor to pass the factory + update unit tests
• bump abstractions, http and serialization packages
• implement factory method generation (read the discriminator value from parse node, switch case) + unit tests
• use refiner method to add reference to types in discriminator mapping
• implement using the factory + discriminator property name in getObjectValue

[nikithauc]

running into an issue with Go where the type system for structs doesn't allow for up casting of structs (because it's composition over inheritance). Here is the roadmap to solve it:

1. interfaces for all the models with inheritance structure
2. all the models implement their respective interfaces
3. properties of objects/collection of objects are interfaces
4. the deserializer infers to parent interface
5. the client does a type inferance
6. put the interfaces in their dedicated package structures

Can you elaborate on put the interfaces in their dedicated package structures ? How would that look ? Would this be some pattern that we apply for typescript when we use model interfaces?

[baywet]

@nikithauc I'm still working with @darrelmiller to understand how much this is a requirement. But the gist of it is that interfaces for models would be in a sub namespace like so

• mainnamespace -> contains the api client and the request builders
• mainnamespace.models -> contains the model classes
• mainnamespace.interfaces -> contains the model interfaces

Of course the infrastructure I'm laying out would leave that as a choice for each language (whether or not we have interfaces in this language and where they are placed).
Hopefully this clarifies the ongoing work here.

[darrelmiller]

From conversation with Vincent, decision is that we put interfaces and classes all in the same models folders.
We should use interfaces for request payload and responses payload in chained API.

[baywet]

@andrueastman this is ready for review, thanks for your help during the design time
@nikithauc @ramsessanchez @jobala if you have time to look at the languages you contribute to, it'd be greatly appreciated
@jasonjoh if you have time to look at the markdown modifications, it'd be appreciated as well.

I'm aiming to merge this this in by Friday so we can start testing that in Go/Dotnet/TS previews as the newer conversion lib releases.

[nikithauc]

From conversation with Vincent, decision is that we put interfaces and classes all in the same models folders. We should use interfaces for request payload and responses payload in chained API.

TS does not append an I- to the interfaces. In cases like that, how would the class names and interface names for the same model be conflict free?

[nikithauc]

If we fix the problem with circular dependency, will we still need the new CreateDiscriminator classes right?

[baywet]

@nikithauc

TS does not append an I- to the interfaces. In cases like that, how would the class names and interface names for the same model be conflict free?

This PR still adds most of the infrastructure needed for that change, the only missing piece would be to create the interfaces into a different namespace/package. (which I reverted after my convo with Darrel)

If we fix the problem with circular dependency, will we still need the new CreateDiscriminator classes right?

They are functions but yes, this part would still be needed after models classes inheritance is broken up and interfaces are introduced (like Go).

[andrueastman]

👍🏼 On the reorganization of the CodeDOM

Otherwise just a few comments from me.

[sonarqubecloud]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
4 Code Smells

88.0% Coverage
0.0% Duplication