如何在JSDoc中引用变量实现动态返回值的智能提示？

问题场景 #

现有如下JavaScript函数，调用时传入字符串参数，返回以该字符串为键和值的对象：

function wrapInObject(key){
  const result = { [key]: key }
  return result
}

调用代码示例：

const a = wrapInObject("Yellow")
a.Yel.. // 希望编辑器能智能补全出"Yellow"键名

需求是让编辑器根据传入的参数值，动态提供返回对象的键名提示，且不希望硬编码具体的键值，支持任意字符串输入的场景。

之前尝试的JSDoc写法无法实现动态提示，卡在返回值类型定义上：

/**
 * @param {string} key - 用于包装到对象中的字符串
 * @returns { ??? }
*/
function wrapInObject(key){
  const result = { [key]: key }
  return result
}

解决方案 #

需要结合JSDoc的泛型和TypeScript的Record类型来实现动态类型推断，具体写法如下：

/**
 * @template {string} T
 * @param {T} key - 用于包装到对象中的字符串
 * @returns {Record<T, T>}
*/
function wrapInObject(key){
  const result = { [key]: key }
  return result
}

代码说明 #

• @template {string} T：声明一个泛型T，并约束其为字符串类型，确保参数只能传入字符串。
• @param {T} key：指定参数key的类型为泛型T，让编辑器能捕获传入的具体字符串值。
• @returns {Record<T, T>}：Record<K, V>是TypeScript的工具类型，用来定义一个以K为键类型、V为值类型的对象。这里用泛型T同时作为键和值的类型，让编辑器能根据传入的具体key值，推断出返回对象的键名，从而提供智能补全提示。

这样当你调用wrapInObject("Yellow")时，编辑器会自动识别返回对象的键是Yellow，输入a.Yel就能触发补全。

内容的提问来源于stack exchange，提问作者Islam Y-