TS2304 when a generic (@template) function JSDoc contains @overload

[antichris]

Generic functions that have an @overload in their JSDoc produce TS2304: Cannot find name 'T' errors.

In const assignments this applies only to the base params (the params in all the overloads are fine). In function definitions this applies to all params except those of the first overload.

CHANGES.md does not address this new "feature".

Steps to reproduce

const createElementC = /**
	 * @template {keyof HTMLElementTagNameMap} T
	 * @param {T}t
	 * @param {NodeList|HTMLCollection=}c
	 *
	 * @overload
	 * @param {T}t
	 * @return {HTMLElementTagNameMap[T]}
	 *
	 * @overload
	 * @param {T}t
	 * @param {NodeList|HTMLCollection}c
	 * @return {HTMLElementTagNameMap[T]}
	 */(t, c) => {
		/* ... omitted for brevity ... */ return document.createElement(t)
	}

/**
 * @template {keyof HTMLElementTagNameMap} T
 * @param {T}t
 * @param {NodeList|HTMLCollection=}c
 *
 * @overload
 * @param {T}t
 * @return {HTMLElementTagNameMap[T]}
 *
 * @overload
 * @param {T}t
 * @param {NodeList|HTMLCollection}c
 * @return {HTMLElementTagNameMap[T]}
 */
function createElementF(t, c) {
	/* ... omitted for brevity ... */ return document.createElement(t)
}

The real use case is, of course, far more complex than the repro above.

Behavior with typescript@6.0

tsc --checkJs --strict --noEmit index.js

No output, no errors.

Behavior with tsgo

tsgo --checkJs --strict --noEmit index.js

index.js:5:13 - error TS2304: Cannot find name 'T'.

5   * @param {T}t
              ~

index.js:22:12 - error TS2304: Cannot find name 'T'.

22  * @param {T}t
              ~

index.js:30:12 - error TS2304: Cannot find name 'T'.

30  * @param {T}t
              ~

index.js:32:35 - error TS2304: Cannot find name 'T'.

32  * @return {HTMLElementTagNameMap[T]}
                                     ~

index.js:32:35 - error TS2538: Type 'T' cannot be used as an index type.

32  * @return {HTMLElementTagNameMap[T]}
                                     ~


Found 5 errors in the same file, starting at: index.js:5

[ahejlsberg]

There are a couple of issues here. First issue is we're not correctly finding the @template tags that apply to @overload declarations. That's a fairly simple fix. Second issue, however, is more complicated. TS6 supports JSDoc @overload declarations for arrow functions and function expressions, even though there is no equivalent for that in TypeScript itself (in fact, there's an open issue suggesting the feature). Since TS7 aligns our JSDoc features more closely with TypeScript (we now re-parse JSDoc constructs into synthetic TypeScript constructs), we aren't really equipped to support arrow function overloading without first implementing it as a TypeScript feature.

I will put up a PR that fixes the first issue and documents the second issue in CHANGES.md.

[antichris]

we aren't really equipped to support arrow function overloading without first implementing it as a TypeScript feature.

How sad. I prefer arrow functions over function declarations, since there is zero new insight that the extra 8 letters of the function keyword can provide about the code, it's only the parameters and the body that ever matter. Now I'll have to rewrite all my overloaded arrow ones to declarations to be compatible with TS7.

Regardless, thank you for addressing this!

[ahejlsberg]

@antichris Actually, thinking about it a bit more, there's a reasonable translation to TypeScript that we can use. When you write:

/**
 * @overload
 * @param {string} x
 * @returns {string}
 * @overload
 * @param {number} x
 * @returns {number}
 * @param {string | number} x
 * @returns {any}
 */
let f = x => x;

We can turn it into:

let f: { (x: string): string; (x: number): number } = (x: string | number): any => x;

The only difference from Strada would be that we actually check the assignment. Strada currently doesn't do any validation that overloads and implementation signatures are compatible.

I will include this translation in the PR I'm putting up. Will save you rewriting all of your overloaded arrows!

[ahejlsberg]

I may have been a bit too optimistic about a solution. The following already works in both Strada and Corsa:

/**
 * @type {{ (x: string): string; (x: number): number }}
 * @param {string | number} x
 * @returns {any}
 */
const f1 = x => x;

It works because the @type annotation applies to f1 and the @param and @return tags apply to the arrow function expression. We could potentially support turning @overload tags into the equivalent of a @type annotation as I suggested in my previous comment. However, that still won't resolve the issue as reported because the original example has the JSDoc comment on the arrow function, not the variable declaration. There is no translation of that that gives us the same semantics as Strada.

I'm thinking it may be best to be conservative here and simply recommend writing the above to implement overloads with arrow functions in a manner that works with both Strada and Corsa.