Deep Pluck
Extract a nested property value from each element of an object array.
Installation
$ npm install utils-deep-pluck
Usage
var 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 = ;// returns [ 1, 2 ]
A key path
may be specified as either a string
or as an array
.
var arr ='a':012'a':345;var out = ;// 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 = ;// 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 = ;// returns [ 1, 2 ]
Notes
-
If a key path does not exist, the
function
sets the plucked value asundefined
.var arr ='a':'b':'c':1nullundefined'a':'b':'c':2;var out = ;// returns [ 1, undefined, undefined, 2 ] -
Extracted values are not cloned.
var arr ='a':'b':'c':2'a':'b':'c':3;var out = ;// returns [ {'c':2}, {'c':3} ]var bool = arr 0 ab === out 0 ;// returns trueTo prevent subsequent unintended mutation, use utils-copy.
var copy = ;var arr ='a':'b':'c':2'a':'b':'c':3;var out = ;// returns [ {'c':2}, {'c':3} ]// Perform a deep copy:out = ;var bool = arr 0 ab === out 0 ;// returns false
Examples
var round = ;var pluck = ;var arr = 100 ;var tmp;var i;for i = 0; i < arrlength; i++tmp = 'a':'b':'c':'d':null;tmpabcd = ;arr i = tmp;// Pluck the deeply nested values:var out = ;console;
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
Copyright
Copyright © 2016. Athan Reines.