泛型方法中解析Promise时为何出现TypeScript类型错误？

问题背景 #

为WebSocket协议添加类型定义时，编写了如下类型与函数框架，但在实现doAction函数时遇到了类型不兼容错误。

类型定义代码 #

type Action =
    | {
        action: "change-or-create-state";
        response: string;
    }
    | {
        action: "get-state";
        response: string | null;
    };

/**
 * 根据action映射对应的response类型
 */
type ActionResponse<T extends Action["action"]> = Extract<
    Action,
    { action: T }
>["response"];

export async function doAction<
    TAction extends Action["action"]
>(action: TAction): Promise<ActionResponse<TAction>> { /* ... */ }

实现代码与错误提示 #

// 实际通过WebSocket接收的数据
const someDataFromAPI: string = '"hello world"'

export async function doAction<
    TAction extends Action["action"]
>(action: TAction): Promise<ActionResponse<TAction>> {
    return new Promise<ActionResponse<TAction>>((resolve) => {
        // 实际代码会做类型校验，这里先跳过直接断言类型
        const jsonWithSpecificType: ActionResponse<TAction> = JSON.parse(someDataFromAPI);

        /** ⚠️ 错误提示：
        Argument of type 'ActionResponse<TAction>' is not assignable to parameter of type 'ActionResponse<TAction> | PromiseLike<ActionResponse<TAction>>'.
        Type 'Extract<{ action: "get-state"; response: string | null; }, { action: TAction; }>["response"]' is not assignable to type 'ActionResponse<TAction> | PromiseLike<ActionResponse<TAction>>'.
        Type 'string | null' is not assignable to type 'ActionResponse<TAction> | PromiseLike<ActionResponse<TAction>>'.
        Type 'null' is not assignable to type 'ActionResponse<TAction> | PromiseLike<ActionResponse<TAction>>'.(2345)
        */
        resolve(jsonWithSpecificType)
    })
}

问题根源 #

这不是箭头函数的类型一致性问题，核心原因是TypeScript泛型上下文里条件类型的推断限制：

1. ActionResponse<TAction>基于Extract条件类型实现，当TAction是泛型参数时，TypeScript无法在Promise回调内部将其完全解析为具体类型，只能保留条件类型的原始形式。
2. 错误提示里的Extract<{ action: "get-state"; response: string | null; }, { action: TAction; }>["response"]就是未解析的条件类型。此时TypeScript无法确认string | null是否能匹配ActionResponse<TAction>的所有可能场景——比如当TAction是"change-or-create-state"时，ActionResponse<TAction>是string，null显然不兼容这个类型，因此触发类型报错。
3. 即便你断言了局部变量的类型，TypeScript也无法在泛型函数的嵌套回调中验证这个断言的有效性，因为TAction的具体类型要到函数调用时才能确定。

解决方案 #

方式1：直接给resolve参数加类型断言 #

跳过局部变量的类型声明，直接在resolve时断言类型，让TypeScript明确类型匹配：

export async function doAction<TAction extends Action["action"]>(action: TAction): Promise<ActionResponse<TAction>> {
    return new Promise((resolve) => {
        const parsed = JSON.parse(someDataFromAPI);
        resolve(parsed as ActionResponse<TAction>);
    })
}

方式2：显式指定回调函数的参数类型 #

给Promise的resolve回调明确指定参数类型，帮助TypeScript关联外部泛型：

export async function doAction<TAction extends Action["action"]>(action: TAction): Promise<ActionResponse<TAction>> {
    return new Promise<ActionResponse<TAction>>((resolve: (value: ActionResponse<TAction>) => void) => {
        const jsonWithSpecificType = JSON.parse(someDataFromAPI) as ActionResponse<TAction>;
        resolve(jsonWithSpecificType);
    })
}

方式3：改用映射类型（更推荐） #

重构类型为映射结构，让TypeScript能更清晰地解析泛型对应的返回类型，避免条件类型的模糊性：

type ActionMap = {
    "change-or-create-state": string;
    "get-state": string | null;
};

type Action = {
    [K in keyof ActionMap]: {
        action: K;
        response: ActionMap[K];
    };
}[keyof ActionMap];

type ActionResponse<T extends keyof ActionMap> = ActionMap[T];

export async function doAction<TAction extends keyof ActionMap>(action: TAction): Promise<ActionResponse<TAction>> {
    return new Promise((resolve) => {
        resolve(JSON.parse(someDataFromAPI) as ActionResponse<TAction>);
    })
}

这种写法更直观，TypeScript对泛型的解析会更准确，减少条件类型带来的推断问题。

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