如何在JSDoc中描述包含必选属性及其他未知属性的对象类型

实现方法 #

你可以通过JSDoc支持的索引签名语法满足需求，把???替换为[key: string]: any即可，该声明表示对象除了显式定义的属性外，还可以携带任意字符串键、任意类型的其他属性。

修改后的完整代码如下：

/**
 * @param {{bar: number, [key: string]: any}} foo
 * @return {{bar: number, [key: string]: any}} parameter `foo` with incremented property `bar`
 */
function fn(foo) {
    const { bar, ...rest } = foo
    console.log('bar', bar)
    console.log('other unknown properties', rest)

    foo.bar++
    return foo
}

注：原代码末尾return object属于笔误，这里修正为返回foo以匹配注释描述的返回值逻辑。

可选优化方案 #

如果你的项目支持TypeScript风格的JSDoc，还可以用泛型实现更灵活的类型复用：

• 先定义可扩展的通用类型
• 后续如果需要调整约束只需要修改公共类型定义即可

/**
 * 定义携带bar属性的通用对象类型
 * @template T
 * @typedef {{ bar: number } & T} FooWithBar
 */

/**
 * @template T extends Record<string, any>
 * @param {FooWithBar<T>} foo
 * @return {FooWithBar<T>} parameter `foo` with incremented property `bar`
 */
function fn(foo) {
    // 函数逻辑不变
}

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