README

Deep Pluck

Extract a nested property value from each element of an object array.

Installation

$ npm install utils-deep-pluck

Usage

var pluck = require( 'utils-deep-pluck' );

pluck( arr, path[, opts] )

Extracts a nested property value from each element of an object array based on a key path.

var arr = [
    {'a':{'b':{'c':1}}},
    {'a':{'b':{'c':2}}}
];

var out = pluck( arr, 'a.b.c' );
// returns [ 1, 2 ]

A key path may be specified as either a string or as an array.

var arr = [
    {'a':[0,1,2]},
    {'a':[3,4,5]}
];

var out = pluck( arr, ['a',1] );
// returns [ 1, 4 ]

The function accepts the following options:

copy: boolean indicating whether to return a new data structure. Default: true.
sep: key path separator. Default: '.'.

By default, the function returns a new data structure. To mutate the input data structure (e.g., when input values can be discarded or when optimizing memory usage), set the copy option to false.

var arr = [
    {'a':{'b':{'c':1}}},
    {'a':{'b':{'c':2}}}
];

var out = pluck( arr, 'a.b.c', {'copy':false} );
// returns [ 1, 2 ]

var bool = ( arr[ 0 ] === out[ 0 ] );
// returns true

The default key path separator is .. To specify an alternative separator, set the sep option.

var arr = [
    {'a':{'b':{'c':1}}},
    {'a':{'b':{'c':2}}}
];

var out = pluck( arr, 'a|b|c', {'sep':'|'} );
// returns [ 1, 2 ]

Notes

If a key path does not exist, the function sets the plucked value as undefined.

var arr = [
    {'a':{'b':{'c':1}}},
    null,
    undefined,
    {'a':{'b':{'c':2}}}
];

var out = pluck( arr, 'a.b.c' );
// returns [ 1, undefined, undefined, 2 ]

Extracted values are not cloned.

var arr = [
    {'a':{'b':{'c':2}}},
    {'a':{'b':{'c':3}}}
];

var out = pluck( arr, 'a.b' );
// returns [ {'c':2}, {'c':3} ]

var bool = ( arr[ 0 ].a.b === out[ 0 ] );
// returns true

To prevent subsequent unintended mutation, use utils-copy.

var copy = require( 'utils-copy' );

var arr = [
    {'a':{'b':{'c':2}}},
    {'a':{'b':{'c':3}}}
];

var out = pluck( arr, 'a.b' );
// returns [ {'c':2}, {'c':3} ]

// Perform a deep copy:
out = copy( out );

var bool = ( arr[ 0 ].a.b === out[ 0 ] );
// returns false

Examples

var round = require( 'math-round' );
var pluck = require( 'utils-deep-pluck' );

var arr = new Array( 100 );
var tmp;
var i;

for ( i = 0; i < arr.length; i++ ) {
    tmp = {'a':{'b':{'c':{'d':null}}}};
    tmp.a.b.c.d = round( Math.random()*100 );
    arr[ i ] = tmp;
}

// Pluck the deeply nested values:
var out = pluck( arr, 'a.b.c.d' );

console.log( out );

To run the example code from the top-level application directory,

$ node ./examples/index.js

Tests

Unit

This repository uses tape for unit tests. To run the tests, execute the following command in the top-level application directory:

$ make test

All new feature development should have corresponding unit tests to validate correct functionality.

Test Coverage

This repository uses Istanbul as its code coverage tool. To generate a test coverage report, execute the following command in the top-level application directory:

$ make test-cov

Istanbul creates a ./reports/coverage directory. To access an HTML version of the report,

$ make view-cov

Browser Support

This repository uses Testling for browser testing. To run the tests in a (headless) local web browser, execute the following command in the top-level application directory:

$ make test-browsers

To view the tests in a local web browser,

$ make view-browser-tests

License

MIT license.

utils-deep-pluck

Usage no npm install needed!