如何让TypeScript强制函数参数使用相同长度的元组类型？

问题场景 #

我编写了一个泛型函数，泛型参数为1元素元组TypeA或2元素元组TypeB，希望确保函数接收的对象中所有属性都使用相同长度的元组。现有代码如下：

type TypeA = [string] // 1元素元组
type TypeB = [string, string] // 2元素元组
type Header = TypeA | TypeB

interface SomeObject<H extends Header> {
    prop1: H
    prop2: H
}

function useHeader<H extends Header>(someObject:SomeObject<H>) {
    // 业务逻辑
}

useHeader({
    prop1: ["tuple of 1 element"],
    prop2: [
        "tuple of", 
        "2 elements"
    ] // <-- 此处期望触发错误，但当前无报错
})

发现当把TypeA改为number、TypeB改为string时，混用两种类型会触发TypeScript错误，但不同长度的元组混用时却没有预期的错误提示，请问如何解决这个问题？

解决方案 #

问题根源在于TypeScript对元组联合类型的推断逻辑：当使用H extends Header时，TypeScript会将H推断为TypeA | TypeB的联合类型，而非强制单一元组类型。以下是几种可行的解决方式：

方案一：通过隐藏属性约束元组长度 #

添加一个隐藏的类型约束属性，当元组长度不一致时，该属性会触发never类型错误：

type TypeA = [string];
type TypeB = [string, string];
type Header = TypeA | TypeB;

// 提取元组长度的工具类型
type TupleLength<T extends readonly any[]> = T['length'];

interface SomeObject<H extends Header> {
    prop1: H;
    prop2: H;
    // 当prop1和prop2长度不一致时，此属性类型为never，触发错误
    _ensureSameLength: TupleLength<typeof this.prop1> extends TupleLength<typeof this.prop2> ? unknown : never;
}

function useHeader<H extends Header>(someObject: SomeObject<H>) {
    // 忽略隐藏属性，不影响业务逻辑
    const { _ensureSameLength, ...rest } = someObject;
    // 业务逻辑
}

// 正常情况：同长度元组，无错误
useHeader({
    prop1: ["1 element"],
    prop2: ["another 1 element"]
});

// 错误情况：不同长度元组，触发TypeScript错误
useHeader({
    prop1: ["tuple of 1 element"],
    prop2: ["tuple of", "2 elements"]
});

方案二：将元组长度作为泛型参数 #

直接把元组长度作为泛型约束，强制所有属性使用对应长度的元组：

type TypeA = [string];
type TypeB = [string, string];
// 根据长度映射对应元组类型
type Header<L extends 1 | 2> = L extends 1 ? TypeA : TypeB;

interface SomeObject<L extends 1 | 2> {
    prop1: Header<L>;
    prop2: Header<L>;
}

function useHeader<L extends 1 | 2>(someObject: SomeObject<L>) {
    // 业务逻辑
}

// 正常情况
useHeader({
    prop1: ["1 element"],
    prop2: ["another 1 element"]
});

// 错误情况：不同长度元组，触发错误
useHeader({
    prop1: ["tuple of 1 element"],
    prop2: ["tuple of", "2 elements"]
});

方案三：用联合类型限制对象结构 #

直接定义对象的合法结构为两种单一元组类型的联合，避免TypeScript合并推断：

type TypeA = [string];
type TypeB = [string, string];
type Header = TypeA | TypeB;

// 限制对象只能是全TypeA或全TypeB的结构
type SomeObject = {
    prop1: Header;
    prop2: Header;
} & ({ prop1: TypeA; prop2: TypeA } | { prop1: TypeB; prop2: TypeB });

function useHeader(someObject: SomeObject) {
    // 业务逻辑
}

// 正常情况
useHeader({
    prop1: ["1 element"],
    prop2: ["another 1 element"]
});

// 错误情况：不同长度元组，触发错误
useHeader({
    prop1: ["tuple of 1 element"],
    prop2: ["tuple of", "2 elements"]
});

原代码不报错的原因 #

当TypeA和TypeB是不同长度的元组时，TypeScript会将泛型H推断为TypeA | TypeB，此时prop1: TypeA和prop2: TypeB都符合H extends Header的约束，因此不会报错。而当TypeA是number、TypeB是string时，prop1: number和prop2: string无法同时满足单一H的类型推断，所以会触发错误。

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