Repository: TypeScript
Issue: Type checking and IntelliSense with JSDoc typed js dependencies
Labels: Suggestion,Awaiting More Feedback

## 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](https://gist.github.com/ahocevar/9a7253cb4712e8bf38d75d8ac898e36c) with a demo project that successfully uses a dependency ([ol@6.0.0-beta.1](https://www.npmjs.com/package/ol/v/6.0.0-beta.1) with [fully JSDoc typed sources](https://github.com/openlayers/openlayers/pull/9178). This works well to get IntelliSense in VS Code for projects authored in pure JavaScript, but requires a not very obvious [`jsconfig.json` configuration](https://gist.github.com/ahocevar/9a7253cb4712e8bf38d75d8ac898e36c#file-jsconfig-json). Similar configurations (with `tsconfig.json`) partially work with TypeScript projects, but are very [fragile](https://github.com/openlayers/openlayers/pull/9178#issuecomment-461577897) quite [easily](https://github.com/Toterbiber/OpenlayersAngularTest), especially in [more complex projects](https://github.com/openlayers/openlayers/pull/9178#issuecomment-461588832). 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](#7546), 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.
 1. 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](https://www.npmjs.com/package/ol/v/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
```js
{
  "compilerOptions": {
    "jsSources": [
      "src/**/*.js"
    ]
  }
}
```

## Checklist

My suggestion meets these guidelines:

* [x] This wouldn't be a breaking change in existing TypeScript/JavaScript code
* [x] This wouldn't change the runtime behavior of existing JavaScript code
* [x] This could be implemented without emitting different JS based on the types of the expressions
* [x] This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, etc.)
* [x] This feature would agree with the rest of [TypeScript's Design Goals](https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals).