Data Distillery

Returns an object constructed using slices of an exisitng object.

Install:
npm i -S data-distillery
Alternate: npm i -S @webkrafters/data-distillery

Example

import distill from 'data-distillery'; 

const source = {
    address: {
        city: 'Test City',
        state: 'My Province'
    },
    matrix: [
        [ [ 0, 3, 1 ], [ 4, 0, 3 ] ],
        [ [ 4, 1, 9 ], [ 7, 4, 9 ] ],
        [ [ 8, 7, 3 ], [ 0, 3, 1 ] ]
    ],
    registered: {
        time: new Date(),
        timezone: 'Eastern Time'
    },
    tags: [ 'test', 'foo', 'bar', 'baz', 'boo', 'tap', 'bak' ]
};

// DEFAULT USAGE
// -------------
distill( source, [
    'matrix.1.1',
    'matrix[2].0',
    'address',
    'registered.timezone',
    'tags[4]',
    'matrix[0][1]'
]);
// returns distilled object => {
//   matrix: {
//     0: { 1: [ 4, 0, 3 ] },
//     1: { 1: [ 7, 4, 9 ] },
//     2: { 0: [ 8, 7, 3 ] }
//   },
//   address: {
//     city: 'Test City',
//     state: 'My Province'
//   },
//   registered: {
//     timezone: 'Eastern Time'
//   },
//   tags: {
//     4: 'boo'
//   }
// }

An Optional Parameter 3:

This function also accepts an optional third parameter which may either be

• a transformation function or
• an options object

The transformation function is of the the type:
<T>({ value } : PropertyInfo) : T => value;
This function is called on all values mapping to the provided property paths listed in the second argument.

The options object is of the type:

{
    arrays?: {
        preserve?: boolean // defaults to false
        sparse?: boolean // defaults to true
    },
    tranform?: <T>({ value } : PropertyInfo) : T => value;
}

Available Options
Property	Description
arrays	dascribes the strategy for handling array types encountered durring the distillation process.
transform	serves the same function as the afore-described transformation function.

Available arrays Options
Property	Description
preserve	when true will preserve properties of array types in the collected data and maintain the original indexes of values in the arrays. Note: altering the name of a propery within the distilled object will preclude that property, if an array, from array preservation.
sparse	when false will compact all arrays in the distilled data by removing all unassigned array elements. Note: this is active only when the options.arrays.preserve property is true.

Example: Property Tranformation.

// USING SAME SOURCE OBJECT AS ABOVE USAGE
// ---------------------------------------
distill( source, [
    'address',
    'registered.timezone',
    'tags[4]',
    'matrix[0][1]'
], function( p ) {
    if( typeof p.value === 'string' || p.value instanceof String ) {
        return p.value.toUpperCase();
    }
    return p.value;
} );
// returns distilled object => {
//   matrix: { 0: { 1: [ 4, 0, 3 ] } },
//   address: {
//     city: 'Test City',
//     state: 'My Province'
//   },
//   registered: {
//     timezone: 'EASTERN TIME'
//   },
//   tags: {
//     4: 'BOO'
//   }
// }

Example: Array Preservation.

// USING SAME SOURCE OBJECT AS IN PREVIOUS EXAMPLE.
// ------------------------------------------------
distill( source, [
    'matrix.1.1',
    'matrix[2].0',
    'address',
    'registered.timezone',
    'tags[4]',
    'matrix[0][1]'
], {
    arrays: {
        preserve: true
    }
} );
// returns distilled object => {
//   matrix: [
//    [ <empty>, [ 4, 0, 3 ] ],
//    [ <empty>, [ 7, 4, 9 ] ],
//    [ [ 8, 7, 3 ] ]
//   ],
//   address: {
//     city: 'Test City',
//     state: 'My Province'
//   },
//   registered: {
//     timezone: 'Eastern Time'
//   },
//   tags: [ <empty>, <empty>, <empty>, <empty>, 'boo' ]
// }

Example: Array Compaction.

// USING SAME SOURCE OBJECT AS IN PREVIOUS EXAMPLE.
// ------------------------------------------------
distill( source, [
    'matrix.1.1',
    'matrix[2].0',
    'address',
    'registered.timezone',
    'tags[4]',
    'matrix[0][1]'
], {
    arrays: {
        preserve: true,
        sparse: false
    }
}  );
// returns distilled object => {
//   matrix: [
//    [ [ 4, 0, 3 ] ],
//    [ [ 7, 4, 9 ] ],
//    [ [ 8, 7, 3 ] ]
//   ],
//   address: {
//     city: 'Test City',
//     state: 'My Province'
//   },
//   registered: {
//     timezone: 'Eastern Time'
//   },
//   tags: [ 'boo' ]
// }

License

MIT