在TypeScript和/或JSDoc中，如何指示记录类型中的某些属性名称是同一类型中同级属性的别名？

如何解决在TypeScript和/或JSDoc中，如何指示记录类型中的某些属性名称是同一类型中同级属性的别名？

在TS中建模对象属性包类型（又称“记录”）的正确方法是什么，其中某些属性名是其他属性的替代名（又称“别名”）？特别是，我们希望使VSCode知道别名，以便它仅建议（在IntelliSense自动完成列表中）“主要”属性名称，而不是别名，但是我们也不想让TS编译器在用户手动键入时失败别名。

这里有更多背景知识：我们正在为JS库开发一个.d.ts，其中包括接受诸如{hour: 12,minute: 30,second: 0}之类的时间常量的函数。该库还接受这些文字属性的多种变体，例如{hours: 12,minutes: 30,seconds: 0}。使用复数变体不是最佳实践（可能仅在允许的情况下简要记录下来）。但是使用这些复数字符串也不会崩溃。

在两个变体中指定相同单位的情况下，将会崩溃： {hour: 12,hours: 12}。

我们应该如何在TS中为这种类型建模？

我们的目标：

• 从IDE自动完成中隐藏“错误的”变体。我以为我假设JSDoc ignore标签可用于此目的，但在TS文档的supported tags list中未列出，并且在VSCode中似乎没有任何作用。
• 允许“错误的”变体而不会出现TS编译器错误。
• 如果同一对象文字中包含相同属性的单数和复数变体，则会产生TS编译器错误。
理想地，如果存在一个较小的单元而没有相应的较大单元，则理想情况下也会产生编译器错误。例如，{hour: 10,second: 30}应该产生错误。就是说，由于并集类型的工作原理，我不确定TS中是否可以做到这一点。 理想情况下，即使不存在属性的别名，单数和复数变体的混合也应产生编译器错误。 {hours: 10,minute: 5}。如果TS未标出此错误，也可以，因为与上述“同一单元的2个变体”情况相比，这是一个罕见的错误。
• 理想情况下（这是可选的，因为我怀疑它不可能），复数形式将显示信息级别的IDE警告（VSCode中的淡蓝色波浪线），以鼓励用户选择正确的形式而不是错误的，但是没有破坏编译。

在TypeScript和/或JSDoc中为这些文字建模的推荐方法是什么，以实现这种期望的行为，或者至少实现其中的一部分？

这是包括两个变体在内的普通类型。该声明不具有上述任何期望的行为。

type Time = {
  hour?: number;
  minute?: number;
  second?: number;
  hours?: number;
  minutes?: number;
  seconds?: number;
};

JSDoc的@alias标签似乎最接近我们的意图，但是它似乎在VSCode中没有做任何事情，并且没有免除自动完成的复数形式。我也不确定@alias是否打算处理别名指向同级成员的情况。上面链接的JSDoc手册中的所有示例均指的是用一个名称定义成员但在运行时以另一个名称使用成员的情况，例如与类名前缀一起使用的静态类函数。我没有看到使用@alias来镜像另一个现有同级属性的示例。

我们可以使用JSDoc @deprecated，但这意味着该值过去可以，但现在还不行，这不是真的。但是它确实提供了一条消息，提醒用户使用其他变体。这似乎很有用。

JSDoc的@ignore标记似乎也可能有所帮助，但是它似乎在VSCode中没有任何作用，并且也没有免除自动完成的复数形式。

解决方法

• 从IDE自动完成中隐藏“错误的”变体。
• 允许“错误的”变体而不会出现TS编译器错误。

为此，我能想到的最接近的是new support for /** @deprecated */ in typescript 4.0.。这不会使它们无法自动完成，但是会在一行中标记它们以阻止其使用。

我不认为可以根据类型系统从自动完成中隐藏也是有效属性的任何内容。您最好得到的是标记为不鼓励使用。

是的，这不是@deprecated的完美用法，但是如果您想要IDE级别的提示，那将是最好的。

type Time = {
  hour?: number;
  minute?: number;
  second?: number;
  
  /** @deprecated */
  hours?: number;

  /** @deprecated */
  minutes?: number;

  /** @deprecated */
  seconds?: number;
};

---

对于其他情况，听起来好像不需要在这里使用单个界面。相反，您希望结合可能的组合。我认为解决此问题的唯一合理方法是为每个允许的组合创建一个类型。

但是您也想禁止某些组合中的某些属性，可以使用{ foo?: undefined }之类的方法来实现。

所以您可以将类似的东西放在一起：

// Singular Components
type Hour = { hour: number }
type Minute = { minute: number }
type Second = { second: number }

type NoHour = { hour?: undefined }
type NoMinute = { minute?: undefined }
type NoSecond = { second?: undefined }
type NoSingular = NoHour & NoMinute & NoSecond

// Plural Components
type Hours = { hours: number }
type Minutes = { minutes: number }
type Seconds = { seconds: number }

type NoHours = { hours?: undefined }
type NoMinutes = { minutes?: undefined }
type NoSeconds = { seconds?: undefined }
type NoPlural = NoHours & NoMinutes & NoSeconds

// Singular time type
type SingularTime = NoPlural & (
  | (Hour & NoMinute & NoSecond)
  | (Hour & Minute & NoSecond)
  | (Hour & Minute & Second)
)

// Plural time type
type PluralTime = NoSingular & (
  | (Hours & NoMinutes & NoSeconds)
  | (Hours & Minutes & NoSeconds)
  | (Hours & Minutes & Seconds)
)

// Final time type
type Time = SingularTime | PluralTime

（为简便起见，我省略了/** @deprecated */，但您必须在出现复数属性的所有时间中都添加它）

可以像这样使用：

// Good
const singular: Time = { hour: 1,minute: 2,second: 3 }
const plural: Time = { hours: 1,minutes: 2,seconds: 3 }

// Errors:
const samePropMix: Time = { hour: 1,hours: 2,minute: 3,second: 4 }
const diffPropMix: Time = { hour: 1,second: 3 }
const missingMinutes: Time = { hour: 1,second: 3 }

Playground