JSDoc import integration doesn't support return-style AMD modules

[peteruhnak]

TypeScript Version: 4.0.0-dev.20200508
also 3.8.3 (and presumably any other version)

Search Terms:
require, AMD, exports, import, JSDoc, module

Code

mod.js

// @ts-check

define(function () {
  // (1) this checks
  // exports.number = 12;

  // (2) this doesn't check
  // var exports = {
  //   number: 12
  // };
  // return exports;

  // (3) this also doesn't check
  return {
    number : 12
  }
});

usage.js

// @ts-check

define(function(require) {
  /** @type {import('mod')} */
  var Mod = require('mod');
  Mod.number;
});

My tsconfig is configured for JS/AMD/es5/noEmit:

    "allowJs": true,
    "module": "AMD",
    "target": "es5",
    "noEmit": true,

Expected behavior:

The import in the @type annotation in usage.js is correctly resolved for all three AMD module variants of mod.js .

Actual behavior:

Only the first variant, where number is explicitly added to exports works.
For the second and third variants, I get a compile error.

src/usage.js:4:23 - error TS2306: File 'd:/ns-prog/ts-jsdoc/src/mod.js' is not a module.

4     /** @type {import('mod')} */

Considering both (2) and (3) are valid AMD modules, I would expect this to work.

Note that JSDoc supports @exports annotation. Perhaps that could be utilized in the TypeScript-JSDoc integration?

Playground Link: N/A (I didn't see an option to have multiple files.)

Related Issues:
There's a StackOverflow question from 2016 https://stackoverflow.com/questions/37035462/importing-amd-modules-that-don-t-use-exports-with-typescript, but I didn't find any issue for it here.

[sandersn]

"module": "amd" is intended for emit, but together with "allowJs": true, we could use that as a signal to treat the return type of functions passed to define specially.

However, this is a completely new feature from the perspective of JS support -- it's not like existing support for module.exports= or even Object.defineProperty(module.exports, ... So the biggest question is how many people need this feature.

For a workaround, Typescript uses .d.ts files to specify the module exports instead of jsdoc @export tags.

[JHawkley]

Since you bring up @export, a request of mine is to allow TypeScript to pick up @export as a virtual module export, particularly when the module option in the project's jsconfig.json file is set to something uncommon or minimally supported, like "none". With this constraint, it could at least use these types for type-checking purposes. This could expose types for essentially any kind of non-standard module system out there.

My case in particular: I'm maintaining a large AngularJS 1.7 project that exclusively uses its odd pre-ES6 module system and we really want to get TypeScript to recognize types to make life easier for us, but we have not found any reliable scheme that allows TypeScript to pick up types defined from inside of a .directive or .controller call. Scoping prevents access to those types, and the JSDoc-standard typing syntax, which allows referencing these "hidden" types, is not supported (and doesn't look like it will ever see support).

Just being able to tag these things with @export and allowing TypeScript to pretend the file is a module in the context of type-checking and the import("./someJsFile").SomeExport syntax would really help out typing these kinds of unusual module systems.

This would give us:

• A way to expose types in almost any .js file without having to disassociate documentation into .d.ts files.
  • Would also probably appease some of us requesting support for JSDoc's @namespace and other "bandaid" features that don't align well with TypeScript's module-centric approach.
• Eliminate the need to replicate API structures that are already well-defined elsewhere.
• A smoother path toward switching to a proper module system, or even TypeScript-proper, at some point in the future.
• A clue for TypeScript as to the potential compilation order, when no /// <reference /> directive is present and TypeScript is tasked to emit (which is not my use case, but a gain nonetheless).

[peteruhnak]

As for the original report, I've managed to work around the issue by:

1. replacing all return statements with

  /** @type {Object<string,any>} */
  var exports = {};
  exports.thing = thing;
  return exports;

2. auto-generating a massive Requires.d.ts file for every single RequireJS module file extending the Require interface

interface Require {
  (module : 'a/b/module1'): typeof import('a/b/module1');
  (module : 'g/d/module-x'): typeof import('g/d/module-x');
  ...
  [... another ~2k modules ...]
  ...
}

It's not ideal, but it was the only way I've managed to make both TS happy and be able to use VSCode IntelliSense. I didn't observe any performance loss due to so many overloads.

However, this is a completely new feature from the perspective of JS support

Considering I've managed to work around this, and this would be a new feature, I think this can be closed. (Unless there's something in TS that can ease this process.)