node.js typescript npm typescript-typings definitelytyped

How to relate a version of @types package to the versions of the associated JS package?

I am working on a nodejs project with typescript 2.2 that is using node 6.3.1 and I want to migrate from using typings to using @types. By doing so I ran into a set of questions related to whether there is a relationship between the version of the @types file and the corresponding npm package.

If I use jasmine as an example, the existing versions of the types definitions are

npm show @types/jasmine@* version
@types/jasmine@1.3.0 '1.3.0'
@types/jasmine@1.3.1 '1.3.1'
@types/jasmine@1.3.2 '1.3.2'
@types/jasmine@2.2.29 '2.2.29'
@types/jasmine@2.2.30 '2.2.30'
@types/jasmine@2.2.31 '2.2.31'
@types/jasmine@2.2.32 '2.2.32'
@types/jasmine@2.2.33 '2.2.33'
@types/jasmine@2.2.34 '2.2.34'
@types/jasmine@2.5.35 '2.5.35'
@types/jasmine@2.5.36 '2.5.36'
@types/jasmine@2.5.37 '2.5.37'
@types/jasmine@2.5.38 '2.5.38'
@types/jasmine@2.5.39 '2.5.39'
@types/jasmine@2.5.40 '2.5.40'
@types/jasmine@2.5.41 '2.5.41'
@types/jasmine@2.5.42 '2.5.42'
@types/jasmine@2.5.43 '2.5.43'
@types/jasmine@2.5.44 '2.5.44'
@types/jasmine@2.5.45 '2.5.45'
@types/jasmine@2.5.46 '2.5.46'

But if I examine the versions of the jasmine packages I have;

npm show jasmine@* version
jasmine@2.0.1 '2.0.1'
jasmine@2.1.0 '2.1.0'
jasmine@2.1.1 '2.1.1'
jasmine@2.2.0 '2.2.0'
jasmine@2.2.1 '2.2.1'
jasmine@2.3.0 '2.3.0'
jasmine@2.3.1 '2.3.1'
jasmine@2.3.2 '2.3.2'
jasmine@2.4.0 '2.4.0'
jasmine@2.4.1 '2.4.1'
jasmine@2.5.0 '2.5.0'
jasmine@2.5.1 '2.5.1'
jasmine@2.5.2 '2.5.2'
jasmine@2.5.3 '2.5.3'

Let’s say I am using version 2.4.0 of jasmine, which version of @types/jasmine should I pick? Because even if I use the latest of both, 2.5.46 does not match with 2.5.3.

Another example would be node itself, there are basically 6.0 or 7.0 versions in @types, and typings has only the ones shown below, being 6.0 reported as obsolete. So, what version of node are those typings actually tied to?

typings view dt~node --versions
TAG                  VERSION DESCRIPTION COMPILER LOCATION
                          UPDATED
7.0.0+20170322231424 7.0.0                        github:DefinitelyTyped/DefinitelyTyped/node/index.d.ts#a4a912a0cd1849fa7df0e5d909c8625fba04e49d 2017-03-22T23:14:24.000Z
6.0.0+20161121110008 6.0.0                        github:DefinitelyTyped/DefinitelyTyped/node/node.d.ts#fb7fbd28b477f5e239467e69397ed020d92817e7  2016-11-21T11:00:08.000Z

Thanks

Solution

The major and minor versions of the DefinitelyTyped packages are supposed to correspond to the major and minor versions of the package they are types for. The patch version increments whenever the .d.ts file changes for other reasons. Because the minor version shouldn't represent breaking changes, in theory, you can use the highest 2.x.y definition file available for a 2.a.b.c library.

But now the caveats begin.

The header in the definition file may not have changed at the right time
Library authors do not necessarily follow semver*
The definition file may not be 100% correct at any given point, in either direction (i.e. listing a 2.6 feature under a 2.5 version, or failing to list a 2.4 in function in the 2.5 file)

* In fact, no one does

A detailed explanation can be found in official docs FAQ:
How do Definitely Typed package versions relate to versions of the corresponding library?