es-toolkit/compat 的 add 函数Lodash 兼容的加法实现与源码剖析【免费下载链接】es-toolkitA modern JavaScript utility library thats 2-3 times faster and up to 97% smaller, a major upgrade to lodash.项目地址: https://gitcode.com/GitHub_Trending/es/es-toolkitadd是 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);其中valuenumber为第一个相加的值othernumber为第二个相加的值。从 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.tsif (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 语义渲染为undefinedSymbol 调用Symbol.prototype.toStringtoString([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.tsif (value undefined other undefined) { return 0; } if (value undefined || other undefined) { return value ?? other; }规则可以概括为参数组合返回值说明add(undefined, undefined)0两个参数都缺省时返回0add(6, undefined)6只有一个参数定义时返回该值add(undefined, 4)4同上返回有定义的那个参数add(6)6省略第二个参数等价于传undefined测试 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对非常规输入的处理结果。对象转换为 NaNadd.spec.ts 验证了对象参数的行为add(0, {}); // NaN add({}, 0); // NaN普通对象经Number()转换后为NaN参与加法后整个结果变为NaN。这是toNumber语义的自然结果。Symbol 转换为 NaNadd.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输入结果1 / resultadd(0)0Infinityadd(0)0Infinityadd(-0)-0-Infinityadd(-0)-0-Infinity无论参数是数字-0还是字符串-0add都保证结果的符号不丢失这与toString中对-0的符号保留逻辑src/compat/util/toString.ts一脉相承。参数与返回值说明根据 参考文档 的定义Parametersvaluenumber要相加的第一个值othernumber要相加的第二个值。Returnsnumber | 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 语义。核心要点如下数值相加常规数字加法NaN按 IEEE 754 语义传播字符串拼接任一参数为字符串即触发拼接转换细节由 toString 精确复刻 Lodash含-0符号保留、数组递归拼接、Symbol 字符串化undefined 缺省语义add(undefined, undefined)返回0单边undefined返回另一参数对象与 Symbol经 toNumber 转换后产生NaN不抛异常性能提示官方明确建议非兼容场景使用运算符替代。从 源码实现 到 测试用例add的每一个边界行为都有据可查、有测可依这也正是 compat 层通过 Lodash 自身测试套件、行为完全一致这一承诺的微观体现。【免费下载链接】es-toolkitA modern JavaScript utility library thats 2-3 times faster and up to 97% smaller, a major upgrade to lodash.项目地址: https://gitcode.com/GitHub_Trending/es/es-toolkit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
es-toolkit/compat 的 add 函数：Lodash 兼容的加法实现与源码剖析
es-toolkit/compat 的 add 函数Lodash 兼容的加法实现与源码剖析【免费下载链接】es-toolkitA modern JavaScript utility library thats 2-3 times faster and up to 97% smaller, a major upgrade to lodash.项目地址: https://gitcode.com/GitHub_Trending/es/es-toolkitadd是 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);其中valuenumber为第一个相加的值othernumber为第二个相加的值。从 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.tsif (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 语义渲染为undefinedSymbol 调用Symbol.prototype.toStringtoString([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.tsif (value undefined other undefined) { return 0; } if (value undefined || other undefined) { return value ?? other; }规则可以概括为参数组合返回值说明add(undefined, undefined)0两个参数都缺省时返回0add(6, undefined)6只有一个参数定义时返回该值add(undefined, 4)4同上返回有定义的那个参数add(6)6省略第二个参数等价于传undefined测试 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对非常规输入的处理结果。对象转换为 NaNadd.spec.ts 验证了对象参数的行为add(0, {}); // NaN add({}, 0); // NaN普通对象经Number()转换后为NaN参与加法后整个结果变为NaN。这是toNumber语义的自然结果。Symbol 转换为 NaNadd.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输入结果1 / resultadd(0)0Infinityadd(0)0Infinityadd(-0)-0-Infinityadd(-0)-0-Infinity无论参数是数字-0还是字符串-0add都保证结果的符号不丢失这与toString中对-0的符号保留逻辑src/compat/util/toString.ts一脉相承。参数与返回值说明根据 参考文档 的定义Parametersvaluenumber要相加的第一个值othernumber要相加的第二个值。Returnsnumber | 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 语义。核心要点如下数值相加常规数字加法NaN按 IEEE 754 语义传播字符串拼接任一参数为字符串即触发拼接转换细节由 toString 精确复刻 Lodash含-0符号保留、数组递归拼接、Symbol 字符串化undefined 缺省语义add(undefined, undefined)返回0单边undefined返回另一参数对象与 Symbol经 toNumber 转换后产生NaN不抛异常性能提示官方明确建议非兼容场景使用运算符替代。从 源码实现 到 测试用例add的每一个边界行为都有据可查、有测可依这也正是 compat 层通过 Lodash 自身测试套件、行为完全一致这一承诺的微观体现。【免费下载链接】es-toolkitA modern JavaScript utility library thats 2-3 times faster and up to 97% smaller, a major upgrade to lodash.项目地址: https://gitcode.com/GitHub_Trending/es/es-toolkit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
