Aggregation
calcSum / calcAvg / calcMedian / calcMax / calcMin — array aggregation.
Aggregation
Compute sum / average / median / max / min directly over a plain array or an array of objects. All results are strings.
API
calcSum(keyOrArr, list?): string
calcAvg(keyOrArr, list?): string
calcMedian(keyOrArr, list?): string
calcMax(keyOrArr, list?): string
calcMin(keyOrArr, list?): string
Try It Live
calcSum([1, 2, 3, 4]) // "10"
calcAvg([1, 2, 3]) // "2"
calcSum('price', [{ price: 10 }, { price: 20 }]) // "30"
calcMax([3, 10, 2]) // "10"
在线运行⌘/Ctrl + Enter 运行
Two Call Forms
1. Pass an array directly
calcSum([1, 2, 3]) // "6"
calcAvg([1, 2, 3]) // "2"
calcMax([3, 1, 2]) // "3"
calcMin([3, 1, 2]) // "1"
2. Pass a key + object array
const orders = [
{ price: 9.99, qty: 3 },
{ price: 19.99, qty: 2 },
{ price: 29.99, qty: 1 },
]
calcSum('price', orders) // "59.97"
calcAvg('price', orders) // "19.99"
calcMax('qty', orders) // "3"
Median
calcMedian returns the middle value of the sorted collection. When the count is even it returns the average of the two middle values, so it accepts a trailing { _precision }:
calcMedian([3, 1, 2]) // "2"
calcMedian([1, 2, 3, 4]) // "2.5" (average of the two middle values)
calcMedian([10, 20, 25], { _precision: 2 }) // "20"
calcMedian('score', [{ score: 80 }, { score: 90 }]) // "85"
Like the other aggregates, an empty collection returns
"0" rather than throwing.Combining with fmt
const totalRaw = calcSum('amount', records) // "12345.6789"
fmt(totalRaw, { decimals: 2, thousands: true }) // "12,345.67"
Handling Null Values
Real-world API responses often contain null / undefined. All five aggregation functions automatically skip null values without throwing:
const list = [{ p: 1 }, { p: null }, { p: 3 }, { p: undefined }]
calcSum('p', list) // "4"
calcAvg('p', list) // "2" (denominator counts only non-null items: 4 / 2)
calcMax('p', list) // "3"
// all values null ⇒ falls back to "0", no error thrown
calcSum('p', [{ p: null }]) // "0"
Note that
calcAvg's denominator is the count of non-null items — null values are excluded from both the numerator and the denominator.Alternative: addStr with Spread
For simple sum / product operations you don't necessarily need the aggregation functions — addStr / subStr / mulStr are all variadic and accept a spread array directly:
const nums = ['9.99', '19.99', '4.95']
addStr(...nums) // "34.93"
// extract a field from an object array
addStr(...orders.map(o => o.price)) // "59.97"
The difference is that
addStr does not skip null values and throws on error, whereas calcSum handles null values for you (and uses addStr internally to avoid large-number precision loss):addStr(...list.map(v => v.p)) // ❌ throws (array contains null)
addStr(...list.map(v => v.p).filter(v => v != null)) // ✅ "4", but requires manual filtering
calcSum('p', list) // ✅ "4", null values skipped automatically
Advantage over reduce
calcSum([0.1, 0.2, 0.3]) strictly returns "0.6". The native equivalent:
[0.1, 0.2, 0.3].reduce((a, b) => a + b, 0) // 0.6000000000000001