get-value

What is get-value?

The get-value npm package is used for safely retrieving nested values from an object or array. It is useful when dealing with deeply nested structures where checking for the existence of each level can be cumbersome. It allows for specifying paths to the desired value using a string or an array of keys/indices.

What are get-value's main functionalities?

Get nested values

Retrieve a nested value from an object using a string path.

const get = require('get-value');
const obj = { a: { b: { c: 'd' } } };
console.log(get(obj, 'a.b.c')); // 'd'

Use array paths

Retrieve a nested value using an array of keys as the path.

const get = require('get-value');
const obj = { a: { b: { c: 'd' } } };
console.log(get(obj, ['a', 'b', 'c'])); // 'd'

Specify default values

Provide a default value to return if the full path does not exist.

const get = require('get-value');
const obj = { a: { b: { c: 'd' } } };
console.log(get(obj, 'a.b.e', { default: 'default value' })); // 'default value'

Split string paths

Retrieve values from keys that include a dot or other special characters by specifying a custom separator.

const get = require('get-value');
const obj = { 'a.b': { c: 'd' } };
console.log(get(obj, 'a\.b.c', { separator: '\.' })); // 'd'

Other packages similar to get-value

lodash.get

lodash.get is a method from the Lodash library that provides similar functionality to get-value. It allows for retrieving nested values with a default option. Lodash is a larger utility library, so lodash.get is part of a broader suite of tools.

dot-prop

dot-prop is another package that allows for getting and setting nested properties. Unlike get-value, dot-prop also supports setting values. It uses a dot notation string as the path.

deep-get-set

deep-get-set is a package that not only gets but also sets deep values. It is less popular than get-value and does not have as many configuration options.

README

get-value

Use property paths (a.b.c) get a nested value from an object.

Benchmarks

This is 10x faster and more performant than dot-prop, and it passes all of the dot-prop tests.

Of the libs benchmarked, dot-prop was the least performant:

#1: deep
  get-value x 3,308,335 ops/sec ±1.32% (94 runs sampled)
  dot-prop x 197,631 ops/sec ±1.27% (94 runs sampled)
  getobject x 218,635 ops/sec ±1.51% (91 runs sampled)

#2: shallow
  get-value x 5,762,976 ops/sec ±1.21% (95 runs sampled)
  dot-prop x 695,892 ops/sec ±1.42% (95 runs sampled)
  getobject x 724,493 ops/sec ±1.46% (93 runs sampled)

Also, get-value supports escaping dots in paths, which is common when object keys are file paths with extensions, dot-prop does not.

Install with npm

npm i get-value --save

Install with bower

bower install get-value --save

Usage

var get = require('get-value');

var obj = {a: {b : {c: {d: 'foo'}}}};
get(obj, 'a.b.c');
//=> {d: 'foo'}

get(obj, 'a.b.c.d');
//=> 'foo'

Related projects

• has-value: Returns true if a value exists, false if empty. Works for booleans, functions, numbers, strings, nulls, objects and arrays. Other libs do this, but I needed one that would optionally not treat zero as empty. Also, this works with booleans and other valu
• set-value: Create nested values and any intermediaries dot notation ('a.b.c') paths.
• get-property: Get a nested property or its value from an object using simple a.b.c paths.
• get-object: Get a object from a property on a nested object.

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue

Running tests

Install dev dependencies.

npm i -d && npm test

Author

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright (c) 2014-2015 Jon Schlinkert
Released under the MIT license

---

This file was generated by verb-cli on March 25, 2015.