如何使用JSDoc标注入参出参结构一致但部分属性类型不同的函数

你只需修改makeSomeThings的JSDoc模板与返回值定义即可，核心逻辑是用类型映射保留thingsA、thingsB的原有键名，同时将值类型修改为CoolThing，其余入参字段保持原类型不变。

修改后的完整代码 #

class CoolThing {
  constructor (id, settings) { }

  happyLittleMethod () { /* do something */ }
}

/**
 * 该函数返回的对象结构与入参完全一致，仅thingsA、thingsB的属性值会转换为CoolThing实例
 * @template {{thingsA?: Record<string, any>, thingsB?: Record<string, any>}} T
 * @param {T} ABThingsAndStuff 入参对象，可包含thingsA、thingsB及其他自定义字段
 * @returns {Omit<T, 'thingsA' | 'thingsB'> & {
 *  thingsA: Record<keyof T['thingsA'], CoolThing>,
 *  thingsB: Record<keyof T['thingsB'], CoolThing>
 * }}
 */
function makeSomeThings ({ thingsA, thingsB, ...otherStuff }) {
  const a = {}
  const b = {}

  for (let key in thingsA) {
    a[key] = new CoolThing(key, thingsA[key])
  }

  for (let key in thingsB) {
    b[key] = new CoolThing(key, thingsB[key])
  }

  return { thingsA: a, thingsB: b, ...otherStuff }
}

类型说明 #

1. 原来的写法直接将返回值标注为T，等于告诉编辑器返回值和入参类型完全一致，自然识别不到thingsA、thingsB内部属性的类型变化
2. @template后增加的约束，保证入参的格式符合函数处理要求
3. 返回值用&拼接两部分类型：
   • Omit<T, 'thingsA' | 'thingsB'>：保留入参除thingsA、thingsB外的所有字段的原有类型
   • 重新定义的thingsA、thingsB：通过keyof T['thingsA']保留原有键名，值的类型统一设置为CoolThing

修改完成后，调用myThings.thingsA.cat.happyLittleMethod()时，编辑器就会正确识别cat是CoolThing实例，自动补全happyLittleMethod方法，其余自定义字段（比如示例中的worldName）也会保留原有类型的补全提示。

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