如何通过JSDoc为JS类的条件属性配置正确的TypeScript类型？

你需要通过JSDoc泛型绑定+构造函数重载，让TypeScript根据传入的配置参数，自动识别ExampleClass实例是否包含property属性，具体实现如下：

1. 定义参数与实例的关联条件类型 #

先通过@typedef结合TypeScript条件类型，把配置参数和实例类型绑定：

/**
 * @template {ExampleOptions} T
 * @typedef {T extends {option: true} ? { property: boolean } : { property?: never }} ExampleInstance
 */

这个类型的逻辑是：如果传入的参数T包含option: true，实例就带必填的property；否则实例的property为可选且类型为never（等同于不存在）。

2. 给构造函数添加重载签名 #

用@overload定义两种调用场景，让TypeScript能根据传入参数匹配对应实例类型：

/**
 * @overload
 * @param {{option: true}} param
 * @returns {ExampleInstance<{option: true}>}
 */
/**
 * @overload
 * @param {Omit<ExampleOptions, 'option'> | undefined} param
 * @returns {ExampleInstance<Omit<ExampleOptions, 'option'>>}
 */
/**
 * A thing that does stuff
 * @constructor
 * @param {ExampleOptions} [param] Options you can use to configure the new instance
 */
function ExampleClass(param) {
    if (param?.option === true) {
        /** @type {boolean} */
        this.property = true;
    }
}

两个重载分别对应：

• 传入{option: true}时，返回带必填property的实例
• 不传参数或传不带option的对象时，返回property可选/不存在的实例

3. 修正原有配置类型定义 #

把ExampleOptions里的option类型调整为更准确的boolean | undefined：

/**
 * Settings you can use to configure an instance of an ExampleClass
 * @typedef {Object} ExampleOptions
 * @property {boolean} [option] Set to `true` to add `property` to the instance; omit or set to false to exclude it
 */

效果验证 #

• 当调用const inst1 = new ExampleClass({option: true})时，TypeScript会识别inst1.property为必填boolean，可直接使用无需检查
• 当调用const inst2 = new ExampleClass()或new ExampleClass({option: false})时，inst2.property会被标记为可选，编辑器会提示你访问前需先判断是否存在

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