Shape Collection

Utility for manipulating data in arrays of objects.

Installation

Run npm install shape-collection --save

Usage

import { shape } from 'shape-collection';

const arr = [{
  users: ['aa', 'bb']
}, {
  users: ['kk', 'zz', 'xyz']
}];

const users = shape(arr).reduceTo('users').fetch();

// users contains:
// ["aa", "bb", "kk", "zz", "xyz"]

Syntax

const arr = [{ id: 'abc' }, { id: 'xyz' }]
shape(arr).filterByProp('id', 'abc').fetchIndex(0);

Parameters

• items - array (of objects), REQUIRED

Shape API

All methods available under the shape API, morph data into arrays. To retrieve the morphed array, call fetch() at the end of your sequence. Then, you can take full advantage of array-extras methods like map, sort and filter. All methods, which accept key as property, support nested key look-ups like user.details.createdAt. This works for nested object properties only.

fetch

Function. Returns the morphed collection.

fetchIndex(index)

Function. Returns item at a specific index from the morphed collection.

filterByUnique(key)

Function. Filters the collection by unique values for given key:

import { shape } from 'shape-collection';

const arr = [{
  id: 1,
  users: ['aa', 'bb']
}, {
  id: 2,
  users: ['kk', 'zz', 'xyz']
}, {
  id: 1,
  users: ['aa', 'bb']
}, {
  id: 2,
  users: ['kk', 'zz', 'xyz']
}];

const uniqueItems = shape(arr).filterByUnique('id').fetch();

// uniqueItems contains:
// [{ id: 1, users: ['aa', 'bb'] }, { id: 2, users: ['kk', 'zz', 'xyz'] }]

This function filters by first found unique value. All subsequent identical values are ignored.

filterByDuplicate(key)

Function. Filter the collection by duplicate values for given key:

const arr = [{
  id: 1,
  type: 'b',
  users: ['aa', 'bb']
}, {
  id: 1,
  type: 'a',
  users: ['kk', 'zz', 'xyz']
}, {
  id: 3,
  type: 'a',
  users: ['kk', 'zz', 'xyz']
}];

const duplicates = shape(arr).filterByDuplicate('id').fetch();

// duplicates contains:
// [{ id: 1, type: 'b' ... }, { id: 1, type: 'a' ... }]

filterByProp(key, value)

Function. Filter collection by key-value pair comparison:

const arr = [{
  id: 1,
  type: 'b',
  users: ['aa', 'bb']
}, {
  id: 1,
  type: 'a',
  users: ['kk', 'zz', 'xyz']
}, {
  id: 3,
  type: 'a',
  users: ['kk', 'zz', 'xyz']
}];

const item = shape(arr).filterByProp('id', 3).fetch();

// item contains:
// [{ id: 3, type: 'a' ... }]

sortBy(key, type, direction)

Function. Sort collection by key, type and direction:

const arr = [{
  id: 1,
  type: 'b',
  users: ['aa', 'bb']
}, {
  id: 1,
  type: 'a',
  users: ['kk', 'zz', 'xyz']
}, {
  id: 3,
  type: 'a',
  users: ['kk', 'zz', 'xyz']
}];

const sortedById = shape(arr).sortBy('id', 'number', 'desc').fetch();

// sortedById contains:
// [{ id: 3 ... }, { id: 1 ... }, { id: 1 ... }]

Params type and direction can be configured with the following options:

• type: string

  • number
  • string
  • date - new Date() fields
  • combo - combination of two string fields

• direction: string

  • asc
  • desc

reduceTo(key, augmenter = (item, prop, key) => {})

Function. Reduce collection to another collection:

const arr = [{
  id: 1,
  type: 'b',
  users: ['aa', 'bb']
}, {
  id: 2,
  type: 'a',
  users: ['kk', 'zz', 'xyz']
}, {
  id: 3,
  type: 'a',
  users: ['ff', 'hhh', 'eeee', 'kk']
}];

const users = shape(arr).reduceTo('users').fetch();

// users contains:
// ["aa", "bb", "kk", "zz", "xyz", "ff", "hhh", "eeee", "kk"]

You can also pass an optional augmenter function to reduceTo as a second argument. An augmenter is a special function, invoked only when you are reducing arrays of objects to another array of objects. It can be useful, when you want to extract a nested array of objects but also want to keep track of their parent object after they have been reduced. Here's an example:

const users = [{
    id: 1,
    type: 'day_group',
    grades: {
        english: 4,
        driving: 7
    }
}, {
    id: 2,
    type: 'evening_group',
    grades: {
        english: 6,
        driving: 10
    }
}, {
    id: 3,
    type: 'weekend_group',
    grades: {}
}];

const gradesWithUserId = shape(users)
    .reduceTo('grades', ({ id }) => ({ id })) // reduce to grades and augment items with parent id
    .fetch();

// gradesWithUserId contains
/*
[
    { english: 4, driving: 7, id: 1 },
    { english: 6, driving: 10, id: 2 }
]

The augmenter method must return an object, which is then merged into the respective reduced item. With an augmenter you can add identifiers to your morphed collections.

The following params are passed to augmenter:

• item - the parent item
• prop - the currently reduced-to property of the parent item
• key - the key passed to reduceTo function

Examples

const groups = [{
   id: 1,
   type: 'day_group',
   events: {
       summerBreak: {
           startDate: '22/06/2018',
           endDate: '22/09/2018'
       },
       winterBreak: {
           startDate: '22/12/2018',
           endDate: '02/01/2019'
       }
   },
   users: [{
       id: 'abc',
       name: 'John Doe',
       age: 33,
       exams: [{
           name: 'English B1',
           score: 5
       }, {
           name: 'Exam B',
           score: 10
       }]
   }, {
       id: 'xyz',
       name: 'Teddy Williams',
       age: 42,
       exams: [{
           name: 'English B1',
           score: 6
       }, {
           name: 'Exam B',
           score: 3
       }]
   }, {
       id: 'zzz',
       name: 'Jake McCoy',
       age: 14,
       exams: []
   }]
}, {
   id: 2,
   type: 'evening_group',
   events: {
       summerBreak: {
           startDate: '12/06/2018',
           endDate: '12/09/2018'
       },
       winterBreak: {
           startDate: '01/12/2018',
           endDate: '01/02/2019'
       }
   },
   users: [{
       id: 'yyy',
       name: 'Teddy Smith',
       age: 23,
       exams: [{
           name: 'English B1',
           score: 3
       }, {
           name: 'Exam B',
           score: 7
       }]
   }, {
       id: 'jjj',
       name: 'Jane Doe',
       age: 42,
       exams: [{
           name: 'English B1',
           score: 4
       }, {
           name: 'Exam B',
           score: 1
       }]
   }]
}, {
   id: 3,
   type: 'weekend_group',
   users: []
}];

const examsSortedByName = shape(groups)
    .reduceTo('users')
    .reduceTo('exams')
    .sortBy('name')
    .fetch();

// examsSortedByName contains
/*
[
    {name: "English B1", score: 5},
    {name: "English B1", score: 6},
    {name: "English B1", score: 3},
    {name: "English B1", score: 4},
    {name: "Exam B", score: 10},
    {name: "Exam B", score: 3},
    {name: "Exam B", score: 7},
    {name: "Exam B", score: 1}
]
*/

const examsSortedByScore = shape(groups)
    .reduceTo('users')
    .reduceTo('exams')
    .sortBy('score', 'number', 'desc')
    .fetch();

// examsSortedByScore contains
/*
[
    {name: "Exam B", score: 10},
    {name: "Exam B", score: 7},
    {name: "English B1", score: 6},
    {name: "English B1", score: 5},
    {name: "English B1", score: 4},
    {name: "Exam B", score: 3},
    {name: "English B1", score: 3},
    {name: "Exam B", score: 1}
]
*/

// getting nested props from object fields, using comma-separated keys
const summerBreaks = shape(groups).reduceTo('events.summerBreak').fetch();

// summerBreaks contains
/*
[
    {startDate: "22/06/2018", endDate: "22/09/2018"},
    {startDate: "12/06/2018", endDate: "12/09/2018"}
]
*/

const nestedItems = [{
    id: 1,
    type: 'a',
    items: [{
        id: 11,
        type: 'aa',
        items: [{
            id: 111,
            type: 'aaa',
            items: [{
                id: 1111,
                type: 'aaaa'
            }]
        }]
    }]
}, {
    id: 2,
    type: 'b',
    items: [{
        id: 22,
        type: 'bb',
        items: [{
            id: 222,
            type: 'bbb',
            items: [{
                id: 2222,
                type: 'bbbb'
            }]
        }]
    }]
}, {
    id: 3,
    type: 'c',
    items: [{
        id: 33,
        type: 'cc',
        items: [{
            id: 333,
            type: 'ccc'
        }]
    }]
}];

const nestedItems = shape(nestedItems)
    .reduceTo('items')
    .reduceTo('items')
    .reduceTo('items')
    .fetch();

// nestedItems contains:
/*
[
    {id: 1111, type: "aaaa"},
    {id: 2222, type: "bbbb"}
]
*/

const users = [{
    id: 1,
    name: 'User A',
    grades: {
        english: 4,
        driving: 7
    }
}, {
    id: 2,
    name: 'User B',
    grades: {
        english: 6,
        driving: 10
    }
}, {
    id: 3,
    name: 'User C',
    grades: {}
}];

const usersSortedByEnglishScore = shape(testData.users)
    .sortBy('grades.english', 'number', 'desc') // sort collection by nested property
    .fetch();

// usersSortedByEnglishScore contains
/*
[
{ id: 2, grades: { english: 6 ... } },
{ id: 2, grades: { english: 4 ... } },
{ id: 2, grades: {} },
]
*/