TypeScript中如何从对象类型排除单个键以解决类型索引错误？

问题背景 #

我正在为颜色转换器编写类型定义。JavaScript环境中，通过条件判断能确保不会调用错误的转换方法，但TypeScript无法推断已经排除了无效选项，抛出如下错误：

Element implicitly has an 'any' type because expression of type 'OutputFormat' can't be used to index type '{ hsl: () => string; hsv: () => string; } | { rgb: () => string; hsv: () => string; } | { rgb: () => string; hsl: () => string; }'.
  Property 'rgb' does not exist on type '{ hsl: () => string; hsv: () => string; } | { rgb: () => string; hsv: () => string; } | { rgb: () => string; hsl: () => string; }'.

Exclude<T,U>这类工具类型在此场景不适用，因为它们操作的是整个联合类型，我需要告诉TypeScript：const from = converters[ inputFormat ];中的from永远不会包含outputFormat作为键。

代码示例 #

type OutputFormat = 'rgb' | 'hsl' | 'hsv';

// 该对象来自外部库，结构固定
const converters = {
    // 注意此处无rgb键
    rgb: {
        hsl: (): string => 'foo',
        hsv: (): string => 'foo',
    },
    // 注意此处无hsl键
    hsl: {
        rgb: (): string => 'foo',
        hsv: (): string => 'foo',
    },
    // 注意此处无hsv键
    hsv: {
        rgb: (): string => 'foo',
        hsl: (): string => 'foo'
    }
};

function convert( color: string, outputFormat: OutputFormat ): string {
    const inputFormat = detectFormat( color );

    if ( inputFormat === outputFormat ) {
        return color;
    }

    const from = converters[ inputFormat ];

    // 前置条件已排除inputFormat与outputFormat相同的情况，
    // 不会出现converters.rgb.rgb()这类调用，但TypeScript无法识别
    const to = from[ outputFormat ];

    return to( color );
}

function detectFormat( color: string ): 'rgb' | 'hsl' | 'hsv' {
    return 'rgb';
};

解决方案 #

方案一：泛型重载+类型断言

通过泛型函数明确输入格式与输出格式的互斥关系，同时定义转换器的结构类型，让TypeScript理解两者的关联：

type Format = 'rgb' | 'hsl' | 'hsv';

// 定义转换器的结构：每个格式对应的转换方法不包含自身
type ConverterMap = {
  [F in Format]: { [T in Exclude<Format, F>]: (color: string) => string };
};

// 用satisfies确保converters符合ConverterMap的类型约束
const converters = {
    rgb: {
        hsl: () => 'foo',
        hsv: () => 'foo',
    },
    hsl: {
        rgb: () => 'foo',
        hsv: () => 'foo',
    },
    hsv: {
        rgb: () => 'foo',
        hsl: () => 'foo'
    }
} as const satisfies ConverterMap;

// 泛型重载：明确输出格式是输入格式的排除类型
function convert<I extends Format>(color: string, outputFormat: Exclude<Format, I>): string;
function convert(color: string, outputFormat: Format): string;
function convert(color: string, outputFormat: Format): string {
    const inputFormat = detectFormat(color) as Format;

    if (inputFormat === outputFormat) {
        return color;
    }

    const from = converters[inputFormat];
    // 用类型断言告诉TS，outputFormat是from的有效键
    const to = from[outputFormat as Exclude<Format, typeof inputFormat>];

    return to(color);
}

function detectFormat(color: string): Format {
    return 'rgb';
};

方案二：自定义类型守卫

通过自定义类型守卫在编译时缩小类型范围，同时在运行时验证转换的有效性：

type Format = 'rgb' | 'hsl' | 'hsv';

const converters = {
    rgb: {
        hsl: () => 'foo',
        hsv: () => 'foo',
    },
    hsl: {
        rgb: () => 'foo',
        hsv: () => 'foo',
    },
    hsv: {
        rgb: () => 'foo',
        hsl: () => 'foo'
    }
} as const;

// 类型守卫：验证outputFormat是否是inputFormat对应的有效转换目标
function isValidOutputFormat<I extends Format>(
    input: I,
    output: Format
): output is keyof typeof converters[I] {
    return output in converters[input];
}

function convert(color: string, outputFormat: Format): string {
    const inputFormat = detectFormat(color);

    if (inputFormat === outputFormat) {
        return color;
    }

    const from = converters[inputFormat];

    // 类型守卫让TS确认outputFormat是from的有效键
    if (!isValidOutputFormat(inputFormat, outputFormat)) {
        throw new Error(`无法从${inputFormat}转换到${outputFormat}`);
    }

    const to = from[outputFormat];
    return to(color);
}

function detectFormat(color: string): Format {
    return 'rgb';
};

说明 #

• 方案一通过泛型重载让TypeScript在编译阶段就识别输入输出格式的互斥关系，适合对类型安全性要求高的场景。
• 方案二通过类型守卫兼顾编译时类型检查和运行时验证，代码更直观，适合需要额外错误处理的场景。

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