Array Aggregation

a-calc provides aggregation functions for batch calculations over data arrays.

Function Overview

Function	Description	Use Case
calc_sum	Sum	Order totals, payroll
calc_avg	Average	Average score, average price
calc_max	Maximum	Highest score, largest order
calc_min	Minimum	Lowest score, minimum stock
calc_count	Count	Count valid records

Basic Syntax

All aggregation functions share the same signature:

import { calc_sum, calc_avg, calc_max, calc_min, calc_count } from "a-calc";

calc_sum(expression, dataArray);
calc_avg(expression, dataArray);
calc_max(expression, dataArray);
calc_min(expression, dataArray);
calc_count(expression, dataArray);

• expression: calculation expression, can include formatting
• dataArray: array of data objects

calc_sum

Evaluates the expression for each element and sums the results:

calc_sum("value", [{ value: 10 }, { value: 20 }, { value: 30 }]); // '60'

calc_sum("a * b", [
  { a: 2, b: 3 },
  { a: 4, b: 5 },
]); // '26' (6 + 20)

calc_sum("price | =2", items); // '60.00'

calc_avg

Evaluates the expression for each element and returns the average:

calc_avg("score", [{ score: 80 }, { score: 90 }, { score: 100 }]); // '90'

calc_avg("score | =2", scores); // '90.00'

calc_max

Returns the maximum value across all elements:

calc_max("price", [{ price: 99 }, { price: 199 }, { price: 149 }]); // '199'

calc_max("value", [{ value: -10 }, { value: -5 }, { value: -20 }]); // '-5'

calc_min

Returns the minimum value across all elements:

calc_min("stock", [{ stock: 50 }, { stock: 10 }, { stock: 30 }]); // '10'

calc_min("value", [{ value: -10 }, { value: -5 }, { value: -20 }]); // '-20'

calc_count

Counts elements where the expression result is truthy (non-zero):

calc_count("active", [{ active: 1 }, { active: 0 }, { active: 1 }]); // '2'

calc_count("stock > 0 ? 1 : 0", [{ stock: 10 }, { stock: 0 }, { stock: 5 }]); // '2'

Real-World Examples

E-commerce Order

const cartItems = [
  { name: "Phone", price: 699, quantity: 1, discount: 1 },
  { name: "Earbuds", price: 199, quantity: 2, discount: 0.9 },
  { name: "Case", price: 9.9, quantity: 3, discount: 0.8 },
];

const total = calc_sum("price * quantity * discount | =2", cartItems);
const avgPrice = calc_avg("price | =2", cartItems);
const maxPrice = calc_max("price", cartItems); // '699'
const minPrice = calc_min("price", cartItems); // '9.9'

Exam Scores

const scores = [
  { name: "Alice", score: 85 },
  { name: "Bob", score: 92 },
  { name: "Carol", score: 78 },
  { name: "Dave", score: 95 },
  { name: "Eve", score: 60 },
];

calc_avg("score | =1", scores); // '82.0'
calc_max("score", scores); // '95'
calc_min("score", scores); // '60'
calc_count("score >= 90 ? 1 : 0", scores); // '2'

Edge Cases

// Empty array returns '0'
calc_sum("value", []); // '0'
calc_avg("value", []); // '0'

// With formatting
calc_sum("value | =2", []); // '0.00'

// Error in any element returns the error value
calc_sum("a / b", [
  { a: 10, b: 2 },
  { a: 5, b: 0 }, // division by zero
]); // '-' (default error value)