## Usage

```js
var groupArray = require('{%= name %}');
```

## Examples

```js
var arr = [
  {tag: 'one', content: 'A'},
  {tag: 'one', content: 'B'},
  {tag: 'two', content: 'C'},
  {tag: 'two', content: 'D'},
  {tag: 'three', content: 'E'},
  {tag: 'three', content: 'F'}
];

// group by the `tag` property
groupArray(arr, 'tag');
```

**results in:**

```js
{
  one: [
    {tag: 'one', content: 'A'},
    {tag: 'one', content: 'B'}
  ],
  two: [
    {tag: 'two', content: 'C'},
    {tag: 'two', content: 'D'}
  ],
  three: [
    {tag: 'three', content: 'E'},
    {tag: 'three', content: 'F'}
  ]
}
```

**Group by multiple, deeply nested properties**


```js
// given an array of object, like blog posts...
var arr = [
  { data: { year: '2016', tag: 'one', month: 'jan', day: '01'}, content: '...'},
  { data: { year: '2016', tag: 'one', month: 'jan', day: '01'}, content: '...'},
  { data: { year: '2016', tag: 'one', month: 'jan', day: '02'}, content: '...'},
  { data: { year: '2016', tag: 'one', month: 'jan', day: '02'}, content: '...'},
  { data: { year: '2016', tag: 'one', month: 'feb', day: '10'}, content: '...'},
  { data: { year: '2016', tag: 'one', month: 'feb', day: '10'}, content: '...'},
  { data: { year: '2016', tag: 'one', month: 'feb', day: '12'}, content: '...'},
  { data: { year: '2016', tag: 'one', month: 'feb', day: '12'}, content: '...'},
  { data: { year: '2016', tag: 'two', month: 'jan', day: '14'}, content: '...'},
  { data: { year: '2016', tag: 'two', month: 'jan', day: '14'}, content: '...'},
  { data: { year: '2016', tag: 'two', month: 'jan', day: '16'}, content: '...'},
  { data: { year: '2016', tag: 'two', month: 'jan', day: '16'}, content: '...'},
  { data: { year: '2016', tag: 'two', month: 'feb', day: '18'}, content: '...'},
  { data: { year: '2017', tag: 'two', month: 'feb', day: '18'}, content: '...'},
  { data: { year: '2017', tag: 'two', month: 'feb', day: '10'}, content: '...'},
  { data: { year: '2017', tag: 'two', month: 'feb', day: '10'}, content: '...'},
  { data: { year: '2017', tag: 'three', month: 'jan', day: '01'}, content: '...'},
  { data: { year: '2017', tag: 'three', month: 'jan', day: '01'}, content: '...'},
  { data: { year: '2017', tag: 'three', month: 'jan', day: '02'}, content: '...'},
  { data: { year: '2017', tag: 'three', month: 'jan', day: '02'}, content: '...'},
  { data: { year: '2017', tag: 'three', month: 'feb', day: '01'}, content: '...'},
  { data: { year: '2017', tag: 'three', month: 'feb', day: '01'}, content: '...'},
  { data: { year: '2017', tag: 'three', month: 'feb', day: '02'}, content: '...'},
  { data: { year: '2017', tag: 'three', month: 'feb', day: '02'}, content: '...'}
]
```

Pass a list or array of properties:

```js
groupArray(arr, 'data.year', 'data.tag', 'data.month', 'data.day');
```

**Results in something like this: (abbreviated)**

```js
{ '2016': 
   { one: 
      { jan: 
         { '01': 
            [ { data: { year: '2016', tag: 'one', month: 'jan', day: '01' },
                content: '...' },
              { data: { year: '2016', tag: 'one', month: 'jan', day: '01' },
                content: '...' } ],
           '02': 
            [ { data: { year: '2016', tag: 'one', month: 'jan', day: '02' },
                content: '...' },
              { data: { year: '2016', tag: 'one', month: 'jan', day: '02' },
                content: '...' } ] },
        feb: 
         { '10': 
            [ { data: { year: '2016', tag: 'one', month: 'feb', day: '10' },
                content: '...' },
              { data: { year: '2016', tag: 'one', month: 'feb', day: '10' },
                content: '...' } ],
           '12': 
            [ { data: { year: '2016', tag: 'one', month: 'feb', day: '12' },
                content: '...' },
              { data: { year: '2016', tag: 'one', month: 'feb', day: '12' },
                content: '...' } ] } },
     two: 
      { jan: 
         { '14': 
            [ { data: { year: '2016', tag: 'two', month: 'jan', day: '14' },
                content: '...' },
              { data: { year: '2016', tag: 'two', month: 'jan', day: '14' },
                content: '...' } ],
           '16': 
            [ { data: { year: '2016', tag: 'two', month: 'jan', day: '16' },
                content: '...' },
              { data: { year: '2016', tag: 'two', month: 'jan', day: '16' },
                content: '...' } ] },
        feb: 
         { '18': 
            [ { data: { year: '2016', tag: 'two', month: 'feb', day: '18' },
                content: '...' } ] } } },
  '2017': 
   { two: 
      { feb: 
         { '10': 
            [ { data: { year: '2017', tag: 'two', month: 'feb', day: '10' },
                content: '...' },
              { data: { year: '2017', tag: 'two', month: 'feb', day: '10' },
                content: '...' } ],
           '18': 
            [ { data: { year: '2017', tag: 'two', month: 'feb', day: '18' },
                content: '...' } ] } },
     three: 
      { jan: 
         { '01': 
            [ { data: { year: '2017', tag: 'three', month: 'jan', day: '01' },
                content: '...' },
              { data: { year: '2017', tag: 'three', month: 'jan', day: '01' },
                content: '...' } ],
           '02': 
            [ { data: { year: '2017', tag: 'three', month: 'jan', day: '02' },
                content: '...' },
              { data: { year: '2017', tag: 'three', month: 'jan', day: '02' },
                content: '...' } ] },
        feb: 
         { '01': 
            [ { data: { year: '2017', tag: 'three', month: 'feb', day: '01' },
                content: '...' },
              { data: { year: '2017', tag: 'three', month: 'feb', day: '01' },
                content: '...' } ],
           '02': 
            [ { data: { year: '2017', tag: 'three', month: 'feb', day: '02' },
                content: '...' },
              { data: { year: '2017', tag: 'three', month: 'feb', day: '02' },
                content: '...' } ] } } } }
```