TypeScript映射类型下如何保留d.ts中的属性注释？

针对你遇到的TS 5.0.4中使用映射类型时，d.ts文件丢失对象属性注释的问题，这里有几个可行的解决方案：

方案1：使用satisfies关键字（推荐，TS 4.9+支持） #

把传入getInstance的对象先赋值给一个变量，用satisfies确保它符合函数参数的类型要求，这样TS会保留变量的注释并传递到最终的类型输出中：

type SomeType<T> = {
  field: T;
};

const getInstance = <T>(
  value: T
): SomeType<{
  [K in keyof T]: T[K];
}> => {
  return {
    field: value,
  };
};

// 先定义带注释的配置变量，用satisfies约束类型
const config = {
  /**
   * want to have it in d.ts
   */
  nested: "nested",
} satisfies Parameters<typeof getInstance>[0];

export const variable = getInstance(config);

编译后生成的d.ts会保留nested的注释：

type SomeType<T> = {
    field: T;
};
export declare const variable: SomeType<{
    /**
     * want to have it in d.ts
     */
    nested: string;
}>;
export {};

方案2：显式标注传入对象的类型 #

如果你的配置结构是固定的，可以提前定义带注释的类型，再用类型断言把传入对象关联到这个类型上：

type SomeType<T> = {
  field: T;
};

// 提前定义带注释的配置类型
type Config = {
  /**
   * want to have it in d.ts
   */
  nested: string;
};

const getInstance = <T>(
  value: T
): SomeType<{
  [K in keyof T]: T[K];
}> => {
  return {
    field: value,
  };
};

export const variable = getInstance({
  nested: "nested",
} as Config);

这种方式下，d.ts会把Config类型的注释同步到variable的类型定义中。

方案3：升级TypeScript版本 #

这个问题可能是TS 5.0.4的特定bug，尝试升级到5.1及以上版本，新版本可能修复了映射类型下注释输出的问题，无需修改代码即可保留注释。

原理说明 #

VSCode能看到注释是因为编辑器直接读取了原始代码的注释信息，但TS生成d.ts时，对于匿名对象通过映射类型推导的情况，默认没有把注释关联到输出的类型节点上。通过satisfies或显式类型标注，可以让TS明确把注释绑定到推导后的类型上，从而在d.ts中保留下来。

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