[afavour]

I've found a happy medium to be annotating functions etc with JSDoc style comments but keeping interfaces etc. in a .d.ts file. The Typescript compiler is able to import it from a .js file just fine.

[eyelidlessness]

The one frustrating thing is that you can’t just use .d.ts files in a project to define the full types for their corresponding .js module, without importing each type def individually. And assigning imported type defs to classes is severely limited and confusing. It’s a shame, because the same structure/approach ~just works for packages installed under node_modules.

[syspec]

Agree, any complex types just get placed in their own `.d.ts` file, and import that into JSDoc comments

  /// Top of file usually
  /**
   * @typedef {import('./typedefs/MyThing')} MyThing
   */
  
  /// Later
  
  /**
   * @param {MyThing} x
   */
  function(x) {
    //
  }

[fenomas]

Worth noting that you can also do this from plain .js files.

    /** @param { import('./foo.js').SomeType } arg */
    function doThing(arg) {
        // ...
    }

The thing being imported can be a JS thing like an exported class, or a JSDoc type that's defined with @typedef.

[toastercat]

This is the way.