PAYATHON 2026

为何 `NonNullable<Generic>` 总是返回 `never`?

排障赵师傅

结论

NonNullable<Target> 处理的并非原始类型 string | undefined。进入 Target extends undefined 的真分支后,分布式条件类型已经将 Target 缩窄为 undefined,此时:

NonNullable<undefined> // never

处理可选属性时,需要检查完整类型中是否包含 undefined:

undefined extends Target

然后再从完整类型中排除 undefined。直接使用下面的判断无法达到这个目的:

Target extends undefined

为什么会得到 never

条件类型左侧为裸类型参数时,TypeScript 会对联合类型的每个成员分别计算:

type Example<T> = T extends undefined ? "optional" : "required";

type Result = Example<string | undefined>;
// "required" | "optional"

所以:

JsonProcessingTemplate<string | undefined>

会被拆分为:

JsonProcessingTemplate<string>
| JsonProcessingTemplate<undefined>

计算 undefined 时,会进入真分支:

Target extends undefined
  ? JsonProcessingTemplate<NonNullable<Target>>
  : ...

这时 Target 已经缩窄为 undefined,因此:

NonNullable<Target>

等同于:

NonNullable<undefined> // never

接下来得到:

JsonProcessingTemplate<never>

分布式条件类型无法从 never 中取出任何联合成员,计算结果仍是 never。这样一来,undefined 分支会消失,最终只留下 string 对应的函数类型。

把 NonNullable 换成 Exclude<Target, undefined> 也解决不了原写法,因为进入该分支时,Target 已经是 undefined:

Exclude<undefined, undefined> // never

正确的类型设计

这里要判断 Target 是否允许为 undefined。可以写成:

type JsonProcessingTemplate<Target> =
  undefined extends Target
    ? {
        optional: true;
        value: JsonProcessingTemplate<Exclude<Target, undefined>>;
      }
    : Target extends string | number
      ? (id_or_object: string) => boolean
      : Target extends object
        ? {
            [Key in keyof Target]-?:
              JsonProcessingTemplate<Target[Key]>;
          }
        : never;

完整示例如下:

interface OptionalString {
  optional_string?: string;
}

type JsonManifest = {
  optional_string: OptionalString;
};

type JsonProcessingManifest = {
  [Key in keyof JsonManifest]:
    JsonProcessingTemplate<JsonManifest[Key]>;
};

type JsonProcessingTemplate<Target> =
  undefined extends Target
    ? {
        optional: true;
        value: JsonProcessingTemplate<Exclude<Target, undefined>>;
      }
    : Target extends string | number
      ? (id_or_object: string) => boolean
      : Target extends object
        ? {
            [Key in keyof Target]-?:
              JsonProcessingTemplate<Target[Key]>;
          }
        : never;

const json_manifest: JsonProcessingManifest = {
  optional_string: {
    optional_string: {
      optional: true,
      value: (input) => /.*/.test(input),
    },
  },
};

对应的计算过程为:

undefined extends string | undefined // true
Exclude<string | undefined, undefined> // string
JsonProcessingTemplate<string> // (id_or_object: string) => boolean

可选属性最终会转换为:

{
  optional: true;
  value: (id_or_object: string) => boolean;
}

NonNullable 也可以使用

如果需要同时排除 null,可以继续使用 NonNullable:

type JsonProcessingTemplate<Target> =
  undefined extends Target
    ? {
        optional: true;
        value: JsonProcessingTemplate<NonNullable<Target>>;
      }
    : Target extends string | number
      ? (id_or_object: string) => boolean
      : Target extends object
        ? {
            [Key in keyof Target]-?:
              JsonProcessingTemplate<Target[Key]>;
          }
        : never;

两者处理的范围不同:

Exclude<T, undefined> // 只移除 undefined
NonNullable<T>        // 同时移除 null 和 undefined

如果 null 是合法的 JSON 值,直接使用 NonNullable<T> 会把它一并删除。这种情况下,需要为 null 单独设计校验规则。

为什么分支里的测试结果会变化

在下面的条件类型中:

Target extends undefined ? ... : ...

真分支内的 Target 已受到 undefined 约束,所以再次判断时会得到 "Undefined":

Target extends string
  ? "String"
  : Target extends undefined
    ? "Undefined"
    : "Something Else"

同一段表达式如果位于 Target extends string 的真分支中,Target 会受到 string 约束,结果便是 "String"。

后一个条件没有覆盖前一个条件。每个条件类型分支都会保留该分支对应的类型约束。

注意事项

这套方案会把所有包含 undefined 的类型都视为可选,包括:

required_value: string | undefined;

这个属性虽然必填,转换后仍会被标记为 optional: true。若要严格区分 prop?: T 与 prop: T | undefined,需要在映射父对象时检查属性本身是否可选:

{} extends Pick<T, Key>

调用正则表达式时,建议使用包装函数:

value: (input) => /.*/.test(input)

这样可以避免直接提取对象方法可能引发的 this 绑定问题。

备注:内容仅供参考。