Type checking and IntelliSense with JSDoc typed js dependencies

Search Terms

JSDoc types dependenies

Suggestion

Possible alternative to #7546: Maybe type checking from JSDoc annotated dependencies can be achieved more easily in a different way. I have created a gist with a demo project that successfully uses a dependency (ol@6.0.0-beta.1 with fully JSDoc typed sources. This works well to get IntelliSense in VS Code for projects authored in pure JavaScript, but requires a not very obvious jsconfig.json configuration. Similar configurations (with tsconfig.json) partially work with TypeScript projects, but are very fragile quite easily, especially in more complex projects. And they only work when the "noEmit": true option is used.

However, it looks like a much lower hanging fruit than making .d.ts file generation work from JSDoc annotated JavaScript code (#7546). As the above example shows, it works already, but it should work out of the box and also in more complex configurations with TypeScript.

Use Cases

Full type checking and tsc support in both JavaScript and TypeScript projects with pure JavaScript dependencies. The dependencies are either JSDoc typed directly or published with their JSDoc typed sources.

This has to work without .d.ts files, because these cannot be generated from .js sources, neither with tsc nor reliably with third party applications.

Examples

Two possible scenarios:

1. A package that only contains untranspiled JSDoc-typed modules. Unrealistic, because class inheritance is only fully recognized by TypeScript when the ES2015 class and extends keywords are used, which packages don't usually do, because it limits interoperability.
2. A package that contains transpiled modules in addition to the original JSDoc-typed sources. Realistic and feasible, especially when source maps can point to these sources directly. An example for this would be ol@6.0.0-beta.1.

So let's assume the latter case is the more common one. If TypeScript would look for a tsconfig.json in dependencies (e.g. node_modules/ol/tsconfig.json), that file could have a config option to point to the annotated sources. Maybe something like

{
  "compilerOptions": {
    "jsSources": [
      "src/**/*.js"
    ]
  }
}

Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

Reproduce the linked gist and compare the jsconfig.json and tsconfig.json configurations described in the issue. Start by tracing how TypeScript resolves JavaScript dependencies and their JSDoc-annotated sources; done should mean type checking and IntelliSense work for JavaScript and TypeScript projects without requiring .d.ts files or noEmit.