为既有的 JavaScript 库编写声明文件时应如何还原其真实接口

# 核心结论

为既有的 JavaScript 库编写声明文件，本质上是对已经存在的运行时契约进行逆向建模，而不是重新设计一套更理想的接口。应先确认消费者实际如何加载模块，再还原导出值是否可调用、可构造，是否具有静态成员、实例成员、事件、回调或链式调用等能力。声明不仅要让正确示例通过类型检查，还必须拒绝运行时不支持的调用，并尽量保留输入、输出及不同参数之间的类型关联。

# 底层机制

TypeScript 的值空间、类型空间和命名空间空间彼此相关但并不等同。接口只能描述类型形状，不能凭空创建运行时导出。因此，若模块实际导出一个函数，就不能仅声明一个同名接口；若导出对象既能调用又有属性，可使用调用签名，或通过函数声明与同