vscode Using Typed Definitions in JavaScript Files

Question

VSCode Version: 1.20.0

First, what I think I know about Visual Studios Code IntelliSense:

1. The presence of a tsconfig.json/jsconfig.json should indicate to vscode that the directory is a TypeScript/JavaScript project (docs). This means that IntelliSense should be aware of all .js and .ts files in the directory (respecting the include and exclude config properties), and all classes/definitions exported by those files without having to explicitly reference them.
2. In any case, you can make IntelliSense aware of classes/definitions exported by a file by explicitly referencing said file. This can be done via require(), import, or /// <reference path="..." />.
3. You can mix TypeScript and JavaScript files.

Given these preconceptions, I can not get vscode to work as expected. See the simple example project below. The objective is to be able to use the Person class definition defined in test.d.ts typed definition TypeScript file in the test.js JavaScript file. However, IntelliSense complains that it is unaware of the Person class:

Note that IntelliSense works with packages that have been npm install-ed.

Given assumption #1, simply including the tsconfig.json file should be all I need. Even so, I also tried explicitly listing typings/test.d.ts and test.js in includes. I also tried listing typings in compilerOptions.typeRoots.

Given assumption #2, including a triple-slash reference directive in test.js to ./typings/test.d.ts should work.

There is a lot of outdated information out there because vscode has changed the way it handles configurations, typings, etc. I have read everything I could find but I can't get it to work.

Any ideas? What am I missing here?

---

tsconfig.json

{
  "compilerOptions": {
    "module": "commonjs",
    "target": "es6",
    "lib": ["es6"],
    "allowJs": true,
    "checkJs": true
  },
  "exclude": [
    "node_modules"
  ]
}

---

test.js

/// <reference path="./typings/index.d.ts" />

/** @type {Person} */
const p = {};

---

typings/test.d.ts

export class Person {
  name: string;
  age: number;
}

Answer 1

As of the May 2018 (v1.24) release of VSCode, the TypeScript version was updated to 2.9 which includes the ability to import() types.

• VSCode May 2018 (v1.24) release notes
• TypeScript v2.9 announcement

This means we can also use import() in JSDocs like so:

/** @type {import('./typings/test').Person} */
const p = {};

and/or

/** @typedef {import('./typings/test').Person} Person */

/** @type {Person} */
const p = {};

This also allows us to reference types defined in other JavaScript files even if they are not exported. No tsconfig.json or any other configuration file required and no need to use TypeScript files. Full example:

---

func1.js

/**
 * @typedef MyStruct
 * @property {string} fu
 * @property {number} bar
 */

module.exports = function func1() {
  // ...
}

---

func2.js

/**
 * @param {import('./func1').MyStruct} options 
 */
module.exports = function func2(options) {
  // ...
  // IntelliSense definition for this function:
  // func2(options: MyStruct): void
}

---

You can also reference types from node modules:

/** @type {import('async').AsyncCargo} */

Note: I did find a possible bug. If the file you import() does not export anything, intellisense breaks.