Improve Declaration File Acquisition #9184
Comments
|
How will that work with npm? You would have to use the package.json version as the package version of the module, so how will you fix a bug in the typings that still targets the same version of the module? We have to release it as a new version, and then the versions would be out of sync with the module version and we have no way anymore to reference the actual module version, because a declaration update can be a breaking change. Furthermore, if you maintain a 3.x and a 4.x branch, how would you introduce a breaking change to the declarations in the 3.x branch? Typings solves this much better. Either more frameworks start bundling their typings with their modules or we need a seperate typings manager, that allows declarations to evolve independent of the module. |
|
NPM has version numbers too. We intend to use the I should add that if you want to continue using |
|
How are type definitions for different versions of TypeScript handled? Related discussion: typings/typings#49 |
|
We'll have tags for the latest version of a file compatible with each released version of the language starting at 2.0. So you could |
|
@RyanCavanaugh thanks |
|
This is a super rad idea, but how will people upload things to the |
|
Packages in the So to get a package published to |
|
I don't like how this feature is dependent on a single github repo and forcing us to put our typings there. Does this seem like a bad idea to anyone else? Also, it sounds like you are recommending that even lib authors should put their typings here even if we are generating our own typings? Shouldn't they just be included in the npm package if possible? |
Issue microsoft/types-publisher#4 is tracking supporting redirects.
No. Publishing declaration files with your packages would be the preferred course of action. for packages that do not include their declaration files, |
|
Ok, thank you for the clarification. |
So you would have to always use an exact dependency instead of a caret ^ or tilde ~ because a declaration change is often a breaking change in a way that it wont compile without code changes. So when a new module version comes out that automatically gets installed because your package.json semver range, you wont get the new typings for it, because you have to lock the version to prevent breaking changes. typings on the other hand, because the declaration version is tracked independently, could in theory allow us to specify a caret dependency and lock the declaration to prevent breaking changes: Imo using the patch section of the version for declaring the declaration version (that may also be a breaking change) is completely against semver and npm's idea of the version field in package.json.
Ok, so you can tag the last compatible version of a typing, but how do you tag the last compatible version of the 3.x branch and the 4.x branch of a module?
Putting all typing definitions in a single gigantic repository, where every module often only has a single .d.ts file with over 3000 lines of code and every change is done through a PR just doesn't scale. That's why typings moved over to one-repository-per-definition scheme, where the declaration structure mirrors the actual module structure and typings taking care of wrapping the definitions in |
|
Currently we have
I feel like instead of introducing yet another way to publish and install typings the TypeScript team should rather improve
TL;DR Scrap this idea and put the effort into |
|
For large and popular libraries, I agree that having a separate repo is the way to go. We fully intend to support that scenario by allowing redirection from DefinitelyTyped to other repos so that well-maintained libraries can have their own repo. For the ~80% of other libraries on DefinitelyTyped that don't have strong specific ownership and are managed on a more ad-hoc basis, having a separate repo for these is bad because it scales badly in the other direction. We could easily end up with six people having their own repo for calq, not knowing which is preferable. What happens when the owner for that repo doesn't use the library anymore? If I want to contribute a fix to this file, whose repo do I go to? If I'm a maintainer for DefinitelyTyped, how do I see all the pending PRs for the un-owned libraries out there? Having individual repos for well-owned definitions and a catch-all repo for ad-hoc-managed definitions is really the best of both worlds. I fully expect e.g. React to have its own repo, but having a separate repo for every definition leads us to the exact XKCD you just posted. |
that's where the typings registry comes in. The idea is simply that instead of hosting the whole definition in the repo you just host a reference.
|
|
I'm just not sure what you're going after here since we're basically supporting a superset of scenarios over what you're describing. Separate repos will be supported! Because there are many type definitions that don't have (or need) a specific owner, we don't want to raise the barrier to entry here to the point where submitting a four-line definition requires setting up your own repo, sending a separate PR to a registry, and implicitly agreeing to maintain it for the rest of your life. Having non-isolated definitions means we can have shared maintainership of the long tail of files, in one place. We're going to be stepping up our commitment to DefinitelyTyped in the future to decrease the latency of PRs; having the additional friction that we suddenly need a massive cross-repo PR query and pull request merge rights on 1,600 other repos isn't actually getting us anything in return. Again, you can still have a separate repo for your type definitions. That's a key scenario for well-owned definitions, but we have to consider the "long tail" of definitions as well. |
|
@RyanCavanaugh Valid points you raise there about DT, I didnt look at it that way until now. It may really be beneficial to keep DT for small definitions (even though, I would ideally like to see module authors bundling that four line definition, I mean come on guys, it doesn't cost you a penny :D). But typings supports DT... So I still don't see why we need npm. |
|
@mhegazy That's awesome |
|
I welcome needing to install one less tool. Consolidating on npm is a simple, clean solution. |
|
@RyanCavanaugh FWIW, that definition you reference is actually in the repo itself already 😄 We should make sure deprecation is handled effectively by the publishing tool also. Aside from that, the way I've been working with separate repos is by adding a large collection of people to @types and people can add repos there knowing the rest of the community already has access. Of course, this doesn't work for first time creation where you'd need to make your own repo, but you could always move the repo later if you get added to @types (for example). Do you imagine owning a @types like organisation (or I can add the MicroSoft team to @types)? |
|
The pros of this are immediately clear:
I can only think of one possible con: assuming the worst possible scenario wherein none of your dependencies ship with their own typings, this approach results in roughly double the number of |
|
@kourge Can you point me to where you found |
|
|
|
@mhegazy Did you resolve how you'd be handling sub-dependency being emitted where the |
And redirection is also pointing to separate repo. 😄 |
|
Another benefit @felixfbecker already mentioned and I want to emphasis on: testing Testing in DT (having typings in one giant repo) just doesn't scale, and the "shape test" done in DT is simply not sufficient: |
|
What is the correct procedure to report missing type definitions under @types that are already present in DefinitelyTyped? Like xpath for example? |
I would file an issue on https://github.com/DefinitelyTyped/DefinitelyTyped |
|
I'm currently testing TS 2.0 beta. And "npm-install" typings is a nice improvement, way faster than grabing definition files from DT. |
ghost
mentioned this issue
Version 2.0 brings a better way to manage type definitions. See microsoft/TypeScript#9184
TypeScript 2.0 introduces a better way of managing type definitions of third-party libraries using a combination of `npm` `@types` packages and type definitions built into each package. See microsoft/TypeScript#9184 for more details. As a result, I will migrate most of the type definitions currently managed by the `typings` tool over to these `npm` packages if the package authors didn't provide their own type definitions inside each package. That's the objective of this branch. However, although the author of `redux` does provide a type definition for his library (as an `index.d.ts` file inside the `redux` npm package), other `redux` plugins like `react-redux` and 'redux-thunk` has not updated their type definitions. As such, until those `redux` plugins update their type definitions, the type definitions for `redux` and those plugins will have to be "manually" managed i.e. not through an automated system like `tsd`, `typings` or `npm` packages. This commit adds the original version of these type definition files i.e. the versions that can be obtained through automated commands (listed below for reference). The next commit will slightly modify these definitions because they were intended to be used as "modular" definitions instead of as "global" definitions. - The `react-redux` type definition is version 4.4.8 of the `@types/react-redux` npm package. - The `redux-thunk` definition is version 2.0.27 of the `@types/redux-thunk` npm package. - The `redux` definition is the one that is bundled with version 3.5.2 of the `redux` npm package.
|
@DanielRosenwasser You mentioned in the first post that type definitions in
However, when I compile one of my repos with It looks like the compiler is always searching for type definitions inside the npm package itself first before searching inside |
|
This would get a lot more traction if the DefinitelyTyped readme file included |
|
@mhegazy I have the exact same problem as @realityfilter where a package (numeraljs) already exists in DefinitelyTyped for months but does not show up in NPM under The types-publisher documentation seems to mention some |
|
@billccn the package was published under the name https://www.npmjs.com/package/@types/numeral because that was the package name the declaration claimed to be for: https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/numeraljs/numeraljs.d.ts#L45 |
|
Indeed that's the actual package name itself https://www.npmjs.com/package/numeral -- the rule is always that the types package name matches the NPM package name (if one is available) |
|
Where is the documentation? I saw this and that, but I don't see an example of A working example of a correctly packaged module, correctly configured to build it's |
|
@mindplay-dk That's a separate feature, something that's been available since 1.5 of TypeScript. It uses the Edit: Here's a simple example - https://github.com/blakeembrey/free-style/blob/master/package.json#L6 which is used in https://github.com/blakeembrey/react-free-style/blob/master/package.json#L48. TypeScript resolves the field when using node module resolution. |
and others
In TypeScript 2.0, we want to make acquiring declaration files easier. We'd like to consolidate
.d.tsmanagement with general dependency management through npm.Background
TypeScript uses declaration files (files ending in
.d.ts, also called "definition" files) to describe the shape and functionality of other libraries. Usually, new declaration files are submitted to DefinitelyTyped, a community-driven repository of declaration files. Unfortunately, there are issues with the way a definition file gets from there to your project today.Once a declaration file is on DefinitelyTyped, you can get it through tools like Typings or tsd - package managers for declaration files. While very useful, these were extra tools to learn, and this added friction for new users. There were also some technical issues, such as lack of versioning and conflicting declarations, that existing tools couldn't manage.
The new world
So let's jump to the new world to contrast against the current one. Grabbing a declaration file won't require using tsd or Typings at all. It's just an npm command away:
That command does two things:
@types/lodashin our package'snode_modules.package.json.@types/lodashis nothing more than a scoped package. We have taken the time to import files from DefinitelyTyped into their own scoped package. But why does this matter, and why is it any different from how things worked before?Well in TypeScript 2.0, this
@typesfolder is going to be significant. Usually when we try to try toimport "lodash", we look in./node_modules/lodash,../node_modules/lodash,../../node_modules/lodash, etc. for type declarations. Instead, each time we peek into anode_modulesfolder as we climb up, we'll look for@types/lodashfirst, and then forlodash.That might sound surprising, but the logic is that if the
lodashpackage itself had type declarations, you wouldn't have installed@types/lodash.Global declaration files
Some declaration files only affect the globals, and don't use modules (e.g. Jasmine). In most cases, TypeScript will automatically pick them up from the
typeRootsoption. By default,typeRootswill just benode_modules/@types/andnode_modules/, relative to atsconfig.jsonor for loose files, the files themselves.If for some reason, you need to include Jasmine but it's not present in your
typeRoots, then you can use thetypescompiler option to trigger the same sort of resolution that happens for modules, where TypeScript will look in./node_modules/@types/,./node_modules, and keep climbing up.The
typesoption could be used something like this.{ "compilerOptions": { "types": ["jasmine"] } }Going forward
Library authors will be getting attention in 2.0 as well. We're also introducing new features that simplify the way
.d.tsfiles can be authored for libraries that are both modules and globally defined (also called universal modules). Apart from that, everything stays the same - for instance, new declarations and fixes should still go to DefinitelyTyped. In the future, we'll go into this in more detail and have some prescriptive documentation.Acknowledgements
We also owe a great thanks to those who dedicated their own time into efforts like Typings and tsd.
These tools helped bring TypeScript where it is today and ultimately helped guide us on the direction for this effort. Specifically, Blake Embrey, the maintainer and creator of Typings, has worked closely with us during this entire process and given us extremely valuable feedback. In addition to this, Diullei Gomes and Bart van der Schoor, maintainers of tsd, have helped lay the foundation from the beginning.
Finally, the entire DefinitelyTyped community - a group that has grown to over 2000 contributors at this point - have demonstrated, and continue to show, the kind of enthusiasm and support outside of the core team. We're grateful for all the great work that's been done here.
The text was updated successfully, but these errors were encountered: