如何在TypeScript中覆盖标准库函数JSON.parse的类型定义？

我正在开发一个Polyfill，通过为JSON.parse()的reviver回调函数添加可选第三个参数来扩展其行为。用户只需通过以下方式导入即可使用：

import 'my-polyfill';

TypeScript内置的JSON.parse定义位于node_modules/typescript/lib/lib.es5.d.ts，如下所示：

// lib.es5.d.ts
interface JSON {
  // …
  parse(
    text: string,
    reviver?: (this: any, key: string, value: any) => any
  ): any;
  // …
}

我需要覆盖这个默认定义，让用户导入Polyfill后自动使用我的自定义类型——比如带泛型支持、reviver多一个context参数的版本：

interface ContextType {
  // …
}

interface JSON {
  parse<Type = any>(
    text: string,
    reviver?: (
      key: string,
      value: any,
      context?: ContextType
    ) => any
  ): Type;
}

实现方法 #

1. 创建类型声明文件

在你的Polyfill包中新建一个index.d.ts（或对应入口的声明文件），利用TypeScript的接口合并特性扩展全局JSON接口：

// 定义自定义上下文类型
interface ContextType {
  // 填入你的上下文结构定义
}

// 扩展全局JSON接口
declare global {
  interface JSON {
    parse<Type = any>(
      text: string,
      reviver?: (
        key: string,
        value: any,
        context?: ContextType
      ) => any
    ): Type;
  }
}

// 标记为模块，避免全局作用域冲突
export {};

2. 配置包的类型入口

在Polyfill包的package.json中指定types字段，指向刚才创建的声明文件，确保TypeScript能自动识别：

{
  "name": "my-polyfill",
  "types": "./index.d.ts",
  // 其他包配置字段...
}

3. 关键注意点

• 接口合并是TypeScript原生支持的特性，只要你的扩展接口与内置JSON接口兼容（比如不修改原有参数的必填性、新增参数设为可选），就能自动合并生效。
• 保持兼容性：reviver回调的原有参数（key、value）位置不变，新增的context设为可选，避免破坏已有代码的类型检查。
• 泛型支持：新增的<Type = any>允许用户直接指定解析后的返回类型，无需额外类型断言。

内容的提问来源于stack exchange，提问作者Slava Fomin II