Create spec for TypeScript model usage using interfaces and classes.

[nikithauc]

#1013 identified the requirement to generate model as interfaces which is a convention for JavaScript/TypeScript community. The solution that is introduced to this is

• Create model interfaces from model classes
• Maintain classes with an Impl suffix.
• Suggest the use of interfaces to deal with model objects and abstract the model class implementation.

However, there is also a part of the community which uses classes for models. For instance, Angular and NestJS recommend the use of classes instead of interfaces for models (although many angular users do prefer model interfaces).

Expectation of this issue:

• Have a better naming for classes and interfaces. Something better than -Impl. Kiota generation should ease the breaking changes when we need to add/modify models support updates in the future.

• The Kiota generation should take into consider that the TS some user might use interfaces AND/OR classes for models and pass allow generation commands to users the options the type of models that they want.
  This can be more of an incremental effort allowing more community friendly generation commands to be added in the future.

[baywet]

Alternatively we could place the interfaces in a "contracts" package name and the classes in the "models" one (original name).

[sebastienlevert]

Just as an idea and see if that even makes sense. Could Interfaces and Classes have the same name and the interface could implement the "Aliased" model?

This is definitely an interesting scenario that I'm willing to have a look at, but I'll be waiting for community feedback before taking on this work. We've been using interfaces for ages (in our JS SDK) and it's not something I've seen mentioned strongly.

[nikithauc]

We've been using interfaces for ages (in our JS SDK) and it's not something I've seen mentioned strongly

Interfaces is common and popularly preferred used, yes. But there are some users that use classes as well and that could work with small size sdks.

Our current design exports both interfaces and models. We need a clear story

• Explaining users why we have classes as well.
• Allowing the option to work only with classes and a good naming and documentation for that.
• May be allowing users to pick one type of models (if requested by the community).

[baywet]

Expanding on the size aspect, we had a very productive meeting with the pnp folks this morning and they reminded us of an alternative that would be easily adaptable to our current model: selective import.

We could enable that only at the root level (so everything directly under the client). By default the client would only have the basic configuration things and that's it. If you import /me or /groups, the client would then be augmented by everything under /me or /groups . This would help not only the size/tree shaking discussion, but also the auto completion experience. Worth investigating.

[baywet]

More documentation on the experience aspect https://pnp.github.io/pnpjs/concepts/selective-imports/ How it's implemented https://github.com/pnp/pnpjs/blob/version-3/packages/sp/sites/index.ts

[baywet]

not needed anymore since we're moving to full interfaces for models, query parameters and request configuration. The only thing left will be the backing store, but we'll be most likely using a proxy for that.