为何TypeScript扁平类型IntelliSense正常，嵌套类型失效？

问题场景 #

我定义了一个不算复杂的自定义类型：

• 采用扁平结构{ uniqueIndex: string, uniqueValues: T }时，IntelliSense智能提示完全正常；
• 改为嵌套结构{ index: { name: string, values: T } }后，智能提示会显示所有未过滤的键。

虽然TypeScript仍能正确校验潜在错误，类型校验功能符合预期，但智能提示失效对开发效率影响很大，想搞清楚这一现象的原因。

基础代码定义 #

type IndexColumns<I extends string, Attrs extends Record<string, any>> = Record<
    I,
    Array<keyof Attrs>
>;

type CarIndexes =
    | "pk"
    | "brand_model"
    | "brand_category"
;

interface ICars {
    code: string;
    brand: "skoda" | "ford" | "volvo";
    category: "family" | "off-road" | "racing";
    model: string;
}

const carIndexColumns = {
    pk: ['code'],
    brand_category: ["brand", "category"],
    brand_model: ["brand", "model"],
} satisfies IndexColumns<CarIndexes, ICars>;

版本1：扁平结构（IntelliSense正常） #

interface FindUniqueParams<Index extends CarIndexes> {
    context: 'tenant' | 'cross',
    uniqueIndex: Index,
    uniqueValues: { [K in (typeof carIndexColumns)[Index][number]]: ICars[K] }
}

版本2：嵌套结构（IntelliSense失效） #

interface FindUniqueParams<Index extends CarIndexes> {
    context: 'tenant' | 'cross',
    uniqueIndex: {
        name: Index,
        values: { [K in (typeof carIndexColumns)[Index][number]]: ICars[K] },
    }
}

调用函数定义 #

declare function findUnique<Index extends CarIndexes>(
    params: FindUniqueParams<Index>,
    arg?: { logging?: boolean },
): void;

原因解析 #

核心在于TypeScript泛型推断与智能提示引擎的上下文处理逻辑差异：

1. 扁平结构的工作原理：
   扁平结构中，uniqueIndex和uniqueValues是同级属性。当你输入uniqueIndex的具体值（比如"pk"）时，TypeScript会立即将泛型Index约束为该具体值，随后就能基于这个确定的Index，精准推导uniqueValues的键（比如仅code），智能提示自然能实时过滤出符合要求的选项。

2. 嵌套结构的局限：
   嵌套结构中，name和values同属uniqueIndex对象的子属性。TypeScript的智能提示引擎在处理嵌套对象时，会将整个uniqueIndex作为一个完整的结构来处理——泛型Index的具体化需要等到整个uniqueIndex对象的输入完成后才能确定。在输入过程中，引擎无法提前根据name的临时输入值来动态缩小values的类型范围，因此只能展示所有可能键的联合集合（也就是未过滤的所有ICars键）。

简单来说，扁平结构下的属性是分步确定泛型约束，而嵌套结构下的泛型约束需要整个嵌套对象完成输入后才能锁定，这就导致了智能提示的延迟失效。

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