es-toolkit BigInt sum 函数全解析任意精度求和的正确打开方式【免费下载链接】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-toolkites-toolkit为BigInt提供了专用的sum求和函数它位于es-toolkit/bigint子路径中用于精确计算BigInt数组的累加和。本文将以官方文档 docs/ja/reference/bigint/sum.md 为骨架结合 sum 源码、sum 测试用例 与相关姊妹函数带你掌握 BigInt 精确求和的 API 用法、边界语义与底层实现原理并理解它与普通number版本sum的本质差异。为什么 BigInt 求和需要独立的 sumJavaScript 的number类型基于 IEEE 754 双精度浮点数能够精确表示的安全整数范围仅为-9007199254740991到9007199254740991即Number.MAX_SAFE_INTEGER以内。一旦数值超出该范围累加结果就可能发生精度丢失。BigInt则可以表示任意大的整数且运算始终精确。因此 es-toolkit 在src/bigint目录下维护了一整套面向 BigInt 的工具函数包括sum、sumBy、clamp、range、median等全部从 src/bigint/index.ts 统一导出供使用者通过es-toolkit/bigint子路径按需引入。值得注意的是如官方文档所述该函数只能从es-toolkit/bigint导入这是为了避免与面向其他数值类型的同名函数例如面向number的 src/math/sum.ts产生潜在的命名冲突保证类型安全与 API 清晰。基本用法sum(nums)当你需要对一组BigInt求和时直接调用sum即可。它遍历数组并将所有元素累加返回总和。import { sum } from es-toolkit/bigint; // 基本求和 const numbers [1n, 2n, 3n, 4n, 5n]; const total sum(numbers); console.log(total); // 15n // 正负值混合求和 const values [-10n, 5n, -3n, 8n]; const result sum(values); console.log(result); // 0n从第一个示例可以看到[1n, 2n, 3n, 4n, 5n]累加得到15n第二个示例中正负数相互抵消结果精确为0n。函数签名非常简单只有唯一一个参数nums。空数组语义与可分割性分治求和的数学保证sum对空数组返回0n。这不仅是边界情况的兜底更赋予了函数一个重要的代数性质——可分割性将数组拆分成若干子数组分别求和再把各部分结果相加与直接对整个数组求和的结果完全一致。import { sum } from es-toolkit/bigint; const empty sum([]); console.log(empty); // 0n const first [1n, 2n]; const second [3n, 4n]; console.log(sum(first) sum(second) sum([...first, ...second])); // true这一性质在实践中有直接价值你可以安全地对大数组做分块chunk并行求和或分批处理流式数据最后汇总各批结果而无需担心结果不一致。测试用例 src/bigint/sum.spec.ts 中的ensures that adding the sums of two arrays equals the sum of their concatenation用例专门验证了该性质const array1: bigint[] []; const array2 [1n, 2n, 3n, 4n]; expect(sum(array1) sum(array2)).toBe(sum([...array1, ...array2]));注意空数组array1的参与恰好验证了0n是加法的单位元因此分割求和恒等式在任意拆分方式下都成立。超越 Number.MAX_SAFE_INTEGER 的精确累加number版本求和在数值较大时可能失去精度而BigInt无论数值多大都保持精确。文档给出两个典型示例import { sum } from es-toolkit/bigint; // 远超 Number.MAX_SAFE_INTEGER 仍然精确 const balances [9007199254740993n, 9007199254740993n]; console.log(sum(balances)); // 18014398509481986n // 以最小货币单位存储的支付总额 const paymentsInCents [129999n, 4550n, 87500n]; console.log(sum(paymentsInCents)); // 222049n其中9007199254740993n已经越过Number.MAX_SAFE_INTEGER9007199254740991两个值相加得到18014398509481986n结果分毫不差。若用普通number进行同样运算9007199254740993本身就会被舍入为9007199254740992精度从源头开始丢失。这一特性使 BigInt 求和天然适合以下场景最小货币单位的金额累计如以「分」为单位存储的支付流水paymentsInCents示例避免浮点误差导致的金额对账问题代币数量 / 余额计算区块链与加密货币场景中数量往往极大且要求逐位精确数据库标识符与 ID 运算超出安全整数范围的 ID 需要精确处理。参数与返回值参数nums类型readonly bigint[]说明需要计算总和的BigInt数组。声明为readonly意味着传入const数组或只读视图也不会产生类型错误函数内部不会修改原数组。返回值类型bigint说明返回数组中所有BigInt的总和空数组返回0n。源码级原理一个极简的线性累加器sum的实现位于 src/bigint/sum.ts完整代码如下export function sum(nums: readonly bigint[]): bigint { let result 0n; for (let i 0; i nums.length; i) { result nums[i]; } return result; }实现要点如下累加器初始化为0n与空数组返回0n的语义严格对应保证空数组不进入循环直接返回0n。普通for循环而非reduce从源码结构看这里采用索引遍历的for循环避免函数式调用带来的额外开销兼顾可读性与性能result nums[i]使用 BigInt 加法运算符天然不会发生浮点舍入。不修改输入数组函数只读遍历配合readonly bigint[]类型签名符合函数式工具库的不可变约定。与之配套的测试用例 src/bigint/sum.spec.ts 覆盖了五类行为普通求和、空数组返回0n、负 BigInt 混合、超过安全整数范围仍精确、以及分割求和恒等式可以作为你验证自身使用场景的参考。进阶与 sumBy 的组合使用当需要求和的BigInt不是数组元素本身、而是对象中的某个字段或通过函数推导出来时应使用配套的sumBy函数同样从es-toolkit/bigint导入文档见 docs/ja/reference/bigint/sumBy.md实现见 src/bigint/sumBy.tsimport { sumBy } from es-toolkit/bigint; // 汇总每个对象的字段 const accounts [{ balance: 10n }, { balance: 20n }, { balance: 30n }]; const total sumBy(accounts, account account.balance); console.log(total); // 60n // 索引作为第二个参数传入 const weights sumBy([a, b, c], (_, index) BigInt(index)); console.log(weights); // 3nsumBy(items, getValue)的签名与语义如下itemsreadonly T[]待遍历的元素数组getValue(element: T, index: number) bigint对每个元素返回一个待累加的BigInt元素索引会作为第二个参数传入回调返回值bigintgetValue返回值的总和空数组返回0n。从 sumBy 源码 可以看到它与sum的实现结构几乎一致只是累加前先经getValue(items[i], i)做一次映射。sum与sumBy一静一动覆盖了「直接对数组求和」与「按字段映射求和」两大典型场景。小结要点说明导入路径仅从es-toolkit/bigint导入避免与number版本冲突函数签名sum(nums: readonly bigint[]): bigint空数组返回0n且保证分割求和与整体求和恒等精度任意大整数累加均精确不受Number.MAX_SAFE_INTEGER限制典型场景最小货币单位金额、代币余额、数据库标识符等大整数累加姊妹函数字段映射求和使用sumByes-toolkit的 BigIntsum以极简实现提供了任意精度、语义明确的累加能力空数组返回0n的单位元设计保证了分治求和的正确性BigInt 本身的高精度特性则使其成为金融、加密与大整数计算场景中值得信赖的求和工具。若要进一步探索 BigInt 系列的其他工具可查看 src/bigint/index.ts 中的完整导出清单或阅读 docs/ja/reference/bigint 目录下的对应文档。【免费下载链接】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），仅供参考