Typescript: Provide a back-compat mechanism for bundled .d.ts files in package.json

[RyanCavanaugh]

People are always excited to use new type system features in their programs or definition files.

However, if these developers are shipping a library with bundled type definitions, they can't use these features in an exposed way unless they are willing to force all TS consumers of the library to upgrade to a matching compiler version.

This leads to awkward trade-offs and end-user confusion when they upgrade eventually does happen.

There should be some way for library authors to say "Use this .d.ts file if you're on this version of TypeScript" so they can provide back-compat ranges. This could be based on semver ranges provided in package.json:

{
  ...
  "types-compat": {
    "<=2.3": "backcompat/index-2.3.d.ts",
    "<=2.7": "backcompat/index-2.7.d.ts",
    "*": "index.d.ts"
  }
}

[mhegazy]

• And we expect ppl to build these files by hand editing the generated .d.ts files? or are these only for hand-authored files?
• Why is the model we have in Definitely Typed today not good enough?

[RyanCavanaugh]

I would expect these files to be either hand-created, or generated through some downleveling process.

The model for DT doesn't apply here since people may need e.g. the runtime v12 of a library for bugfix/feature reasons but not be able to consume type syntax from that version

[rbuckton]

A few comments:

• Most properties in package.json are camelCased, so I'd prefer "typesCompat" or "typesVersions" to "types-compat".
• Path mappings need to be templated, as not all package definitions use ambient modules.
• We don't need (and probably should disallow) a "*" version mapping as we still need to include "types" as the default for older versions of TypeScript.
• We most likely cannot support this in older versions of TypeScript, only 3.1 (or which ever version would ship this feature) or better.

[rbuckton]

cc: @DanielRosenwasser since we were discussing this feature this morning.

[rbuckton]

I put together a proposal that is very similar to this, which also addresses my earlier comments.

The key differences are:

• I used "typesVersion" instead of "types-compat"
• I used path templates for the mappings
• I specifically call out approximate path resolution semantics when importing from an ambient module (via declare module) vs. a non-ambient module.
• I don't specifically call out using semver, though I agree it would be useful (especially in a package.json)

I also describe a proposed structure for DefinitelyTyped packages that could be used by types-publisher to automate package.json generation and package deployments.

[rbuckton]

I would also like to add that this would address a number of issues:

• Transitioning IteratorResult from an interface to a union type would break NodeJS types (as well as es6-shim and es6-collections).
• Allow us to start leveraging /// <reference lib="..." /> in packages and remove empty forward-reference declarations for types like Iterator, AsyncIterator, IteratorResult, etc. (needed for node, es6-shim, core-js, etc.)
• Allow us to support newer features such as conditional types and unique symbols in heavily used "trunk" type packages (such as node, moment, etc.).

[AlexStacker]

@RyanCavanaugh Seeing this I have an idea, I want to add the different language comment version in.d.ts file, and decide which version of the comment to use based on the environment variable local of tsconfig.json or vscode. Friendly tips when using vscode.