Declare a minimum supported version of TypeScript (v2)

[aoberoi]

Description

Bolt for JS is great to use in a TypeScript project because it gives you lots of useful information about the Slack platform while you're writing your code (as opposed to when you're running your code).

TypeScript doesn't use SemVer version numbers the way most dependencies do. A developer using TypeScript depends on the declaration files emitted from this project. TypeScript introduces features in minor versions which can change in a backwards incompatible manner. So a version specifier like ^3.4.3 (the specifier used on master right now) doesn't adequately communicate compatibility. Therefore in order to communicate compatibility, we need to pick a minimum minor version that we intend this package to be used with. We can use integration tests to verify compatibility of the declaration files against that minor version.

In the Node Slack SDK, the minimum TS version changes once per major version of the package(s). We can use the same policy in Bolt for JS.

Since v2 is almost ready to release, we can pick that version now. We want to find a version that balances new features with value to this project (at this major version) and old enough that most users won't have a difficult time to upgrade to using it.

I propose for v2.0, we set the minimum TypeScript version to 3.7. This version was released in Oct 2019. The current version is 3.8, which leaves the following declaration-impacting features as ones we cannot use for v2.x of Bolt for JS:

• Type-only imports and exports

  • In a few places we import a dependency only to be able to reference a type (e.g. WebClient or Logger). A side-effect is that the emitted code still produces a require() that isn't technically needed. This feature would help eliminate those unnecessary require()s.

• ECMAScript private fields

  • In all our classes we use private properties to store data which users should not access. However, if they wanted to access them, they still could. This feature would allow us to enforce the privacy of that data which can eliminate whole classes of errors. It also limits the freedom of how our classes can be used (especially subclassing). It's not clear there is a need for enforcing privacy of data at this time.

There will be more features in future versions of TypeScript that we cannot use, that is inevitable in declaring a minimum supported version. However, these are the significant features we gain (over TypeScript 3.4 which can loosely be interpreted as our current supported minimum):

• (3.7) Optional chaining (?., ?()) Nullish Coalescing (??)
• (3.7) Assertion signatures
  • Useful for implementing validation or verification, where you don't want the function to resume if a certain condition fails, and the type of variables will be narrowed in all the following code.
• (3.7) Better recursive types ❗️
  • Useful for typing JSON structures like body, state, and other places where we currently use StringIndexed to roughly mean "a bag of data".
• (3.7) useDefineForClassFields
  • Helps align the emitted code with spec compatibility for public class fields
• (3.6) get and set accessors in ambient contexts
  • Once again, helps align emitted declarations with spec compatibility for public class fields.
• (3.6) Ambient classes and functions can merge
  • This should help in cases where we are depending on libraries which use a kind of export that works in CommonJS but is tricky to get right with the ES Module (import/export) syntax.
• (3.5) Omit helper type
  • Allows us to stop writing our own version of this helper type.

Requirements (place an x in each of the [ ])

• I've read and understood the Contributing guidelines and have done my best effort to follow them.
• I've read and agree to the Code of Conduct.
• I've searched for any related issues and avoided creating a duplicate issue.

[aoberoi]

Useful for reference:

• TypeScript 3.8 release notes
• TypeScript running release notes (for everything before 3.8)

[seratch]

This looks great to me 👍

[stevengill]

Sweet! Let's do it! Figure we want to update the dep in package.json and add a note to the migration guide