jsdoc : reference typedef-ed type from other module

Question

Assuming I have a typedef type in a js module

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

Is it possible to reference this type in another module, so that in the HTML page generated by jsdoc, the type is displayed as a link to the typedef-ed module ?

I tried variations of this, but nothing seems to work...

// somewhere_else/bar.js
/**
 * @module
 */
/**
 * @param {somewhere/foo/Foo} foo - some param
 */
export default function doStuff(foo) {
  ...
}

Answer 1

This works for me ...

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

and ...

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

Answer 2

The above answer shows up high in search results so I'm documenting what worked for me in case it helps someone in a similar situation.

I'm using Visual Studio code for a node project with // @ts-check on all my modules. Using the above syntax hiccups on the module: syntax. Also, the code assistance doesn't work properly. It took me a while but the answer ended up being quite simple

If I have the typedef myTypedef in a module myModule then in the second module where I require myModule
mm = require(myModule)
I can use something like
/** @param {mm.myTypedef} myParamName */

Answer 3

The module syntax is not supported by TypeScript so if you're getting here assuming it to work, I haven't been able to get the solutions above to work.

To get it working with TypeScript use Import Types

For the OP the way I would do it is

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

Then refer to it in the JS module as

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

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

You can verify things are working on an individual file more strictly by adding the following to the beginning of the file. This will enable typescript checking in Visual Studio code for the specific file to help prepare your move to Typescript in the future.

// @ts-check

Answer 4

Many libraries export types from their root file, to access those in typedefs, change your import to use the import * as format.

For example:

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


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