如何为TypeScript泛型函数编写JSDoc：实例类型返回问题

我完全理解你的需求——你希望调用checkTop(Derived)时返回Derived实例类型，而不是typeof Derived（类构造函数类型），调用checkTop(Derived2)时同理。下面分别提供JSDoc优先方案和TypeScript原生方案：

一、JSDoc解决方案（优先推荐） #

你可以借助TypeScript提供的InstanceType<T>工具类型，它能从类构造函数类型T中提取对应的实例类型。修改后的checkTop函数JSDoc标注如下：

class Base { static get type() { return 'Base'; } }
class Derived extends Base { }
class Derived2 extends Base { }

/** @type {Base} */
var t = new Derived(); // 可随时切换为Derived2实例

/**
 * @template {typeof Base} T
 * @param {T} cl - 要检查的Base子类构造函数
 * @returns {InstanceType<T> | undefined} - 匹配则返回对应实例，否则返回undefined
 */
function checkTop(cl) {
  if (t instanceof cl) {
    return t;
  }
  return undefined;
}

// 调用示例：
const derivedResult = checkTop(Derived);
// 此时derivedResult的类型为 Derived | undefined
const derived2Result = checkTop(Derived2);
// 此时derived2Result的类型为 Derived2 | undefined

注意事项： #

• 确保你的编辑器（比如VSCode）开启了JavaScript的TypeScript类型检查功能：在设置中开启javascript.implicitProjectConfig.checkJs，这样JSDoc的类型标注才能生效。
• InstanceType<T>是TypeScript内置的工具类型，专门用于从构造函数类型获取实例类型，完全适配你的场景。

二、TypeScript原生方案 #

如果直接使用TypeScript编写代码，类型标注会更简洁直观，不需要依赖JSDoc：

class Base { static get type() { return 'Base'; } }
class Derived extends Base { }
class Derived2 extends Base { }

let t: Base = new Derived(); // 可随时切换为Derived2实例

function checkTop<T extends typeof Base>(cl: T): InstanceType<T> | undefined {
  if (t instanceof cl) {
    // 这里需要类型断言，因为TS无法自动推断t的具体实例类型
    return t as InstanceType<T>;
  }
  return undefined;
}

// 调用示例：
const derivedResult = checkTop(Derived);
// derivedResult类型自动推导为 Derived | undefined
const derived2Result = checkTop(Derived2);
// derived2Result类型自动推导为 Derived2 | undefined

扩展：用类型谓词做类型收窄 #

如果你希望直接通过函数调用收窄t的类型，而不是返回实例，可以用类型谓词写法（JSDoc和TS都支持）：

JSDoc版本：

/**
 * @template {typeof Base} T
 * @param {T} cl
 * @returns {t is InstanceType<T>}
 */
function checkTop(cl) {
  return t instanceof cl;
}

// 使用时：
if (checkTop(Derived)) {
  // 这里t的类型自动收窄为Derived
  console.log(t); // 类型为Derived
}

TypeScript版本：

function checkTop<T extends typeof Base>(cl: T): t is InstanceType<T> {
  return t instanceof cl;
}

// 使用时：
if (checkTop(Derived)) {
  t; // 类型自动收窄为Derived
}

内容的提问来源于stack exchange，提问作者Vincent