Incorrect static method overload inheritance between TypeScript and JavaScript with JSDoc

🔎 Search Terms

Static method overload, inheritance, JSDoc, static method TypeScript, class inheritance, overload error, static side incompatible.

🕗 Version & Regression Information

TypeScript Version: 5.6.3

Problem

When using JSDoc in JavaScript as a substitute for TypeScript, the behavior of static method overloads in derived classes should match TypeScript.

⏯ Playground Link

https://www.typescriptlang.org/play/?#code/MYGwhgzhAEBqCmwAuB7ATgRmgbwFAEgIkwkBLYaAbQCIBqagXQAoA3RVNALmgCV4wAJigB2IAJ4AeBMnQYAfABpoEYGHBdowgK4BbAEbw0ASm7SOGANwEiJclTqMmAM1Joi3PoJHip7WYuVEEQEPfiFRSTN-Ezg-TCtCYjIKGnpmMDQAcwxQrwjfGUwAjMyAJlzwnyii6AAfTV0DY1M4rDx8fAB6TugASR0ABxB4HXhhJNIRAnw0eCQtNGFNeAB3WMKMJiMEgF8CAA9ubX1DaABeaAAGKz3cUEgYatLoeH2kMYFH1pxrCZSHZhsQoVbyROKlAIqNQZI6NQwxJ4JGzJexpZyudy8MKggocCFKCBBYQhLF5KqtOQI8FIv6oxwuNxIEH5J6QokkzyVMGFCFUnk02z-NElHKkrm49D46AlcpinGsupylkUxXHJp8vE-DrdPqDYajca2KYdWbzRbLNZPLa7AhiWEnNDnK43XBAA

💻 Code

The following TypeScript code works as expected:

class Vector1 { 
	static ["+"](vector: Readonly<Vector1>, scalar: number): Vector1; 
	static ["+"](first: Readonly<Vector1>, second: Readonly<Vector1>): Vector1; 
	static ["+"](arg1: Readonly<Vector1>, arg2: Readonly<Vector1> | number): Vector1 { 
		// Implementation 
		return new Vector1(); 
	} 
	x: number; 
} 
 
class Vector2 extends Vector1 { 
	static ["+"](vector: Readonly<Vector2>, scalar: number): Vector2; 
	static ["+"](first: Readonly<Vector2>, second: Readonly<Vector1>): Vector2; 
	static ["+"](first: Readonly<Vector2>, second: Readonly<Vector2>): Vector2; 
	static ["+"](arg1: Readonly<Vector2>, arg2: Readonly<Vector2> | Readonly<Vector1> | number): Vector2 { 
		// Implementation 
		return new Vector2(); 
	} 
	y: number; 
}

However, translating this to JavaScript using JSDoc gives an error:

class Vector1 {
	/**
	 * @overload
	 * @param {Readonly<Vector1>} vector 
	 * @param {number} scalar 
	 * @returns {Vector1}
	 */
	/**
	 * @overload
	 * @param {Readonly<Vector1>} first 
	 * @param {Readonly<Vector1>} second 
	 * @returns {Vector1}
	 */
	/**
	 * @param {Readonly<Vector1>} arg1 
	 * @param {Readonly<Vector1> | number} arg2 
	 * @returns {Vector1}
	 */
	static ["+"](arg1, arg2) {
		// Implementation
		return new Vector1();
	}
	/** @type {number} */
	x;
}

class Vector2 extends Vector1 {
	/**
	 * @overload
	 * @param {Readonly<Vector2>} vector 
	 * @param {number} scalar 
	 * @returns {Vector2}
	 */
	/**
	 * @overload
	 * @param {Readonly<Vector2>} first 
	 * @param {Readonly<Vector1>} second 
	 * @returns {Vector2}
	 */
	/**
	 * @overload
	 * @param {Readonly<Vector2>} first 
	 * @param {Readonly<Vector2>} second 
	 * @returns {Vector2}
	 */
	/**
	 * @override
	 * @param {Readonly<Vector2>} arg1 
	 * @param {Readonly<Vector2> | Readonly<Vector1> | number} arg2 
	 * @returns {Vector2}
	 */
	static ["+"](arg1, arg2) {
		// Implementation
		return new Vector2();
	}
	/** @type {number} */
	y;
}

🙁 Actual behavior

The code errors out:

Class static side 'typeof Vector2' incorrectly extends base class static side 'typeof Vector1'.

Types of property '["+"]' are incompatible.

Type '{ (vector: Readonly, scalar: number): Vector2; (first: Readonly, second: Readonly): Vector2; (first: Readonly<...>, second: Readonly<...>): Vector2; }' is not assignable to type '{ (vector: Readonly, scalar: number): Vector1; (first: Readonly, second: Readonly): Vector1; }'.

Types of parameters 'vector' and 'vector' are incompatible.

Property 'y' is missing in type 'Readonly' but required in type 'Readonly'.ts(2417)

🙂 Expected behavior

The code should pass the type check.

Additional information about the issue

This issue occurs when the strictFunctionTypes compiler option is enabled (set to true). Disabling this option makes the error disappear, but this shouldn't be required for static method overload inheritance to work correctly.

Start by reproducing the static overload inheritance case in the linked TypeScript Playground with strictFunctionTypes enabled, then trace the compiler's static-side compatibility checking for the Vector1 and Vector2 classes. Done means the JSDoc JavaScript version type-checks consistently with the equivalent TypeScript version without disabling strictFunctionTypes.