Can TypeScript verify that a .js file is consistent with its own .d.ts declarations?

Question

Is it possible to have the TypeScript compiler check that a JavaScript file foo.js is consistent with its own declaration file foo.d.ts?

We have a body of JavaScript code that, for various reasons, we want to leave in JavaScript. If possible, though, we would love to use TypeScript to achieve two goals: 1) confirm our own JavaScript code is type safe, and 2) make declarations available to customers that are interested in using TypeScript.

For a given JavaScript file foo.js, we can create a corresponding file foo.d.ts to satisfy goal #2 (supporting TypeScript customers). But as far as we can tell, the existence of foo.d.ts does not result in any checking of foo.js. That is, the declaration file is only of interest to external consumers of foo.js, and the compiler doesn't verify that the JavaScript code is consistent with its own .d.ts declarations.

We've experimented with using jsDoc type annotations within foo.js, and the TypeScript compiler does verify that the code in that file is consistent with those declared types. That would seem to satisfy goal #1 (check our own code).

However, jsDoc annotations are not as powerful as the full TypeScript syntax possible in a .d.ts declaration file (e.g., jsDoc support for generics is rudimentary), which limits where we can use them. Furthermore, the TypeScript compiler doesn't seem to provide any verification that the jsDoc annotations are consistent with the .d.ts declarations. We run the risk of inconsistencies between those two sources of type information.

We're looking for guidance about the best way to leverage TypeScript type-checking in the context of a JavaScript project like this.

Answer 1

Is it possible to have the TypeScript compiler check that a JavaScript file foo.js is consistent with its own declaration file foo.d.ts

Not really. A .js file gives very little context about exactly what is and isn't supported. If it was possible, we wouldn't need TypeScript.

More

• Some discussion on TypeScript and FlowType and how they must restrict what is considered valid