如何让JSDoc根据可选参数推断泛型高阶函数的返回类型

问题原因 #

你当前的写法中泛型U没有设置默认类型，当不传入mapper参数时，类型系统没有足够的入参信息推导U的实际类型，因此会将返回值降级为any类型，和你设置的默认参数逻辑没有自动关联。

解决方案 #

有两种常用的实现方式，都可以满足你的类型推断需求：

方式1：给泛型设置默认值（写法更简洁）

给泛型U指定默认类型为T，和你默认恒等函数的逻辑对齐即可：

/**
 * @template T
 * @template [U=T]
 * @param { T } item
 * @param { function(T): U } [mapper = t => t]
 * @returns { U }
 */
function map(item, mapper = t => t) {
  return mapper(item);
}

修改后测试：

• const one = map('123', parseInt) 会被正确推断为number类型
• const two = map('123') 会被正确推断为string类型

方式2：使用函数重载（兼容性更好）

如果你的类型检查工具对泛型默认值支持不好，可以用JSDoc的重载写法明确两种调用场景的类型：

/**
 * @template T
 * @overload
 * @param {T} item
 * @returns {T}
 */
/**
 * @template T
 * @template U
 * @overload
 * @param {T} item
 * @param {function(T): U} mapper
 * @returns {U}
 */
/**
 * @param {any} item
 * @param {function(any): any} [mapper = t => t]
 */
function map(item, mapper = t => t) {
  return mapper(item);
}

两种方式都不需要额外的配置，只要你的编辑器/类型检查工具支持标准JSDoc语法即可生效。

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