docs/reference/bigint/sum.md
BigInts)Returns the sum of all elements in an array of BigInts.
const total = sum(numbers);
::: info
This function is available exclusively from es-toolkit/bigint to avoid potential conflicts with similar functions for other numeric types.
:::
sum(nums)Use sum when you want to add up BigInts. It adds every element of the array together and returns the total.
import { sum } from 'es-toolkit/bigint';
// Basic sum
const numbers = [1n, 2n, 3n, 4n, 5n];
const total = sum(numbers);
console.log(total); // 15n
// Negative and positive values mixed
const values = [-10n, 5n, -3n, 8n];
const result = sum(values);
console.log(result); // 0n
An empty array returns 0n, so splitting an array and summing the parts always gives the same answer as summing the whole.
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
Unlike number, BigInt stays exact no matter how large the values get, which makes it a good fit for money in the smallest currency unit, token amounts, or database identifiers.
import { sum } from 'es-toolkit/bigint';
// Well past Number.MAX_SAFE_INTEGER, still exact
const balances = [9007199254740993n, 9007199254740993n];
console.log(sum(balances)); // 18014398509481986n
// Total of payments stored in the smallest currency unit
const paymentsInCents = [129999n, 4550n, 87500n];
console.log(sum(paymentsInCents)); // 222049n
nums (readonly bigint[]): The array of BigInts to sum.(bigint): Returns the sum of all BigInts in the array. Returns 0n for empty arrays.