Return type annotations ignored with recursive closures using JSDoc

TypeScript Version: 3.5.1

Search Terms:

• "implicit any type"
• "circular reference"
• "jsdoc"
• "recursive"
• "closure"

Code

I have a fairly complex use case in a project which uses vanilla JS with type annotations in JSDoc comments. The long and the short is that there is a function which returns a function, which may recursively call itself and will reassign some closure variables.

Here is a silly example which gets the point across and demonstrates the same issue:

/**
 * @returns {function(): number}
 */
function circular() {
  let rand = Math.random();

  return /** @type {function(): number} */ (function tryAgain() {
    if (rand < 0.5) {
      return rand;
    }

    rand = Math.random();
    return tryAgain();
  });
}

Expected behavior:

TypeScript should know that the return type of tryAgain is a number.

Actual behavior:

When run with:

tsc --allowJs --checkJs --noEmit --strict --target ES2017 *.js

The following error is thrown:

error TS7023: 'tryAgain' implicitly has return type 'any' because it does not have a return type annotation and is referenced directly or indirectly in one of its return expressions.

At the very least, this error seems pretty erroneous. The tryAgain function has two return type annotations (I have tried both styles in an attempt to fix this). The larger issue is that I need some way to get TypeScript to compile this code without a massive refactor.

Playground Link:

None (code is JavaScript).

Related Issues:

This has a circular reference similar to #26623. However for that issue the solution was to add an explicit return type annotation. In my case (perhaps because I am using JSDoc), TypeScript seems to be ignoring all explicit annotations.

Start by reproducing the provided recursive JavaScript example with tsc --allowJs --checkJs --noEmit --strict --target ES2017 *.js and confirm TS7023. Trace how JSDoc return annotations are handled for recursive closures, then verify that the example compiles without the implicit-any error and preserves the expected number return type.