Idiomatic organisation of types

[bodymindarts]

Currently we have 1 file:

src/types.ts

from which we import the types.

An idiomatic way to do this would be:

@types/globalTypes/index.d.ts
@types/globalTypes/xxx.d.ts

Like this typescript should pick up the types automatically without needing to import them.

[vindard]

I can take a look at this next

---

Notes (:leaves: evergreen)

(adding below as I look into this)

• Recommended reading: This looks like a good comprehensive overview of how to tackle this issue: https://medium.com/jspoint/typescript-type-declaration-files-4b29077c43

• An example I found of Declaration file usage: https://www.youtube.com/watch?v=GVUPOvCRmSY

On getting d.ts types into the global namespace

Linking the path:

• "typeRoots" may be a backward compatibility thing, and "paths" may be more correct to use: typeRoots is not finding custom declaration file microsoft/TypeScript#22217 (comment)
• we can optionally simply make sure the file/dir is covered in the "include" setting: stackoverflow.com

Having imports inside d.ts file:

• Using import/export statements in a global declaration turns it into a module declaration file and breaks global nature

  • https://stackoverflow.com/q/42233987
  • https://stackoverflow.com/a/39131986

• There's a way around this import problem: https://stackoverflow.com/a/58375303
  Applied here to resolve issue in our current types.ts file which imports things like the Logger type.

---

For additional consideration on global types as a common practice

I found some additional little comments when searching around on this. I'm not sure how viable or not they are, but I thought I'd include them here just in case we'd need to consider them for moving forward.

• This comment says "global types" are highly discouraged:
  
  

[vindard]

Like this typescript should pick up the types automatically without needing to import them.

@bodymindarts just to be clear on this, is this issue asking that we stop explicitly importing types and rather have all our own declarations available globally as well?

I started looking into this approach and it seems that one problem that would need to be managed is namespace clashes. For e.g. if the type exists globally already and someone re-declares it locally, I believe the existing global type simply gets extended, which can lead to some potential unexpected behaviours.

It also looks like this sort of functionality is usually reserved for vendor typings (if I understand correctly)

---

Edit 1: Adding feedback from 22/Jul Dev West call

Points made by Samer:

• We do want to continue with global implicit types, and we prefer this over explicit imports
• On the point of namespacing, we don't foresee this being a problem because ideally we would like to have more specific naming (generic names may be a code smell); this point ties into GraphQL API considerations as well

[vindard]

Implementation (:leaves: evergreen)

I've started playing with an implementation here.
.

Next steps:

• resolve some issues I'm having when including import statements in the index.d.ts file
  import/export statements aren't supported in global declaration files, but import() function is (see Notes)

• figure out which is better between using "paths" or "typeRoots" in the tsconfig.json file and figure out if node_modules and any other dirs need to be explicitly included in that setting
  we can simply use the "include" setting (see Notes)

• move non-type values (likely into config.ts) and bring over the rest of the types/interfaces from types.ts

[bodymindarts]

Some thoughts on this topic. I have to say I actually like explicit imports in general. It makes it easier to see the dependencies of file.
Am I correct in assuming that the dependency graph will still be clearly identifiable from the remaining imports of source code level dependencies even with global types?
I am a bit worried that global types will make it harder to detect things like circular dependencies.

That being said I think we certainly should adopt what is generally accepted as an idiomatic style from the ts community. @samerbuna has the most ts experience and is advocating for this approach. Could you perhaps post a link to 1 or 2 projects you consider doing this in an idiomatic way so we have something to refer to in this consideration?

I completely agree with the explicit type names argument regardless of scoping.
Will namespaces for types imported from 3rd parties mitigate the type shadowing issue? Would it be hard / break with idiomatic practice to also use namespaces in our own code?

[vindard]

I just added some additional notes to the 'Notes ( 🍃 evergreen)' comment above on:

• importing/exporting in global declaration files
• global type declarations as recommended practice

[vindard]

Based on chat with @samerbuna, we decided that the approach will be to:

• have corresponding .d.ts files alongside regular files in modules as an ideal structure
• temporarily have a global types.d.ts file for types that don't map cleanly to a single module

The goal will be to minimize, and if possible eventually remove the global types.d.ts file.