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

Improve Declaration File Acquisition #9184

Closed
DanielRosenwasser opened this Issue Jun 15, 2016 · 68 comments

Comments

Projects
None yet
@DanielRosenwasser
Copy link
Member

DanielRosenwasser commented Jun 15, 2016

In TypeScript 2.0, we want to make acquiring declaration files easier. We'd like to consolidate .d.ts management 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:

npm install --save @types/lodash

That command does two things:

  1. Grabs the declaration files for lodash and saves it to a directory named @types/lodash in our package's node_modules.
  2. Saves that as a dependency in our package.json.

@types/lodash is 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 @types folder is going to be significant. Usually when we try to try to import "lodash", we look in ./node_modules/lodash, ../node_modules/lodash, ../../node_modules/lodash, etc. for type declarations. Instead, each time we peek into a node_modules folder as we climb up, we'll look for @types/lodash first, and then for lodash.

That might sound surprising, but the logic is that if the lodash package 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 typeRoots option. By default, typeRoots will just be node_modules/@types/ and node_modules/, relative to a tsconfig.json or 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 the types compiler 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 types option 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.ts files 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.

@felixfbecker

This comment has been minimized.

Copy link

felixfbecker commented Jun 15, 2016

typings allows us to version declarations independent from packages. So we can have typings for version 3.2 and 4.6 of the same module. If there was a bug in just the typings, we can update just the typings by adding a timestamp, and they still reference the same package version.

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.

@RyanCavanaugh

This comment has been minimized.

Copy link
Member

RyanCavanaugh commented Jun 15, 2016

NPM has version numbers too. We intend to use the X.Y.z scheme where X.Y is the version of the targeted package and z is the version of the typings file. We'll also be adding support in DefinitelyTyped (and other type definition sources) to have multiple types checked in, so you could have e.g. /jquery/1.x/ and /jquery/2.x folders so they can be maintained separately if that's desired.

I should add that if you want to continue using typings because of some complex versioning scenarios you're anticipating, nothing in these changes will prevent you from doing so.

@myitcv

This comment has been minimized.

Copy link

myitcv commented Jun 15, 2016

How are type definitions for different versions of TypeScript handled?

Related discussion: typings/typings#49

@RyanCavanaugh

This comment has been minimized.

Copy link
Member

RyanCavanaugh commented Jun 15, 2016

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 npm install @types/foo@ts2.1 or whatever if you need the 2.1-compatible file.

@myitcv

This comment has been minimized.

Copy link

myitcv commented Jun 15, 2016

@paulcbetts

This comment has been minimized.

Copy link

paulcbetts commented Jun 15, 2016

This is a super rad idea, but how will people upload things to the @types scope?

@mhegazy

This comment has been minimized.

Copy link
Contributor

mhegazy commented Jun 15, 2016

Packages in the @types scope are auto generated from definitions on https://github.com/DefinitelyTyped/DefinitelyTyped using https://github.com/Microsoft/types-publisher.

So to get a package published to @types you need to submit a PR to DefinitelyTyped.

@ejsmith

This comment has been minimized.

Copy link

ejsmith commented Jun 15, 2016

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?

@mhegazy

This comment has been minimized.

Copy link
Contributor

mhegazy commented Jun 15, 2016

I don't like how this feature is dependent on a single github repo and forcing us to put our typings there.

Issue Microsoft/types-publisher#4 is tracking supporting redirects.

Also, it sounds like you are recommending that even lib authors should put their typings here even if we are generating our own typings?

No. Publishing declaration files with your packages would be the preferred course of action. for packages that do not include their declaration files, @types, would be the correct place for them.

@ejsmith

This comment has been minimized.

Copy link

ejsmith commented Jun 15, 2016

Ok, thank you for the clarification.

@felixfbecker

This comment has been minimized.

Copy link

felixfbecker commented Jun 15, 2016

@RyanCavanaugh

NPM has version numbers too. We intend to use the X.Y.z scheme where X.Y is the version of the targeted package and z is the version of the typings file.

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: "sequelize": "registry:npm/sequelize#^3.0.0+20160604152601"

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.

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 npm install @types/foo@ts2.1 or whatever if you need the 2.1-compatible file.

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?

We'll also be adding support in DefinitelyTyped (and other type definition sources) to have multiple types checked in, so you could have e.g. /jquery/1.x/ and /jquery/2.x folders so they can be maintained separately if that's desired.

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 declare module '...' blocks. They can have their own tests, CI, PRs etc and are tracked in the typings registry. Instead of one file per version, they have a typings.json and actual versions, branches etc. This is much much better than DefinitelyTyped, and every definition on DT should be moved over to this new way.

@felixfbecker

This comment has been minimized.

Copy link

felixfbecker commented Jun 15, 2016

Currently we have

  • DefinitelyTyped, which has a number of problems I outlined above
  • typings, the new definition manager that has great potential, but is still young and most of the typings are still in DT
  • bundled definitions in modules, which is not every module maintainer is willing to support

I feel like instead of introducing yet another way to publish and install typings the TypeScript team should rather improve typings even further (for example, we could make installation easier by automatically reading package.json and searching for typings) and make it the recommended way™ to install typings.

image

TL;DR Scrap this idea and put the effort into typings

@RyanCavanaugh

This comment has been minimized.

Copy link
Member

RyanCavanaugh commented Jun 15, 2016

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.

@felixfbecker

This comment has been minimized.

Copy link

felixfbecker commented Jun 15, 2016

@RyanCavanaugh

We could easily end up with six people having their own repo for calq, not knowing which is preferable.

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.

If I want to contribute a fix to this file, whose repo do I go to?

typings info <package name> shows you the source repository.

@RyanCavanaugh

This comment has been minimized.

Copy link
Member

RyanCavanaugh commented Jun 15, 2016

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.

@felixfbecker

This comment has been minimized.

Copy link

felixfbecker commented Jun 15, 2016

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

@paulcbetts

This comment has been minimized.

Copy link

paulcbetts commented Jun 15, 2016

@mhegazy That's awesome

@sjansen

This comment has been minimized.

Copy link

sjansen commented Jun 15, 2016

I welcome needing to install one less tool. Consolidating on npm is a simple, clean solution.

@blakeembrey

This comment has been minimized.

Copy link
Contributor

blakeembrey commented Jun 15, 2016

@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)?

@kourge

This comment has been minimized.

Copy link

kourge commented Jun 15, 2016

The pros of this are immediately clear:

  • Use npm for what it's best at: dependency and version management
  • Does not require additional tool and thus lowers entry barrier
  • Establishes a more confident "authoritative" typing status without diminishing existing sources of typings
  • For those who have their own npm org / user scope, typeRoots provides a promising way of leveraging npm to add your own custom typings.

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 package.json dependencies, in contrast against the typings approach, where your typings.json would roughly parallel package.json but would remain as a separate file.

@blakeembrey

This comment has been minimized.

Copy link
Contributor

blakeembrey commented Jun 15, 2016

@kourge Can you point me to where you found typeRoots? Last I knew it was being omitted because of dependency complexity.

@mhegazy

This comment has been minimized.

Copy link
Contributor

mhegazy commented Jun 15, 2016

typeRoots is not omitted. it is still in.

@blakeembrey

This comment has been minimized.

Copy link
Contributor

blakeembrey commented Jun 15, 2016

@mhegazy Did you resolve how you'd be handling sub-dependency being emitted where the typesRoot property has been customised?

@unional

This comment has been minimized.

Copy link
Contributor

unional commented Jun 15, 2016

definition you reference is actually in the repo itself already

And redirection is also pointing to separate repo. 😄
Also I would guess redirection will be something pretty close to typings/registry.

@unional

This comment has been minimized.

Copy link
Contributor

unional commented Jun 15, 2016

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:
https://github.com/typings/generator-typings#about-writing-tests-for-typings

@mhegazy

This comment has been minimized.

Copy link
Contributor

mhegazy commented Jul 19, 2016

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

@yahiko00

This comment has been minimized.

Copy link

yahiko00 commented Jul 19, 2016

I'm currently testing TS 2.0 beta. And "npm-install" typings is a nice improvement, way faster than grabing definition files from DT.

huy-nguyen pushed a commit to huy-nguyen/restaurant-menu-builder that referenced this issue Jul 29, 2016

Huy Nguyen
Upgrade typescript version
Version 2.0 brings a better way to manage type definitions. See
Microsoft/TypeScript#9184

huy-nguyen pushed a commit to huy-nguyen/restaurant-menu-builder that referenced this issue Jul 29, 2016

Huy Nguyen
Manually add best type definitions for redux, react-redux, redux-thunk
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.

@deevus deevus referenced this issue Aug 2, 2016

Merged

Add html-webpack-plugin v2.22.2 #10373

2 of 3 tasks complete
@huy-nguyen

This comment has been minimized.

Copy link

huy-nguyen commented Aug 3, 2016

@DanielRosenwasser You mentioned in the first post that type definitions in @types packages will be read first before definitions included inside a package (e.g. index.d.ts):

Well in TypeScript 2.0, this @types folder is going to be significant. Usually when we try to try to import "lodash", we look in ./node_modules/lodash, ../node_modules/lodash, ../../node_modules/lodash, etc. for type declarations. Instead, each time we peek into a node_modules folder as we climb up, we'll look for @types/lodash first, and then for lodash.

That might sound surprising, but the logic is that if the lodash package itself had type declarations, you wouldn't have installed @types/lodash.

However, when I compile one of my repos with tsc 2.0 and enable --traceResolution, this is what I see instead:

======== Resolving module 'redux' from '/Users/huynguyen/Sites/restaurant-menu-builder/src/ts/reducers/reducer.ts'. ========
Module resolution kind is not specified, using 'NodeJs'.
Loading module 'redux' from 'node_modules' folder.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/ts/reducers/node_modules/redux.ts' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/ts/reducers/node_modules/redux.tsx' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/ts/reducers/node_modules/redux.d.ts' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/ts/reducers/node_modules/redux/package.json' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/ts/reducers/node_modules/redux/index.ts' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/ts/reducers/node_modules/redux/index.tsx' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/ts/reducers/node_modules/redux/index.d.ts' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/ts/reducers/node_modules/@types/redux.ts' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/ts/reducers/node_modules/@types/redux.tsx' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/ts/reducers/node_modules/@types/redux.d.ts' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/ts/reducers/node_modules/@types/redux/package.json' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/ts/reducers/node_modules/@types/redux/index.ts' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/ts/reducers/node_modules/@types/redux/index.tsx' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/ts/reducers/node_modules/@types/redux/index.d.ts' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/ts/node_modules/redux.ts' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/ts/node_modules/redux.tsx' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/ts/node_modules/redux.d.ts' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/ts/node_modules/redux/package.json' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/ts/node_modules/redux/index.ts' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/ts/node_modules/redux/index.tsx' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/ts/node_modules/redux/index.d.ts' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/ts/node_modules/@types/redux.ts' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/ts/node_modules/@types/redux.tsx' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/ts/node_modules/@types/redux.d.ts' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/ts/node_modules/@types/redux/package.json' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/ts/node_modules/@types/redux/index.ts' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/ts/node_modules/@types/redux/index.tsx' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/ts/node_modules/@types/redux/index.d.ts' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/node_modules/redux.ts' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/node_modules/redux.tsx' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/node_modules/redux.d.ts' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/node_modules/redux/package.json' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/node_modules/redux/index.ts' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/node_modules/redux/index.tsx' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/node_modules/redux/index.d.ts' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/node_modules/@types/redux.ts' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/node_modules/@types/redux.tsx' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/node_modules/@types/redux.d.ts' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/node_modules/@types/redux/package.json' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/node_modules/@types/redux/index.ts' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/node_modules/@types/redux/index.tsx' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/src/node_modules/@types/redux/index.d.ts' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/node_modules/redux.ts' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/node_modules/redux.tsx' does not exist.
File '/Users/huynguyen/Sites/restaurant-menu-builder/node_modules/redux.d.ts' does not exist.
Found 'package.json' at '/Users/huynguyen/Sites/restaurant-menu-builder/node_modules/redux/package.json'.
'package.json' has 'typings' field './index.d.ts' that references '/Users/huynguyen/Sites/restaurant-menu-builder/node_modules/redux/index.d.ts'.
File '/Users/huynguyen/Sites/restaurant-menu-builder/node_modules/redux/index.d.ts' exist - use it as a name resolution result.
Resolving real path for '/Users/huynguyen/Sites/restaurant-menu-builder/node_modules/redux/index.d.ts', result '/Users/huynguyen/Sites/restaurant-menu-builder/node_modules/redux/index.d.ts'
======== Module name 'redux' was successfully resolved to '/Users/huynguyen/Sites/restaurant-menu-builder/node_modules/redux/index.d.ts'. ========

It looks like the compiler is always searching for type definitions inside the npm package itself first before searching inside @types package. What do you think?

@matijagrcic

This comment has been minimized.

Copy link

matijagrcic commented Aug 8, 2016

This would get a lot more traction if the DefinitelyTyped readme file included

@billccn

This comment has been minimized.

Copy link

billccn commented Aug 8, 2016

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

The types-publisher documentation seems to mention some definitions.json file that seems to be manually maintained by you guys?

@RyanCavanaugh

This comment has been minimized.

Copy link
Member

RyanCavanaugh commented Aug 8, 2016

@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

@RyanCavanaugh

This comment has been minimized.

Copy link
Member

RyanCavanaugh commented Aug 8, 2016

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)

@mindplay-dk

This comment has been minimized.

Copy link

mindplay-dk commented Sep 19, 2016

Where is the documentation?

I saw this and that, but I don't see an example of package.json and tsconfig.json for a type-safe Typescript 2.0 module - an actual type-safe package; that's what this feature is about, right?

A working example of a correctly packaged module, correctly configured to build it's .d.ts file, and a package using that module, with type-safety, would be really useful.

@blakeembrey

This comment has been minimized.

Copy link
Contributor

blakeembrey commented Sep 19, 2016

@mindplay-dk That's a separate feature, something that's been available since 1.5 of TypeScript. It uses the package.json -> typings field. You can find any TypeScript module under my user is published using this approach. The @types approach is about improving accessibility of third-party typings for non-TypeScript modules.

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.

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.