es-toolkit/compat 的 add 函数：Lodash 兼容的加法实现与源码剖析

es-toolkit/compat 的 add 函数：Lodash 兼容的加法实现与源码剖析

【免费下载链接】es-toolkitA modern JavaScript utility library that's 2-3 times faster and up to 97% smaller, a major upgrade to lodash.项目地址: https://gitcode.com/GitHub_Trending/es/es-toolkit

add是 es-toolkit 兼容层（es-toolkit/compat）中与 Lodash 行为 1:1 对齐的算术函数，用于将两个值相加。与 es-toolkit 主包中类型安全、纯数值的加法不同，兼容版add需要复刻 Lodash 的隐式类型转换：既支持数值相加，也支持字符串拼接，还能特殊处理NaN与undefined。阅读本文后，你将掌握add的完整调用语义、边界行为、底层实现原理，以及如何在迁移 Lodash 代码库时正确使用它。

为什么需要add：兼容层的定位

在开始讲解add之前，有必要先明确它的存在场景。es-toolkit/compat 兼容层 旨在 1:1 复刻 Lodash 的接口与行为，目的是让已有 Lodash 代码库无需改写调用点即可迁移到 es-toolkit，之后再逐步切换到类型更严格的 es-toolkit 主包 API。

正因如此，add并非一个"纯粹"的加法函数——它需要模拟 Lodash 中的隐式类型转换（如字符串拼接）、undefined的默认值处理等兼容性行为。如果你没有 Lodash 迁移需求，官方推荐直接使用 es-toolkit 主包，而非 compat 层。

官方警示：优先使用+运算符

add的参考文档开头便附有一条醒目的警告：

由于复杂的类型转换和字符串处理，这个add函数运行较慢。请改用更快、更简单的+运算符。

这是理解add的关键前提：它是为 Lodash 兼容而生的"行为复刻器"，而非性能最优的加法工具。在不需要字符串拼接等兼容语义的普通场景下，直接用原生+运算符即可获得更佳性能。

基本用法：数值相加与 NaN 传播

add的签名与 Lodash 完全一致：

const result = add(value, other);

其中value（number）为第一个相加的值，other（number）为第二个相加的值。从 src/compat/math/add.ts 的导出签名可以看到，其类型层面声明为add(value: number, other: number): number，但在运行时它接受并处理更多类型的实参。

数值相加

import { add } from 'es-toolkit/compat'; // 整数相加 add(2, 3); // Returns: 5 // 小数相加 add(1.5, 2.5); // Returns: 4 // 负数相加 add(-6, 4); // Returns: -2 add(-6, -4); // Returns: -10

这些基础用例在 add.spec.ts 测试 中有完整覆盖：正数相加、负数相加、正负混合相加均返回预期结果。

NaN 的传播语义

当任一参数为NaN时，add返回NaN——这符合 IEEE 754 浮点算术的传播规则：

import { add } from 'es-toolkit/compat'; add(NaN, 5); // Returns: NaN add(10, NaN); // Returns: NaN add(NaN, NaN); // Returns: NaN

从源码 src/compat/math/add.ts 可以看到，NaN的传播是最终value + other运算的自然结果：NaN参与加法必然得到NaN。对应测试 add.spec.ts 分别验证了"第一个参数为 NaN""第二个参数为 NaN""两个参数均为 NaN"三种情形。

字符串参与：拼接而非相加

add与普通+运算符最大的差异在于字符串处理。当任一参数为字符串时，add会执行字符串拼接而不是数值加法：

import { add } from 'es-toolkit/compat'; add('2', 3); // Returns: '23' add(1, '5'); // Returns: '15' add('hello', 'world'); // Returns: 'helloworld'

这一行为在源码中有明确实现（src/compat/math/add.ts）：

if (typeof value === 'string' || typeof other === 'string') { value = toString(value) as any; other = toString(other) as any; } else { value = toNumber(value); other = toNumber(other); }

即：只要有一个参数是字符串，两个参数都会被先转换为字符串再做拼接；否则才走数值转换与加法路径。

字符串参数的转换细节

字符串转换委托给 src/compat/util/toString.ts 中的toString工具函数，它与原生String()存在多处差异，这些细节决定了add的兼容精度：

• null与undefined转为空字符串：toString(null)返回''，toString(undefined)返回''；
• 保留-0的符号：toString(-0)返回'-0'（而非'0'），这在add的符号保留测试中有关键作用；
• 数组递归拼接：toString([1, 2, -0])返回'1,2,-0'，且稀疏数组中的空洞按 Lodash 语义渲染为undefined；
• Symbol 调用Symbol.prototype.toString：toString([Symbol('a'), Symbol('b')])返回'Symbol(a),Symbol(b)'；
• 对象使用默认转换提示（default hint）：源码注释明确指出，通过value + ''拼接会先读取valueOf()再读取toString()，这与String(value)的 string hint 行为不同——这是刻意对齐 Lodash 的实现选择。

测试对字符串语义的验证

add.spec.ts 中专门有一条用例：不将参数强制转为数字（should not coerce arguments to numbers），验证add('6', '4')返回'64'、add('x', 'y')返回'xy'。这明确说明 compat 版的add刻意保留了 Lodash 的字符串拼接行为，与 es-toolkit 主包中纯数值的加法形成对比。

undefined 的特殊处理

add对undefined参数有专门的处理逻辑，这是它区别于普通运算符的又一处兼容语义：

import { add } from 'es-toolkit/compat'; add(undefined, undefined); // Returns: 0 add(5, undefined); // Returns: 5 add(undefined, 3); // Returns: 3

对应源码（src/compat/math/add.ts）：

if (value === undefined && other === undefined) { return 0; } if (value === undefined || other === undefined) { return value ?? other; }

规则可以概括为：

测试 add.spec.ts 覆盖了"无参数调用返回 0""只有一个定义参数"两组场景，其中add()（零参数）与add(6)（单参数）均在类型层被标注为非法调用（@ts-expect-error），但在运行时按 Lodash 兼容语义正常返回。

深入实现：对象与 Symbol 的转换行为

当参数既不是字符串也不是undefined时，add会走数值转换路径，调用 src/compat/util/toNumber.ts 中的toNumber工具函数：

export function toNumber(value: any): number { if (isSymbol(value)) { return NaN; } return Number(value); }

这里有一个关键设计：toNumber与原生Number()不同，对 Symbol 返回NaN而非抛错。这一细节直接影响add对非常规输入的处理结果。

对象转换为 NaN

add.spec.ts 验证了对象参数的行为：

add(0, {}); // => NaN add({}, 0); // => NaN

普通对象经Number()转换后为NaN，参与加法后整个结果变为NaN。这是toNumber语义的自然结果。

Symbol 转换为 NaN

add.spec.ts 验证了 Symbol 参数的行为：

add(0, symbol); // => NaN add(symbol, 0); // => NaN

测试中使用的symbol来自兼容层内部工具 src/compat/_internal/symbol.ts，验证add对 Symbol 的宽容处理——返回NaN而非抛出TypeError。

零的符号保留

add.spec.ts 中还有一组非常细致的测试：保留0的符号。测试用1 / result来探测+0（得到Infinity）与-0（得到-Infinity）：

无论参数是数字-0还是字符串'-0'，add都保证结果的符号不丢失，这与toString中对-0的符号保留逻辑（src/compat/util/toString.ts）一脉相承。

参数与返回值说明

根据 参考文档 的定义：

Parameters

• value（number）：要相加的第一个值；
• other（number）：要相加的第二个值。

Returns

• number | string：两个值之和。如果参数中包含字符串，则返回字符串（拼接结果）；否则返回数字。

结合上述源码分析，实际返回类型可进一步细化为：

• 两个数字 →number（含NaN传播、-0符号保留）；
• 任一为字符串 →string（拼接结果）；
• 任一为undefined→ 返回有定义的那个值，或0；
• 对象 / Symbol → 参与运算后结果为NaN。

导入方式与迁移建议

add可以从兼容层整体入口导入：

import { add } from 'es-toolkit/compat';

该导出在 src/compat/compat.ts 中定义（export { add } from './math/add.ts';），并随 src/compat/index.ts 与 src/compat/toolkit.ts 一并暴露给使用方。

如果你的运行环境不支持 tree-shaking（如 CommonJS 的require()、React Native、或直接在 Node.js 中运行），可以像lodash/merge那样按单函数入口导入，只加载add及其依赖的文件：

import add from 'es-toolkit/compat/add'; // 或 const add = require('es-toolkit/compat/add');

这一模式在 compat 介绍文档 中有明确说明。

何时改用 es-toolkit 主包

正如兼容层文档强调的，迁移的最终目标是从es-toolkit/compat切换到类型严格的es-toolkit主包。如果你的代码只做纯粹的数值加法，完全不需要字符串拼接与undefined兼容语义，那么直接使用原生+运算符，或迁移到主包 API，会得到更小的打包体积与更快的运行时性能。

总结

es-toolkit/compat的add是一个"行为正确优先于性能"的兼容函数，其设计目标是与 Lodash 保持 1:1 语义。核心要点如下：

1. 数值相加：常规数字加法，NaN按 IEEE 754 语义传播；
2. 字符串拼接：任一参数为字符串即触发拼接，转换细节由 toString 精确复刻 Lodash（含-0符号保留、数组递归拼接、Symbol 字符串化）；
3. undefined 缺省语义：add(undefined, undefined)返回0，单边undefined返回另一参数；
4. 对象与 Symbol：经 toNumber 转换后产生NaN，不抛异常；
5. 性能提示：官方明确建议非兼容场景使用+运算符替代。

从 源码实现 到 测试用例，add的每一个边界行为都有据可查、有测可依，这也正是 compat 层"通过 Lodash 自身测试套件、行为完全一致"这一承诺的微观体现。

【免费下载链接】es-toolkitA modern JavaScript utility library that's 2-3 times faster and up to 97% smaller, a major upgrade to lodash.项目地址: https://gitcode.com/GitHub_Trending/es/es-toolkit