Deep Pluck

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

    Usage

    var deepPluck = require( '@stdlib/utils/deep-pluck' );
    

    deepPluck( arr, path[, options] )

    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 = deepPluck( 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 = deepPluck( 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 = deepPluck( 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 = deepPluck( arr, 'a|b|c', { 'sep': '|' } );
    // returns [ 1, 2 ]
    
    • If a key path does not exist, the function sets the plucked value as undefined.

      var arr = [
          { 'a': { 'b': { 'c': 1 } } },
          null,
          void 0,
          { 'a': { 'b': { 'c': 2 } } }
      ];
      
      var out = deepPluck( 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 = deepPluck( arr, 'a.b' );
      // returns [ { 'c': 2 }, { 'c': 3 } ]
      
      var bool = ( arr[ 0 ].a.b === out[ 0 ] );
      // returns true
      

      To prevent subsequent unintended mutation, use copy.

      var copy = require( '@stdlib/utils/copy' );
      
      var arr = [
          { 'a': { 'b': { 'c': 2 } } },
          { 'a': { 'b': { 'c': 3 } } }
      ];
      
      var out = deepPluck( 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 randu = require( '@stdlib/random/base/randu' );
    var round = require( '@stdlib/math/base/special/round' );
    var deepPluck = require( '@stdlib/utils/deep-pluck' );
    
    var arr;
    var out;
    var tmp;
    var i;
    
    arr = new Array( 100 );
    for ( i = 0; i < arr.length; i++ ) {
        tmp = {
            'a': {
                'b': {
                    'c': {
                        'd': null
                    }
                }
            }
        };
        tmp.a.b.c.d = round( randu()*100.0 );
        arr[ i ] = tmp;
    }
    
    // Pluck the deeply nested values:
    out = deepPluck( arr, 'a.b.c.d' );
    console.log( out );