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?

Answer 1

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.