local reference to supergroup namespace
exported function supergroup.group(recs, dim, opts)
Parameters:
recs must be an Array of Objects.
(list of records to be grouped)
dim must be a string or Function.
(either the property name to group by or a function returning a group by string or number)
opts is optional and must be an Object.
opts.childProp must be a String and has a default value of 'children'.
(If group ends up being hierarchical, this will be the property name of any children)
opts.excludeValues is optional and must be an Array of Strings.
(to exlude specific group values)
opts.preListRecsHook is optional and must be a function.
(run recs through this function before continuing processing)
opts.dimName is optional and must be a function.
(defaults to the value of dim
. If dim
is a function, the dimName will be ugly.)
Returns an Array of Values
(enhanced with all the List methods Avaailable as _.supergroup, Underscore mixin)
if dim is an array, use multiDimList to create hierarchical grouping
opts.multiValuedGroup is expected to be set automatically
The original records in this group are stored as an Array in the records property (should probably be a getter method).
val.records is enhanced with Underscore methods for convenience, but also with the supergroup method that's been mixed in to Underscore. So you can group this specific subset like: val.records.supergroup on FIX!!!!!!
pointless without recursion
nested groups, each dim is a level in hierarchy
class List
Native Array of groups with various added methods and properties. Methods described below.
class Value
Supergroup Lists are composed of Values which are String or Number objects representing group values. Methods described below.
sometimes a root value is needed as the top of a hierarchy
lookup a value in a list, or, if query is an array it is interpreted as a path down the group hierarchy
if group has children, can search down the tree
lookup more than one thing at a time
apply a function to the records of each group
returns an identical list with different group names
memberof enlightenedData sg.addUnderscoreMethods = function(arr) { (sg.underscoreMethodsToAddToArrays).each(function(methodName) { if ((arr).has(methodName)) return; Object.defineProperty(arr, methodName, { value: function() { var part = .partial([methodName], arr); var result = part.apply(null, .toArray(arguments)); if (.isArray(result)) sg.addListMethods(result); return result; }}); }); return arr; }; sg.underscoreMethodsToAddToArrays = [ "each", "map", "reduce", "find", "filter", "reject", "all", "every", "any", "some", "contains", "invoke", "pluck", "where", "findWhere", "max", "min", "shuffle", "sortBy", "groupBy", "countBy", "sortedIndex", "size", "first", "initial", "last", "rest", "compact", "flatten", "without", "uniq", "union", "intersection", "difference", "zip", "unzip", //"object", "indexOf", "lastIndexOf", "chain", "result" ];
Enhance arrays with {@link http://underscorejs.org/ Underscore} functions that work on arrays.
Parameters:
Returns an Array
(now enhanced Now can call Underscore functions as methods on the array, and if the return value is an array, it will also be enhanced.)
and Returns a whatever the underscore function would return
Example:
`enlightenedData.addUnderscoreMethods(['a','bb','ccc']) .pluck('length') . group.where({foo:bar}).invoke('baz')
didn't make this yet, just copied from above Value.prototype.descendants = function(level) { var ret = [this]; if (level !== 0 && this[childProp] && (!level || this.depth < level)) ret = .flatten(.map(this[childProp], function(c) { return c.leafNodes(level); }), true); return makeList(ret); };
var delim = opts.delim || '/'; return (this.parent ? this.parent.namePath(_.extend({},opts,{notLeaf:true})) : '') + ((opts.noRoot && this.depth===0) ? '' : (this + (opts.notLeaf ? delim : '')) )
CHANGING -- HOPE THIS DOESN'T BREAK STUFF (pedigree isn't documented yet)
memberof supergroup
Summarize records by a dimension
Parameters:
Records must be a list.
(to be summarized)
Dimension must be a numericDim.
(to summarize by)
memberof supergroup
Compare groups across two similar root notes
Parameters:
* **... must be a from.**
* **... must be a to.**
* **... must be a dim.**
* **... must be an opts.**<br/>(used by treelike and some earlier code)
memberof supergroup
Compare two groups by a dimension
Parameters:
* **... must be an A.**
* **... must be a B.**
* **... must be a dim.**
memberof supergroup
Concatenate two Values into a new one (??)
Parameters:
* **... must be a from.**
* **... must be a to.**
memberof supergroup
Sometimes a List gets turned into a standard array, sg.g., through slicing or sorting or filtering. addListMethods turns it back into a List
List
would be a constructor if IE10 supported
__proto__, so it pretends to be one instead.
Parameters:
can't easily subclass Array, so this explicitly puts the List methods on an Array that's supposed to be a List
//arr.proto = List.prototype; for(var method in List.prototype) { Object.defineProperty(arr, method, { value: List.prototype[method] }); }
Private
lodash createAggregator function, which lodash makes private Creates a function that aggregates a collection, creating an object or array composed from the results of running each element of the collection through a callback. The given setter function sets the keys and values of the composed object or array.
Parameters:
setter must be a Function.
(The setter function.)
retArray is optional, must be a boolean, and has a default value of false.
(A flag to indicate that the aggregator function should return an array.)
Returns a Function
(Returns the new aggregator function.)
Static memberOf _ and category Collections
Creates an object composed of keys generated from the results of running
each element of a collection through the callback. The corresponding value
of each key is an array of the elements responsible for generating the key.
The callback is bound to thisArg
and invoked with three arguments;
(value, index|key, collection).
If a property name is provided for callback
the created "_.pluck" style
callback will return the property value of the given element.
If an object is provided for callback
the created "_.where" style callback
will return true
for elements that have the properties of the given object,
else false
.
Parameters:
collection can be an Array, an Object, or a string.
(The collection to iterate over.)
callback is optional, can be a Function, an Object, or a string, and has a default value of identity.
(The function called per iteration. If a property name or object is provided it will be used to create a ".pluck" or ".where" style callback, respectively.)
thisArg is optional and must be a *.
(The this
binding of callback
.)
Returns an Object
(Returns the composed aggregate object.)
Example:
_.groupBy([4.2, 6.1, 6.4], function(num) { return Math.floor(num); }); // => { '4': [4.2], '6': [6.1, 6.4] }
_.groupBy([4.2, 6.1, 6.4], function(num) { return this.floor(num); }, Math); // => { '4': [4.2], '6': [6.1, 6.4] }
// using "_.pluck" callback shorthand _.groupBy(['one', 'two', 'three'], 'length'); // => { '3': ['one', 'two'], '5': ['three'] }
allows grouping by a field that contains an array of strings rather than just a string
supergroup.js
Author: Sigfried Gold
License: MIT
Version: 0.0.2
usage examples at http://sigfried.github.io/blog/supergroup