Home Manual Reference Source Repository
import {Supergroup} from 'supergroup/src/supergroup.js'
public class | source

Supergroup

Extends:

Array → Supergroup

[http://sigfried.github.io/supergroup/ -- Tutorial and demo]

http://www.toptal.com/javascript/ultimate-in-memory-data-collection-manipulation-with-supergroup-js

usage examples at http://sigfried.github.io/blog/supergroup

Avaailable as _.supergroup, Underscore mixin

Class of grouped records masquerading as an array

A Supergroup object is an array of Value objects made by grouping an array of json objects by some set of properties or functions performed on those objects. Each Value represents a single group. Think of it as a SQL group by:

SELECT state, zipcode, count(*)
FROM addresses
GROUP BY state, zipcode

In Supergroup parlance: 'state' and 'zipcode' are dimensions; states ('Alabama', 'Alaska') and zipcodes (50032, 20002) are values, or, rather, value keys; and count(*) is an aggregation performed on the group. In regular SQL the underlying records represented in a group are not available, with Supergroup they are. So a Value has a key which is the text or number or any javascript object used to form the group. In a group of states, the key of each value would be a string, for zipdcodes it could be a number. (In previous versions of Supergroup, these were String and Number objects, but now they are string literals or anything else returnable by a grouping function.)

Value objects have a key, and valueobj.valueOf() will return that key, and valueobj.toString() will return the results of the default toString method on that key. valueobj.records is an array of the original javascript objects included in the group represented by the key. And valueobj.indexes is an array of the positions of those records in the original array.

  • Supergroup extends Array

    • Array values are Values
    • properties:
      • groupsmap: keys are the keys used to group Values, values are Values
      • recsmap: keys are index into original records array, values are orig records
    • methods:
      • rawValues: returns keys from groupsmap
  • Values

    • depth: same as the depth of its parentList (supergroup)
    • children: array of child Values collected in a supergroup (whose
             depth is one greater than the depth of this Value)
      

Static Method Summary

Static Public Methods
public static

makeRoot(name: *, depth: *, recs: *, dimName: *): *

There are time when you want to give your supergroup tree an explicit root, like when creating hierarchies in D3.

public static

wholeListNumeric(groups: *): *

Constructor Summary

Public Constructor
public

constructor(recs: Object[], dims: string[], dims: function[], opts: Object): Array of Values

Constructor groups records and builds tree structure

Member Summary

Public Members
public

dim: *

public

dimFunc: *

public

dimName: *

public
public

dims: *

public
public

parent: *

public

recsMap: *

public

root: *

Method Summary

Public Methods
public

aggregates(func: *, field: *, ret: *): *

public

asRootVal(name: *, dimName: *): *

public
public

d3NestMap(): *

public
public
public

leafNodes(level: *): *

public

lookup(query: *): *

lookup a value in a list, or, if query is an array it is interpreted as a path down the group hierarchy

public

lookupMany(query: *): *

public

namePaths(opts: *): *

public

rawValues(): *

public

rootList(func: *): *

public

singleLookup(query: *): *

public

state(): *

Static Public Methods

public static makeRoot(name: *, depth: *, recs: *, dimName: *): * source

There are time when you want to give your supergroup tree an explicit root, like when creating hierarchies in D3. In that case call supergroup like:

 let root = makeRoot('Tree Top', 0, recs), 
 let sg = new Supergroup({parent=root, dims=['state','zipcode']});

Otherwise Supergroup will make its own fake root with depth -1 instead of depth 0;

Params:

NameTypeAttributeDescription
name *
depth *
recs *
dimName *

Return:

*

public static wholeListNumeric(groups: *): * source

Params:

NameTypeAttributeDescription
groups *

Return:

*

Public Constructors

public constructor(recs: Object[], dims: string[], dims: function[], opts: Object): Array of Values source

Constructor groups records and builds tree structure

Params:

NameTypeAttributeDescription
recs Object[]

array of objects, raw data

dims string[]

property names to be used for grouping the raw objects

dims function[]

functions on raw objects that return any kind of object to be used for grouping. property names and functions can be mixed in dims array. For single-level grouping, a single property name or function can be used instead of an array.

opts.dimNames string[]
  • optional

array (or single value) of dim names of same length as dims. Property name dims are used as dimName by default.

opts Object
  • optional

options for configuring supergroup behavior. opts are forwarded to Value constructors and subgroup constructors.

opts.excludeValues Object[]
  • optional

to exlude specific group values

opts.preListRecsHook function
  • optional

run recs through this function before continuing processing currently unused

opts.truncateBranchOnEmptyVal function
  • optional

Return:

Array of Values

enhanced with all the List methods

Public Members

public dim: * source

public dimFunc: * source

public dimName: * source

public dimNames: * source

public dims: * source

public groupsMap: * source

public parent: * source

public recsMap: * source

public root: * source

Public Methods

public aggregates(func: *, field: *, ret: *): * source

Params:

NameTypeAttributeDescription
func *
field *
ret *

Return:

*

public asRootVal(name: *, dimName: *): * source

Params:

NameTypeAttributeDescription
name *
dimName *

Return:

*

public d3NestEntries(): * source

Return:

*

public d3NestMap(): * source

Return:

*

public flattenTree(): * source

Return:

*

public getLookupMap(): * source

Return:

*

public leafNodes(level: *): * source

Params:

NameTypeAttributeDescription
level *

Return:

*

public lookup(query: *): * source

lookup a value in a list, or, if query is an array it is interpreted as a path down the group hierarchy

Params:

NameTypeAttributeDescription
query *

Return:

*

public lookupMany(query: *): * source

Params:

NameTypeAttributeDescription
query *

Return:

*

public namePaths(opts: *): * source

Params:

NameTypeAttributeDescription
opts *

Return:

*

public rawValues(): * source

Return:

*

public rootList(func: *): * source

Params:

NameTypeAttributeDescription
func *

Return:

*

public singleLookup(query: *): * source

Params:

NameTypeAttributeDescription
query *

Return:

*

public state(): * source

Return:

*