TypeScript 的 JSDoc 通用类型定义

Question

我在 JavaScript 项目中使用 JSDoc，该项目使用 TypeScript 编译器进行检查。

在 TypeScript 中，我可以像这样创建一个泛型类型：

type Optional<TType extends string> = { type: TType; optional?: boolean; } | { type: `${TType}?` };
type OptionalThing = Optional<'thing'>;

OptionalThing的解析和展平值现在是这样的：

type OptionalThing = 
  | { type: 'thing'; optional?: boolean; }
  | { type: 'thing?'; }

这种类型创建一个类型联合，其中一个成员类型具有type字段的文字和常量thing值，并且它具有额外的optional boolean 字段，而另一个成员类型具有文字和常量thing? 对于type字段并且没有optional字段。

? type上的后缀是一种简写语法，用于在我正在解决的问题中将事物标记为可选，因此需要禁止另外指定optional ，否则可能表示无效值： { type: 'thing?', optional: false } 。

换句话说：

/* These are allowed - they conform to the type */
const optionalThing1: OptionalThing = { type: 'thing?' };
const optionalThing2: OptionalThing = { type: 'thing', optional: true };
const optionalThing3: OptionalThing = { type: 'thing', optional: false };

// This is disallowed, `optional` cannot be specified while `type` has `?` suffix
const optionalThing4: OptionalThing = { type: 'thing?', optional: false };

// This is disallowed, `type` must be either `thing` or `thing?` const string
const optionalThing5: OptionalThing = { type: 'not literally "thing"' };

Playground（配置为 TypeScript）

我无法将其转换为在 TypeScript 中具有相同行为的 JSDoc。 我试过这个：

/** @typedef {{ type: T; optional?: boolean; } | { type: `${T}?`; }} Type<T> */
/** @template {string} T */

/** @typedef {Type<'thing'>} ThingType */
// Error: Type 'Type' is not generic.

Playground（配置为 JavaScript）

当 TypeScript 检查 JavaScript 和 JSDoc 版本时，如何在 JSDoc 中创建通用typedef以使上述 TypeScript 逻辑工作方式相同？

Answer 1

您的代码几乎是正确的，您只需将@template和@typedef标签放在同一个 JSDoc 注释中，如下所示：

/** 
 * @typedef {{ type: T; optional?: boolean; } | { type: `${T}?`; }} Type<T>
 * @template {string} T
 */

/**
 * @typedef {Type<'thing'>} ThingType
 */

游乐场链接

通常，当您需要定义一个泛型类型时，您需要在该@typedef标记旁边还有一个@template标记在同一个JSDoc 注释中。

但是，您不能将ThingType typedef放在同一个 JSDoc 中，否则它也会成为泛型类型。