jsdoc: ссылка на тип typedef из другого модуля

Это работает для меня...

// somewhere/foo.js
/**
 * @module foo
 */
/**
 * @typedef module:foo.Foo
 * @type {object}
 * @property {string} bar - some property
 */

а также ...

// somewhere_else/bar.js
/// <reference path="foo.js" />
/**
 * @module bar
 */
/**
 * @param {module:foo.Foo} foo - some param
 */
function doStuff(foo) {
  //...
};

Приведенный выше ответ отображается высоко в результатах поиска, поэтому я документирую то, что сработало для меня, на случай, если это поможет кому-то в подобной ситуации.

Я использую код Visual Studio для проекта узла с // @ts-check на всех моих модулях. Использование приведенного выше синтаксиса вызывает сбои в синтаксисе module:. Кроме того, помощь по коду не работает должным образом. Мне потребовалось некоторое время, но ответ оказался довольно простым

Если у меня есть typedef myTypedef в модуле myModule, то во втором модуле, где мне требуется myModule
mm = require(myModule)
, я могу использовать что-то вроде
/** @param {mm.myTypedef} myParamName */

Многие библиотеки экспортируют типы из своего корневого файла, чтобы получить доступ к ним в typedefs, измените свой импорт, чтобы использовать формат import * as.

Например:

import * as testingLibrary from '@testing-library/react';


/** 
 * @returns {testingLibrary.RenderResult}
 */
export function myCustomRender() { }

Я пробовал оба вышеуказанных подхода.

Во-первых, в случае @typedef module:foo.Foo VSCode рассматривал использование Foo в том же файле, что и any. Что я не нашел приемлемым.

Во-вторых, при использовании импорта ES6 возникает следующая проблема:

import foo from 'foo'

/** @param {foo.Foo} a - Error Foo does not exist on foo */ 

С другой стороны, VSCode распознает import { Foo } from 'foo' без даже использования синтаксиса модуля JSDoc:

/**
 * @module bar
 */

Более того, я также смог сослаться на свойство импортированного типа, а именно:

import { Foo } from 'foo'

/** @param {Foo['bar']} bar */

Примечание

Этот проект использует Babel и предполагает, что компиляция кода, использующего импорт типов, невозможна без транспилятора.

Я работаю со скриптом vscode-powertools, который обеспечивает доступ в модуль vscode во время выполнения (в отличие от быть доступным для VSCode во время редактирования через локальный node_modules).

Если бы я попытался импортировать типы с помощью обычного jsdoc import

//@ts-check
/** @typedef {import('c:/Users/USERNAME/.vscode/extensions/ego-digital.vscode-powertools-0.64.0/node_modules/vscode').TextEditor} TextEditor */

Я бы получил ошибку File is not a module:

File 'C:/Users/USERNAME/.vscode/extensions/ego-digital.vscode-powertools-0.64.0/node_modules/vscode/vscode.d.ts' is not a module. ts(2306)

Итак, вот трюк, который я использую для проверки типов такого сценария:

//@ts-check
/// <reference types="c:/Users/USERNAME/.vscode/extensions/ego-digital.vscode-powertools-0.64.0/node_modules/vscode" /> 

// Allows us to reference the `vscode` module with jsdoc `@type`
async function vscodeⁱ() {if (1 == 1) return null; return import ('vscode')}

exports.execute = async (args) => {
  // Allows us to reference the `vscode` module with jsdoc `@type`
  const vscode = await vscodeⁱ()

  /** @type {vscode} */
  const vs = args.require ('vscode')

  // NB: The following code is fully typed in VSCode
  const windowᵛ = vs.window
  const editorᵛ = windowᵛ.activeTextEditor
  const start = editorᵛ.selection.start
}

Синтаксис module не поддерживается TypeScript, поэтому, если вы пришли сюда, предполагая, что он работает, я не смог заставить работать приведенные выше решения.

Чтобы заставить его работать с TypeScript, используйте Import Types

Для ОП я бы сделал так:

// foo.d.ts
export type Foo = {
  /**
   * some property
   */
  bar: string,
};

Затем обратитесь к нему в модуле JS как

/**
 * @typedef { import("./foo").Foo } Foo
 */

/**
 * @param {Foo} foo - some param
 */
export default function doStuff(foo) {
  ...
}

Вы можете более строго убедиться, что все работает с отдельным файлом, добавив следующее в начало файла. Это включит проверку машинописного текста в коде Visual Studio для определенного файла, чтобы помочь подготовиться к переходу на Typescript в будущем.

// @ts-check