Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Provide a back-compat mechanism for bundled .d.ts files in package.json #22605

Closed
RyanCavanaugh opened this issue Mar 15, 2018 · 7 comments · Fixed by #26568
Closed

Provide a back-compat mechanism for bundled .d.ts files in package.json #22605

RyanCavanaugh opened this issue Mar 15, 2018 · 7 comments · Fixed by #26568
Labels
Committed The team has roadmapped this issue Suggestion An idea for TypeScript

Comments

@RyanCavanaugh
Copy link
Member

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"
  }
}
@RyanCavanaugh RyanCavanaugh added Suggestion An idea for TypeScript In Discussion Not yet reached consensus labels Mar 15, 2018
@mhegazy
Copy link
Contributor

mhegazy commented Apr 5, 2018

  • 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
Copy link
Member Author

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
Copy link
Member

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
Copy link
Member

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

@rbuckton
Copy link
Member

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
Copy link
Member

rbuckton commented Aug 15, 2018

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
Copy link

@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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Committed The team has roadmapped this issue Suggestion An idea for TypeScript
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants