JSDoc is this how you mark a @typedef as @global?

Question

Just making sure that this in a module in our Node server is the right way to be able to use an @typedef throughout the application instead of repeating it in every module/file it is needed. From the docs I can't determine if this is correct or not, and does anyone have an opinion on where to store global @typedefs so they are easy to find if they need to be changed when used throughout the application.

/**
 * Universally unique identifier.
 * @global
 * @typedef {string} UUID
 */

Pearl

Did you ever determine if this was correct? – Aggressor

No, but I ended up using it anyway since the code needed documentation, and this was how the docs appeared to steer its usage. Even now no one has changed it so my team doesn't have any better idea of the proper use, but it feels like it provides clarity, and is easy to determine the intent, which might be enough. – Pearl

Thanks for the quick response. Guess I'll use it too! Hopefully we can get an "official" answer to this someday - I just scoured the @global and @typedef docs again + Google to no avail :( – Aggressor

Answer 1

A bit of a late answer here, but I came across this issue from Google, so this is how I solved this issue for myself. Hopefully it helps future people!

I ran into a similar situation where I had a typedef in a module and wanted to use that type elsewhere in the application, without redefining the type.

I went with something like this:

myModule.js
/**
 * Universally unique identifier.
 * @typedef {string} UUID
 */

myOtherScript.js

/**
 * @function
 * @param {import('path/to/myModule.js').UUID} uuid
 */
function getByUUID(uuid) { ... }

This doesn't make the typedef strictly global, so you cannot do @param {UUID} uuid (which would be cleaner, however I've yet to find a way to achieve this) but this approach worked for my use-case, and definitely is better than rewriting the type everywhere it is used.

More info around this topic can be found in this Github issue.

Eoin