How do we want to organize types in @dhis2/multi-calendar-dates?

[Mohammer5]

There are various ways of declaring types in TS projects, all come with their own set of advantages and disadvantages.
I'd like to talk about which options we have, so we can decide which way we'd like to go forward.

There are some considerations:

• Do we compile source code and generate a /build/types/index.d.ts (and colocated type files, which is what our platform script does) or do we want to explicitly define an index.d.ts (for example in <root>/index.d.ts)?
• How do we keep public and internal types separate?

This topic does not only affect how we bundle types with our libraries, it also has an impact on our type design. Type design is a very important topic, as the design - when done wrong - can increase the complexity of the library significantly, and we'll have a hard time maintaining the library. Contributing to the library is especially more difficult for people outside dhis2 when we unintentionally yet unnecessarily increase the complexity.

Here are some resources that can serve as inspiration for investigating this topic:

• TypeScript | Organizing and Storing Types and Interfaces
• Reddit: Best open source projects showcasing Typescript on github in 2021?
• How I organize my Typescript types.

[Mohammer5]

Differentiate between "exported types", "global types" & "local types"

To me, there are clear advantages when specifying exported types separately from the rest of the project. Having an index.d.ts files on the root level serves several purposes:

1. Types in <root>/index.d.ts should be available to the internal code (if this doesn't work with our tooling, we can add this file to the tsconfig.js's compilerOptions.typeRoots collection)
2. We declare the public interface that will be consumed by the user on the root level (similarly to a <root>/index.ts that controls which code will be available publicly)
3. This way we wouldn't be publicly exporting types located in types.ts files that export internally used types to which the user shouldn't have access to.
4. It forces us to think more about types as we want the public types (the contract we have with consuming code) to be designed independent of internal code design and as stable as possible while still having the freedom of having internal types which won't be scrutinised that much
5. It allows us to change internal types without having to worry about introducing breaking changes
6. It serves as a quick-to-look-at and quick-to-find documentation for the types a library provides

Using local types that are internal to a module (file):

1. we can easily create types that will help to document that particular module, e.g. with function signatures.
2. At the same time, this pattern allows us to not having to have to over abstract types. Ideally, most of the types in the project are local types. Although that violates the DRY pattern as there might be many similar function signatures, interfaces or union types, it will keep the code as simple as possible.
   • This has the disadvantage that changing existing code can be more work
   • But changing existing code becomes more trivial
   • And understanding existing code is a lot easier.
     • In my opinion, developers will spend a lot more time trying to understand how things work than refactoring code. This is my main argument for following a more repetitive, yet much simpler approach

Using global, but internal types, we can easily declare types that can be used through-out the entire project. But instead of scattering them through our application, we have one dedicated place for these types:

1. This way, every developer knows where to look for and where to put types
2. This pattern forces us to think more about types, especially in regard to coupling and cohesion.
   • These types are structurally decoupled from the rest of the code, as they're located in their own folder / module. This naturally helps with having less coupling and higher cohesion
   • These types can easily use, extend, implement or compose types located in type definition files for external/public types

Several large and well-known projects follow this or a very similar pattern:

• TypeScript uses a global types.ts
• Palantier uses a global types folder.
• Dexie uses a global types folder.
• DevCollective.io uses external type files as well as internal, local types.

Summary

By following this pattern,

• there's a clear hierarchy of which types can use types from other hierarchies (external -> global -> local)
• public/exported types are clearly defined
• coupling is limited while cohesion is increased
• there's an incentive to keep types as clean and simple as possible

[amcgee]

This sounds like a good proposal to me @Mohammer5 . We use the global internal types file pattern in app-runtime packages and I agree it helps make types more explicit and easier to reason about. I would be in favor of explicitly declaring exported types using a custom types root file.

[kabaros]

can I just clarify what we mean by exported types? In the case of the library here, the only exported types - and these would make part of the public API of the library - would be things that generate JS like enums or classes. Or do we mean any type that is associated to a public method?

[Mohammer5]

By public I mean accessible to other libraries and/or apps.
In regards to the multi-calendar-dates library, I'm not entirely sure which types are exposed and which are not. It doesn't mean that internal types are exposed, just that it's difficult to understand which types are exposed and which are not. It would be nice if we could make that part more explicit.

things that generate JS like enums or classes. Or do we mean any type that is associated to a public method?

As an example: Do we want to expose FixedPeriod? We're not exposing it right now. But that's only because the type is not explicitly exported from period-calculation/index.ts. As soon as we need that type in another folder/module within the app, we'll add it to that index.ts, which will then also expose that type. So the index.ts implicitly serves two purposes: First defining the public interface of a module (folder) (which is the intention) and second exporting types (which is a "side effect" not necessarily intended).

I think it'd make sense to expose FixedPeriod so that apps using TS can declare types of periods without having to manually creating and maintaining these types. And now my main question (and the reason for this discussion) is: How do we export that type? Do we export it in src/main.ts explicitly and create a build/types/index.d.ts that also exports that type? Or do we manually write an index.d.ts and leave it out of the src/main.ts?