ts-toolkit 用于 TypeScript：完整指南

1. 这是什么以及为什么需要它

ts-toolkit 是一个强大的 TypeScript 工具库，旨在简化开发人员的日常任务。它提供了一组现成的函数、类型和类，帮助更高效、更安全地处理对象、数组、字符串、函数和数据类型。与标准 JavaScript 库不同，ts-toolkit 提供了严格类型化的解决方案，完全兼容 TypeScript 的类型系统。

为什么需要这个库？在现代 TypeScript 开发中，经常需要执行常规操作：深度复制对象、安全导航嵌套结构、运行时类型检查、处理 Option/Result（用于错误处理的单子）等等。ts-toolkit 负责实现这些模式，使开发人员能够专注于业务逻辑。该库在需要高可靠性和严格类型化的项目中特别有用。

ts-toolkit 的关键优势是类型安全。每个函数的设计都旨在充分利用 TypeScript 的功能：条件类型、映射类型、infer 和其他高级构造。这意味着许多可能仅在运行时才会出现的错误将在编译阶段被捕获。

2. 安装

通过 npm 包管理器安装该库：

npm install @tool-belt/ts-toolkit

或者通过 yarn：

yarn add @tool-belt/ts-toolkit

安装后，将所需函数导入到您的项目中：

import { deepClone, safeGet, pipe } from '@tool-belt/ts-toolkit';

3. 快速入门

展示该库主要功能的最小工作示例：

import { deepClone, isObject, pipe } from '@tool-belt/ts-toolkit';\n\n// 示例 1：深度复制\nconst original = { a: 1, b: { c: 2 } };\nconst cloned = deepClone(original);\ncloned.b.c = 42;\nconsole.log(original.b.c); // 2（原始对象未改变）\n\n// 示例 2：类型检查\nconsole.log(isObject({}));   // true\nconsole.log(isObject(null)); // false\n\n// 示例 3：函数组合\nconst addOne = (x: number) => x + 1;\nconst double = (x: number) => x * 2;\nconst addOneThenDouble = pipe(addOne, double);\nconsole.log(addOneThenDouble(5)); // 12

4. 主要方法和函数

4.1. deepClone

签名： function deepClone<T>(value: T): T

描述： 对任何值执行深度复制，包括嵌套对象、数组、日期、Map、Set 和其他结构。支持循环引用。

import { deepClone } from '@tool-belt/ts-toolkit';\n\nconst user = {\n  name: 'Alice',\n  address: { city: 'NYC', zip: 10001 },\n  hobbies: ['reading', 'coding']\n};\n\nconst clonedUser = deepClone(user);\nclonedUser.address.city = 'LA';\nconsole.log(user.address.city); // 'NYC'

4.2. safeGet

签名： function safeGet<T, K extends keyof T>(obj: T, key: K): T[K] | undefined

描述： 安全地获取对象属性的值。如果属性不存在或对象为 null/undefined，则返回 undefined，而不是抛出错误。

import { safeGet } from '@tool-belt/ts-toolkit';\n\nconst data = { user: { name: 'Bob' } };\nconst name = safeGet(data, 'user')?.name; // 'Bob'\nconst missing = safeGet(null, 'anythi