JSDoc typedef in a separate file

Question

Can I define all custom types in a separate file (e.g. types.jsdoc), so that they can be reused throughout the application? What's the right way to do it?

/**
 * 2d coordinates.
 * @typedef {Object} Coordinates
 * @property {Number} x - Coordinate x.
 * @property {Number} y - Coordinate y.
 */

Answer 1

I just tried with VSCode and it works only if the separate file is opened in the editor. If not, external typedefs are typed as any

Answer 2

You can define types in a module (eg. typedefs.js). The module contains your JSDoc typdefs and can simply export an unused property.

// typedefs.js
/**
 * @typdef foo
 * @property {string} bar
 */

// etc.

exports.unused = {};

To use it, import the module where you need to reference these typdefs:

const typedefs = require("./typedefs");
/** @type {typedefs.foo} */
const fb = { bar: "hello" };

You may wish to annotate typedefs.js as a @module or @namespace. Because I'm using "tsd-jsdoc" to generate a types.d.ts file, and due to the way TypeScript now interprets modules vs. namespaces, I've annotated my typedefs.js file as a @namespace and documented each typedef as a member of that namespace:

/**
 * @namespace typedefs
 */

/**
 * @typedef foo
 * @property {string} bar
 * @memberof typdefs
 */

Hope that helps.

Answer 3

I usually do something similar in my projects, the difference being I use the extension .js to name the file. Webstorm works perfectly and is able to check types and auto-complete just fine. It won't recognize the .jsdoc extension (I just checked), so stick to .js even if the file doesn't contain any code statement.