TypeScript泛型仅类型校验生效，无自动补全问题求助

需求描述 #

需要实现一个Pipeline抽象逻辑，让传入的步骤名（如"Step 1"）或嵌套的流程名（如"Step 1 procedure 1"）既能通过类型校验，又能触发IntelliSense自动补全。期望的使用方式如下：

type ProcedureSpec = {
  name: string;
};

type StepSpec = {
  name: string;
  procedures: Readonly<ProcedureSpec[]>;
};

type PipelineSpec = Readonly<{
  name: string;
  slug: string;
  steps: Readonly<StepSpec[]>;
}>;

const spec = {
  name: "Pipeline 1 name",
  slug: "pipeline1Slug",
  steps: [
    {
      name: "Step 1",
      procedures: [
        { name: "Step 1 procedure 1" },
        { name: "Step 1 procedure 2" },
        { name: "Step 1 procedure 3" },
      ],
    },
  ],
} as const satisfies PipelineSpec;

await pipeline<typeof spec>(async (step) => {
  await step<"Step 1">(async (procedure) => {
    await procedure<"Step 1 procedure 1">(async () => {
      console.log("Step 1 procedure 1");
    });
    // 期望此处输入时能自动补全剩余流程名
  });
});

现有实现问题 #

当前的pipeline函数仅能实现类型校验，但无法触发自动补全：

export async function pipeline<T extends PipelineSpec>(
  pipelineCb: (
    step: <SName extends T["steps"][number]["name"]>(
      stepCb: <S extends T["steps"][number] = Extract<T["steps"][number], { name: SName }>>(
        procedure: <PName extends S["procedures"][number]["name"]>(
          procedureCb: () => Promise<void>
        ) => Promise<void>
      ) => Promise<void>
    ) => Promise<void>
  ) => Promise<void>
) {
  return await pipelineCb(async (stepCb) => {
    return await stepCb(async (procedureCb) => {
      return await procedureCb();
    });
  });
}

问题根源在于嵌套泛型中使用Extract进行条件类型推导时，TypeScript无法提前解析出明确的字面量联合类型，导致自动补全逻辑失效。

解决方案 #

方案一：优化泛型类型推导 #

通过提前提取步骤名和流程名的联合类型，让TypeScript能明确识别可选值集合，从而触发自动补全：

首先定义工具类型提取所需的联合类型：

// 提取Pipeline所有步骤名称的联合类型
type StepNames<T extends PipelineSpec> = T["steps"][number]["name"];

// 根据步骤名称提取对应流程名称的联合类型
type ProcedureNames<T extends PipelineSpec, SName extends StepNames<T>> = 
  Extract<T["steps"][number], { name: SName }>["procedures"][number]["name"];

// 构建步骤名到流程名的映射类型，帮助TS明确推导关系
type StepToProcedures<T extends PipelineSpec> = {
  [S in StepNames<T>]: ProcedureNames<T, S>;
};

然后重写pipeline函数：

export async function pipeline<T extends PipelineSpec>(
  pipelineCb: (
    step: <SName extends keyof StepToProcedures<T>>(
      stepCb: (
        procedure: <PName extends StepToProcedures<T>[SName]>(
          procedureCb: () => Promise<void>
        ) => Promise<void>
      ) => Promise<void>
    ) => Promise<void>
  ) => Promise<void>
) {
  return await pipelineCb(async (stepCb) => {
    return await stepCb(async (procedureCb) => {
      return await procedureCb();
    });
  });
}

此方案保留原API的泛型参数风格，同时让TypeScript能直接识别StepToProcedures<T>的键和值类型，从而触发自动补全。

方案二：改用字符串参数传递（更稳定） #

将步骤名和流程名作为函数参数传入，而非泛型参数。这种方式下TypeScript对字面量参数的自动补全支持更可靠：

重写pipeline函数：

export async function pipeline<T extends PipelineSpec>(
  pipelineCb: (
    step: (
      stepName: StepNames<T>,
      stepCb: (
        procedure: (
          procedureName: ProcedureNames<T, typeof stepName>,
          procedureCb: () => Promise<void>
        ) => Promise<void>
      ) => Promise<void>
    ) => Promise<void>
  ) => Promise<void>
) {
  return await pipelineCb(async (stepName, stepCb) => {
    return await stepCb(async (procedureName, procedureCb) => {
      return await procedureCb();
    });
  });
}

对应的使用方式调整为：

await pipeline<typeof spec>(async (step) => {
  await step("Step 1", async (procedure) => {
    await procedure("Step 1 procedure 1", async () => {
      console.log("Step 1 procedure 1");
    });
    // 此处输入第一个参数时，会自动补全"Step 1 procedure 2"、"Step 1 procedure 3"
  });
});

这种方式更直观，且自动补全的稳定性更高，适合大多数场景。

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