При использовании TypeScript для проверки JS через JSDocs, как объявить, что переменная соответствует пространству имен?

Question

В моем коде JS я импортирую модуль следующим образом:

const toolbox = require('../toolbox')

/**
 * @param {toolbox.Hammer} hammer
 */
function useHammer(hammer) {
  let nail = new toolbox.Nail()
  hammer.ham(nail)
}

Теперь, потому что мой файл tools/index.d.ts экспортирует toolbox как пространство имен. Моя IDE может видеть, что hammer имеет метод ham. Потрясающие! Но он не видит, что в toolbox есть член Nail.

Я попытался поместить теги @module и @export в toolbox/index.js, но безрезультатно. Я также попытался поместить @type {toolbox} поверх оператора require, но мне сказали, что toolbox is referenced directly or indirectly in its own type annotation.

Как я могу сообщить своей IDE, что toolbox = require('toolbox') делает toolbox соответствующим моему namespace?

---

Пример toolbox/index.js и toolbox/index.d.ts для справки:

exports.Hammer = class {
  ham (nail) {
    if (Math.random() > 0.1) {
      exports.nailCount -= 1
      return 'bang!' 
    } else return 'Ouch my thumb!'
  }
}
exports.nailCount = 100
exports.Nail = class {}

export = toolbox
export as namespace toolbox

declare namespace toolbox {
  class Nail {}
  class Hammer {
    ham(n: Nail) : string
  }
}

и мой tsconfig для хорошей меры (так как это маленькая машина go -культура)

{
  "compilerOptions": {
    "allowJs": true,
    "target": "es5",
    "checkJs": true,
    "baseUrl": "../",
    "moduleResolution": "node",
    "noEmit": true
  }
}

Answer 1

Какую IDE вы используете?

В VS Code я вижу, что Nail и nailCount отображаются как часть набора инструментов.

См. это изображение:

Кроме того, чтобы функция hammer.ham принимала только экземпляр Nail, добавьте некоторое свойство к определению класса Nail в index.d.ts Например

// toolbox/index.d.ts

export = toolbox;
export as namespace toolbox;

declare namespace toolbox {
  class Nail {
    length: string; // new property added
  }
  class Hammer {
    ham(n: Nail): string;
  }
}

Теперь, в main/index.js мы получим ошибку, если передадим что-то, кроме Nail экземпляра. например,

const toolbox = require("../toolbox");

/**
 * @param {toolbox.Hammer} hammer
 */
function useHammer(hammer) {
  let nail = new toolbox.Nail();
  hammer.ham("nail-string"); // this will show a red squiggle under "nail-string" since it is a string and the compiler expected a Nail instance
}

см. это изображение: