TypeScript 5.2中Elasticsearch API的refresh字面量字符串校验异常问题

问题背景 #

NodeJS ElasticSearch 7.12 API的index方法，其params参数对应的接口定义中，refresh属性支持'wait_for'字面量字符串或布尔值：

export interface Index<T = RequestBody> extends Generic {
  id?: string;
  refresh?: 'wait_for' | boolean;
}

报错场景 #

当初始化一个空对象options，并设置refresh为'wait_for'后传入ES.update时，TypeScript 5.2会抛出类型不兼容错误：

let options = {};
options.refresh = 'wait_for';
await ES.update({id, index, ...options});

错误信息如下：

No overload matches this call.
  Overload 1 of 4, '(params?: Update<{ doc: any; doc_as_upsert: boolean; script: any; scripted_upsert: any; }>, options?: TransportRequestOptions): TransportRequestPromise<ApiResponse<Record<string, any>, unknown>>', gave the following error.
    Argument of type '{ refresh: string; id: any; index: any; body: { doc: any; doc_as_upsert: true; script: any; scripted_upsert: any; }; retry_on_conflict: number; }' is not assignable to parameter of type 'Update<{ doc: any; doc_as_upsert: boolean; script: any; scripted_upsert: any; }>'.
      Types of property 'refresh' are incompatible.
        Type 'string' is not assignable to type 'boolean | "wait_for"'.

对比正常场景 #

• 若将refresh设为布尔值，代码可正常编译：

  options.refresh = true;
  

• 若options初始化为包含id的对象，再设置refresh为'wait_for'也无异常：

  let options = {id};
  options.refresh = 'wait_for';
  await ES.update({index, ...options});
  

原因解析 #

这并非TypeScript的bug，而是**类型拓宽（Type Widening）**的设计行为：

• 初始化空对象let options = {}时，TypeScript会将其推断为最宽泛的{}类型。后续添加refresh: 'wait_for'时，字符串字面量'wait_for'会被拓宽为通用的string类型，最终options的类型变为{ refresh: string }，与ES.update要求的'wait_for' | boolean类型不兼容。
• 赋值布尔值时，布尔值属于原始类型，TypeScript不会对其进行拓宽，options.refresh的类型会被推断为boolean，符合接口要求。
• 当options初始化为带id的对象时，TypeScript会为该对象推断更精确的类型，后续添加refresh: 'wait_for'时会保留字面量类型，最终options的类型为{ id: typeof id; refresh: 'wait_for' }，与接口的refresh类型匹配。

该行为符合TypeScript官方定义的对象字面量类型推断规则。

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