TypeScript Guidelines - Types: Inference, Annotations, Assertions, Escape Hatches

[MajorLift]

Motivation

In order to improve type safety and maintainability, we need to establish clear guidelines regarding how to apply types: specifically, when and when not to use explicit type declarations or keywords such as as, any.

Explanation

• See markdown preview: TypeScript Guidelines - "Types" section
• The merge conflicts with main will be resolved after the review process to avoid noisy diffs.
• All examples are tagged with a permalink for easy reference and quotation.

Table of Contents

• Types
  • Type Inference
  • Type Annotations (:, satisfies)
  • Type Assertions (as, !)
  • Escape Hatches (any, @ts-expect-error)

Details

• Dangers and advantages.
• Tips for avoiding.
• Acceptable use cases.

References

• Closes Add entry forany, as usage in TypeScript Guidelines doc #47
• Closes Add TS guideline: "Document safe or necessary uses of type assertions" #57
• Contributes to Complete TypeScript guidelines #69

[mcmire]

Lots of good stuff to chew on here! I skimmed through it one more time. This gets me thinking that it may be valuable to have two different kinds of documents in the future, one that's purely "do"s and "don't"s, and another that is a bit more expositional. We can decide on that in the future though. Nice work!