Mangler.aggregate() - DarthJDG/Mangler.js GitHub Wiki

Processes items in a loop and returns a single or grouped result.

Mangler.aggregate(iterable[, function[, options]])

Parameter	Type	Default	Description
iterable	Iterable		A container of items to process.
function	String Function	`'sum'`	The name of the aggregator function to use or a custom function.
options	Object		An object containing optional method modifiers.

Returns

The aggregated result.

Options

Property	Type	Default	Description
value	String Function false	false	Indicates how to get the values to aggregate. It is either a string path to process with Mangler.getPath() or a custom function in the form of `function(item)` returning the value to use. If `false`, the item from the `iterable` is used directly.
group	String Function false	false	Indicates how to get the group's name for grouped results. It is either a string path to process with Mangler.getPath() or a custom function in the form of `function(key, value)` returning the group name. If `false`, results will not be grouped and a single aggregated value is returned.

Built-in aggregator functions

'sum': The sum of all values. Aliases: '+', 'add'
'mul': Multiply all values together. Alias: '*'
'avg': The average of all values.
'cnt': The number of values found. Alias: 'count'
'min': The smallest value. Alias: '<'
'max': The largest value. Alias: '>'
'array': Returns an array of all values. Alias: '[]'

Simple examples

numbers = [6, 10, 20];
object = { one: 1, two: 2, three: 3 };

// Calculate the sum of an array of numbers
Mangler.aggregate(numbers, '+');  // returns 36

// Calculate the sum of object property values
Mangler.aggregate(object, '+');  // returns 6

products = [
	{ name: 'cherry', type: 'fruit', price: 3.00 },
	{ name: 'orange', type: 'fruit', price: 2.90 },
	{ name: 'grapes', type: 'fruit', price: 1.00 },
	{ name: 'carrot', type: 'vegetable', price: 2.00 },
	{ name: 'celery', type: 'vegetable', price: 3.50 }
];

// Calculate the average product price
Mangler.aggregate(products, 'avg', 'price');  // returns 2.48

// Collect all product names into an array
Mangler.aggregate(products, '[]', 'name');
// returns ['cherry', 'orange', 'grapes', 'carrot', 'celery']

Grouping

// Count products by type
Mangler.aggregate(products, 'cnt', { group: 'type' });
// returns object: { fruit: 3, vegetable: 2 }

// Get the lowest prices per product type
Mangler.aggregate(products, 'min', { value: 'price', group: 'type' });
// returns object: { fruit: 1.00, vegetable: 2.00 }

A custom grouping function takes two parameters (key, item) and returns a group name or identifier, which will become property names of the returned object. key is the array index or object property name of the item within the collection. The following example collects product names grouped by their first letter:

getFirstLetter = function(k, i) { return i.name[0]; };
Mangler.aggregate(products, '[]', { value: 'name', group: getFirstLetter });

Returns:

{
	c: ['cherry', 'carrot', 'celery'],
	g: ['grapes'],
	o: ['orange']
}

Custom aggregators

You can pass your own function instead of an aggregator name. The aggregator function gets called for each item in the collection and updates the result. The final result has to be calculated on every call, as there may or may not be further items in the collection. It only needs to generate a single result, grouping of items is handled outside of this function.

It takes three parameters:

k is the key of the item in the collection, either an array index or an object property.
v is the value to be processed. Either the item itself, or a part of it extracted by the value option.
a is the aggregator object, its value is preserved between aggregator calls. The value of a.count is the number of values processed so far, including the current one (starts at 1). The result has to be put into a.result. On the first call, a.result is undefined.

This is the built-in sum aggregator as an example:

function(k, v, a) {
	a.result = a.count === 1 ? v : a.result + v;
}