TypeScript类型定义：关联属性共存约束的报错问题及解决

问题描述 #

我需要定义一个包含path属性的TypeScript类型，要求valueTemplate必须与valuePath或$valuePath成对出现，单独出现其中任意一个都不合法：

合法对象示例 #

{ path: 'abc' }
{ path: 'def', valueTemplate: {}, valuePath: '' }
{ path: 'ghi', valueTemplate: {}, $valuePath: '' }

不合法对象示例 #

{ path: 'abc', valueTemplate: {} }
{ path: 'def', valuePath: '' }
{ path: 'ghi', $valuePath: '' }

我编写了如下类型定义：

type DynamicInputTarget = { path: string } & (
  { valueTemplate?: never; valuePath?: never; $valuePath?: never }
  | { valueTemplate: object; valuePath: string }
  | { valueTemplate: object; $valuePath: string }
)

初步测试符合预期：

const t1: DynamicInputTarget = { path: 'abc' } // 正常
const t2: DynamicInputTarget = { path: 'abc', valuePath: '' } // 报错（符合预期）
const t3: DynamicInputTarget = { path: 'abc', valuePath: '', valueTemplate: {} } // 正常

但访问t3.$valuePath时出现意外编译错误：

const hasDollarValuePath = !!t3.$valuePath // 编译错误

错误信息：

Property '$valuePath' does not exist on type '{ path: string; } & { valueTemplate: object; valuePath: string; }'. Did you mean 'valuePath'?

错误原因 #

当前的类型定义中，联合分支使用了never类型来约束属性不存在：

• 当创建t3时，TypeScript会根据字面量推断它属于{ path: string } & { valueTemplate: object; valuePath: string; }这个分支
• 该分支中没有定义$valuePath属性（never意味着这个属性不允许存在），所以TypeScript认为t3根本没有这个属性，访问时自然报错

解决方案 #

把分支中不需要的属性从never改为undefined，让这些属性在所有分支中都“存在”但值可能为undefined，这样就能安全访问：

type DynamicInputTarget = { path: string } & (
  { valueTemplate?: undefined; valuePath?: undefined; $valuePath?: undefined }
  | { valueTemplate: object; valuePath: string; $valuePath?: undefined }
  | { valueTemplate: object; $valuePath: string; valuePath?: undefined }
)

修改后测试：

const t3: DynamicInputTarget = { path: 'abc', valuePath: '', valueTemplate: {} }
const hasDollarValuePath = !!t3.$valuePath // 正常，结果为false

这样既保留了成对属性的约束（比如单独传valuePath仍然会报错），又能安全访问所有可能的属性，避免编译错误。

内容的提问来源于stack exchange，提问作者Nils-o-mat