How to Compare Two Definitions Structurally?

[blakeembrey]

I'm not sure if this feature is currently supported, or even whether the whole chain of features have been enabled to make this workflow work, but at the lowest level how would one compare two definitions (1.d.ts and 2.d.ts) and check if they're compatible? On top of this, would it be possible to access the definitions for a JavaScript library?

Reasoning: It'd be great to be able to type existing JavaScript libraries, but the biggest thing hindering third-parties is being able to integrate the workflow with CI. One way to improve this workflow would be with the --allowJs flag on the library itself to generate one definition, then comparing it to the user-written definition. Having the declarations flag work with --allowJs would also allow users to get started writing definitions 10x faster - just run tsc entry.js --allowJs --declaration --out definitions and improve the types little by little.

[basarat]

but at the lowest level how would one compare two definitions (1.d.ts and 2.d.ts) and check if they're compatible

Just compile:

import * as foo from "./foo";
import * as bar from "./bar";

let _foo: typeof foo;
let _bar: typeof bar;
_foo = _bar = _foo;

I haven't tested but should work 🌹

[blakeembrey]

@basarat Interesting hack. I guess I'd have to generate this file, assuming it works, to do the test. The only outstanding piece is allowJs and declarations then.

[mhegazy]

allowJs with --declaration should be easy to enable. the emitter needs to be hardened to handle missing types, something it does not expect today. we would accept a PR for this if you are interested.

The only restriction i see, there has to be a --out or --outDir to make sure that a.d.t.s is not dropped next to a.js so that next compilation will not pick the output a.d.ts (as .d.ts files are preferred to .js files).

[mhegazy]

@blakeembrey can you log an issue to track allowing --allowJs with --declaration?

[mhegazy]

As for the structural comparison, who is doing this? is it a command-line tool? do you expect it to be part of the compiler? how would it be surfaced to the user? what is the intended result?

if it is a separate tool, you can do what @basarat suggested.

[blakeembrey]

can you log an issue

Absolutely.

As for the structural comparison, who is doing this?

This is for writing type definitions with package authors. Definitely a CLI tool. I don't expect it to be part of the compiler. It can be part of @typings to validate a type definition on top of a JavaScript project. The intended result is that new, breaking API changes in JS have a chance of being caught by CI. For example, implementing typings for Express.js - references: expressjs/express#2818 and typings/typings#322.

[mhegazy]

Using the compiler API, we can definitely expose a new method on the TypeChecker to compare 2 types. so you would walk over the .d.ts file and the .js file simultaneously and get type for each export, and then compare their types.

[blakeembrey]

@mhegazy That sounds like it'd be perfect 👍

[mhegazy]

Feel free to file an issue for the API changes as needed.

[blakeembrey]

@mhegazy I couldn't find an existing issue and it seems more realistic as this same request, but would the TypeScript compiler consider exposing a mode where it only type checks .d.ts (header files) against .js (runtime files)? That's basically the request here, but without additional files being emitted. It'd allow people to adopt .d.ts files into projects and keep them maintained and up-to-date properly, a massive win for the ecosystem.

I was linked to a new project doing something like this, which renewed my interest in having a feature like this exposed (https://github.com/Raynos/jsig2).

[mhegazy]

We will need a proposal for what that means to implement. also what are the scenarios you would use this mode. i would be inclined to say this is a tool that the compiler API can support. but I would like to understand the full picture first.

[blakeembrey]

Anywhere we're working to merge .d.ts files into a JavaScript project. For example, moment or express. Right now, they have to guess changes to the .d.ts files. Ideally, they could write the header files and keep the JavaScript files and run tsc to catch type errors between them (like the linked project). This would guarantee that the people adopting writing definitions can keep them updated automatically (E.g. as part of CI). Without this, it'll need to be done manually and they'll need to check/remind every person that does a PR and changes the external .js shape - which is a difficult task to do manually.