声明文件中如何通过泛型约束实现组件类型继承校验？

我定义了一个作为“父类型”的COMPONENT类型，要求其他元素类型必须满足该类型的约束。在常规.ts/.tsx文件里，代码能正常做类型校验（比如使用不属于ELEMENT_TYPE的"hero"类型会报错），但在.d.ts声明文件里这个约束不生效。想知道怎么在声明文件里声明泛型类型，并把它作为“模板”来约束更具体的类型？

我的声明文件代码如下：

declare type ELEMENT_TYPE = "div" | "p" | "h1" | "button";

declare type COMPONENT = {
  type: ELEMENT_TYPE;
  children: (COMPONENT | string)[];
};

declare type Satisfies<T, U extends T> = U;

declare type HERO = Satisfies<
  COMPONENT,
  {
    type: "hero";
    children: (COMPONENT | string)[];
  }
>; // 理应报错但在声明文件中无提示

tsconfig配置：

{
  "compilerOptions": {
    "target": "es5",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [
      {
        "name": "next"
      }
    ],
    "paths": {
      "@/*": ["./*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

解决方案 #

方法一：用条件类型强制约束，不满足则返回never #

修改Satisfies类型为条件类型，当传入的子类型不满足父类型约束时，返回never类型，后续使用该类型时会直接报错：

declare type ELEMENT_TYPE = "div" | "p" | "h1" | "button";

declare type COMPONENT = {
  type: ELEMENT_TYPE;
  children: (COMPONENT | string)[];
};

// 修改后的Satisfies：满足约束则返回U，否则返回never
type Satisfies<T, U> = U extends T ? U : never;

// 此时HERO会被推断为never，使用时触发错误
type HERO = Satisfies<
  COMPONENT,
  {
    type: "hero";
    children: (COMPONENT | string)[];
  }
>;

方法二：反向约束的断言类型，定义阶段直接报错 #

定义一个断言类型，要求第一个泛型参数必须继承第二个参数，这样在定义类型时就会直接触发约束检查：

declare type ELEMENT_TYPE = "div" | "p" | "h1" | "button";

declare type COMPONENT = {
  type: ELEMENT_TYPE;
  children: (COMPONENT | string)[];
};

// 断言类型：U必须继承自T，否则直接报错
type AssertExtends<U extends T, T> = U;

// 此处会立即报错，因为{type: "hero", ...}不满足COMPONENT的约束
type HERO = AssertExtends<
  {
    type: "hero";
    children: (COMPONENT | string)[];
  },
  COMPONENT
>;

方法三：替换declare type为普通type定义 #

在.d.ts文件中，直接用type而非declare type来定义具体子类型，TypeScript会更严格地校验泛型约束：

declare type ELEMENT_TYPE = "div" | "p" | "h1" | "button";

declare type COMPONENT = {
  type: ELEMENT_TYPE;
  children: (COMPONENT | string)[];
};

type Satisfies<T, U extends T> = U;

// 用普通type定义，触发约束检查
type HERO = Satisfies<
  COMPONENT,
  {
    type: "hero";
    children: (COMPONENT | string)[];
  }
>;

问题原因 #

.d.ts文件中的declare type主要用于声明全局可见的类型，TypeScript默认不会主动触发其泛型参数的约束校验，除非该类型被实际引用或赋值。而常规.ts/.tsx文件中的类型定义会实时进行约束检查。你的tsconfig已经开启strict: true，只需调整类型定义方式即可让约束生效。

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