TypeScript编译后类型守卫返回类型缺失undefined问题咨询

问题复现 #

我使用TypeScript 4.9.5编写了如下类型守卫函数：

export const isNullOrUndefined = (value: any): value is null | undefined => {
  return value === null || value === undefined;
};

期望编译生成的index.d.ts中，函数返回类型为value is null | undefined，但实际生成内容为：

export declare const isNullOrUndefined: (value: any) => value is null;

而非预期的：

export declare const isNullOrUndefined: (value: any) => value is null | undefined;

我的tsconfig.json配置如下：

{
  "compilerOptions": {
    "incremental": false,
    "target": "es2019",
    "outDir": "build",
    "rootDir": "src",
    "moduleResolution": "node",
    "module": "commonjs",
    "declaration": true,
    "inlineSourceMap": false,
    "esModuleInterop": true,
    "resolveJsonModule": true,
    "removeComments": false,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "traceResolution": false,
    "listEmittedFiles": false,
    "listFiles": false,
    "pretty": true,
    "lib": ["es2019", "dom"],
    "types": ["node"],
    "typeRoots": ["node_modules/@types", "src/types"]
  },
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules/**"],
  "compileOnSave": false
}

原因分析 #

这是TypeScript 4.9.x版本的一个已知bug：当类型守卫的返回类型显式声明为value is null | undefined，且函数体通过value === null || value === undefined的方式判断时，编译器在生成.d.ts声明文件时会错误地丢弃undefined类型部分，只保留null。这个问题在TypeScript 5.0及后续版本中已经被官方修复。

另外补充：如果函数体改用return value == null;（== null等价于判断值为null或undefined），TypeScript 4.9.x版本能正确识别并生成包含null | undefined的声明类型，因为编译器对== null的类型推导逻辑处理更准确。

解决方案 #

• 升级TypeScript版本：直接升级到5.0及以上版本，彻底修复该声明生成bug，同时能获得新版本的其他特性和优化。
• 修改判断逻辑（临时方案）：如果暂时无法升级TS版本，将函数体的判断语句改为return value == null;，这样在4.9.x版本下编译出的.d.ts会正确保留value is null | undefined的返回类型。

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