如何在返回对象的原生JS构造函数中使用JSDoc与ts-check

当构造函数通过返回自定义对象而非this创建实例时，TypeScript的类型检查默认会沿用构造函数的this类型推断，导致无法识别返回对象的属性。要解决这个问题，需要明确标注构造函数的返回类型，具体步骤如下：

1. 定义实例的类型结构 #

用@typedef明确声明返回对象的属性和方法类型，确保TypeScript能识别实例的完整结构：

/**
 * @typedef {Object} PeepInstance
 * @property {string} firstName
 * @property {string} lastName
 * @property {() => string} innerSayHello
 */

2. 为构造函数标注返回类型 #

在构造函数的JSDoc中，用@returns指定返回的是刚才定义的PeepInstance类型，同时用@constructor标识这是一个构造函数：

//@ts-check

/**
 * 创建Peep实例的构造函数，返回自定义对象而非this
 * @constructor
 * @param {string} firstName
 * @param {string} lastName
 * @returns {PeepInstance}
 */
function Peep(firstName, lastName) {
  const fullName = `${firstName} ${lastName}`;
  const innerSayHello = () => `Hello, I'm ${fullName}`;

  return {
    firstName,
    lastName,
    innerSayHello
  };
}

3. 验证类型检查 #

此时创建实例并访问属性，VSCode的//@ts-check会正确识别类型，不会再报错：

const peep = new Peep('John', 'Doe');
console.log(peep.firstName); // 类型识别正常
console.log(peep.innerSayHello()); // 方法调用类型检查正常

关键说明 #

• 常规构造函数通过this挂载属性，TypeScript能自动推断实例类型；但返回自定义对象时，必须显式标注返回类型，覆盖默认的this类型推断。
• @typedef定义的类型要和返回对象的结构完全匹配，包括属性名、类型和方法签名。

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