get-value    

> Use property paths like 'a.b.c' to get a nested value from an object. Even works when keys have dots in them (no other dot-prop library can do this!).

Please consider following this project's author, Jon Schlinkert, and consider starring the project to show your :heart: and support.

Table of Contents

Install

Install with npm:

``sh
$ npm install --save get-value
`

Usage

See the unit tests for many more examples.

`js
const get = require('foo');
const obj = { a: { b: { c: { d: 'foo' } } } };

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

$3

Unlike other dot-prop libraries, get-value works when keys have dots in them:

`js
console.log(get({ 'a.b': { c: 'd' } }, 'a.b.c'));
//=> 'd'

console.log(get({ 'a.b': { c: { 'd.e': 'f' } } }, 'a.b.c.d.e'));
//=> 'f'
`

$3

`js
console.log(get({ a: { b: { c: { d: 'foo' } } }, e: [{ f: 'g' }, { f: 'h' }] }, 'e.1.f'));
//=> 'h'

console.log(get({ a: { b: [{ c: 'd' }] } }, 'a.b.0.c'));
//=> 'f'

console.log(get({ a: { b: [{ c: 'd' }, { e: 'f' }] } }, 'a.b.1.e'));
//=> 'f'
`

$3

`js
function foo() {}
foo.bar = { baz: 'qux' };

console.log(get(foo));
//=> { [Function: foo] bar: { baz: 'qux' } }

console.log(get(foo, 'bar'));
//=> { baz: 'qux' }

console.log(get(foo, 'bar.baz'));
//=> qux
`

$3

Slighly improve performance by passing an array of strings to use as object path segments (this is also useful when you need to dynamically build up the path segments):

`js
console.log(get({ a: { b: 'c' } }, ['a', 'b']));
//=> 'c'
`

Options

$3

Type: any

Default: undefined

The default value to return when get-value cannot resolve a value from the given object.

`js
const obj = { foo: { a: { b: { c: { d: 'e' } } } } };
console.log(get(obj, 'foo.a.b.c.d', { default: true })); //=> 'e'
console.log(get(obj, 'foo.bar.baz', { default: true })); //=> true
console.log(get(obj, 'foo.bar.baz', { default: false })); //=> false
console.log(get(obj, 'foo.bar.baz', { default: null })); //=> null

// you can also pass the default value as the last argument
// (this is necessary if the default value is an object)
console.log(get(obj, 'foo.a.b.c.d', true)); //=> 'e'
console.log(get(obj, 'foo.bar.baz', true)); //=> true
console.log(get(obj, 'foo.bar.baz', false)); //=> false
console.log(get(obj, 'foo.bar.baz', null)); //=> null
`

$3

Type: function

Default: true

If defined, this function is called on each resolved value. Useful if you want to do .hasOwnProperty or Object.prototype.propertyIsEnumerable.

`js
const isEnumerable = Object.prototype.propertyIsEnumerable;
const options = {
isValid: (key, obj) => isEnumerable.call(obj, key)
};

const obj = {};
Object.defineProperty(obj, 'foo', { value: 'bar', enumerable: false });

console.log(get(obj, 'foo', options)); //=> undefined
console.log(get({}, 'hasOwnProperty', options)); //=> undefined
console.log(get({}, 'constructor', options)); //=> undefined

// without "isValid" check
console.log(get(obj, 'foo', options)); //=> bar
console.log(get({}, 'hasOwnProperty', options)); //=> [Function: hasOwnProperty]
console.log(get({}, 'constructor', options)); //=> [Function: Object]
`

$3

Type: function

Default: String.split()

Custom function to use for splitting the string into object path segments.

`js
const obj = { 'a.b': { c: { d: 'e' } } };

// example of using a string to split the object path
const options = { split: path => path.split('/') };
console.log(get(obj, 'a.b/c/d', options)); //=> 'e'

// example of using a regex to split the object path
// (removing escaped dots is unnecessary, this is just an example)
const options = { split: path => path.split(/\\?\./) };
console.log(get(obj, 'a\\.b.c.d', options)); //=> 'e'
`

$3

Type: string|regex

Default: .

The separator to use for spliting the string (this is probably not needed when options.split is used).

`js
const obj = { 'a.b': { c: { d: 'e' } } };

console.log(get(obj, 'a.b/c/d', { separator: '/' }));
//=> 'e'

console.log(get(obj, 'a\\.b.c.d', { separator: /\\?\./ }));
//=> 'e'
`

$3

Type: function

Default: Array.join()

Customize how the object path is created when iterating over path segments.

`js
const obj = { 'a/b': { c: { d: 'e' } } };
const options = {
// when segs === ['a', 'b'] use a "/" to join, otherwise use a "."
join: segs => segs.join(segs[0] === 'a' ? '/' : '.')
};

console.log(get(obj, 'a.b.c.d', options));
//=> 'e'
`

$3

Type: string

Default: .

The character to use when re-joining the string to check for keys with dots in them (this is probably not needed when options.join is used). This can be a different value than the separator, since the separator can be a string or regex.

`js
const target = { 'a-b': { c: { d: 'e' } } };
const options = { joinChar: '-' };
console.log(get(target, 'a.b.c.d', options));
//=> 'e'
`

Benchmarks

_(benchmarks were run on a MacBook Pro 2.5 GHz Intel Core i7, 16 GB 1600 MHz DDR3)_.

get-value is more reliable and has more features than dot-prop, without sacrificing performance.

`


deep (175 bytes)

`

$3

Clone this library into a local directory:

`sh
$ git clone https://github.com/jonschlinkert/get-value.git
`

Then install devDependencies and run benchmarks:

`sh
$ npm install && node benchmark
`

Release history

$3

* Improved support for escaping. It's no longer necessary to use backslashes to escape keys.
* Adds options.default for defining a default value to return when no value is resolved.
* Adds options.isValid to allow the user to check the object after each iteration.
* Adds options.separator for customizing character to split on.
* Adds options.split for customizing how the object path is split.
* Adds options.join for customizing how the object path is joined when iterating over path segments.
* Adds options.joinChar for customizing the join character.

About

$3

You might also be interested in these projects:

* has-any-deep: Return true if key exists deeply on the given object. | key exists deeply on the given object. "" class="text-primary hover:underline" target="_blank" rel="noopener noreferrer">homepage
* has-any: Returns true if an object has any of the specified keys. | homepage
* has-value: Returns true if a value exists, false if empty. Works with deeply nested values using… more | homepage
* set-value: Create nested values and any intermediaries using dot notation ('a.b.c') paths. | 'a.b.c'`" class="text-primary hover:underline" target="_blank" rel="noopener noreferrer">homepage paths.")
* unset-value: Delete nested properties from an object using dot notation. | homepage

$3

| Commits | Contributor |
| --- | --- |
| 81 | jonschlinkert |
| 2 | ianwalter |
| 1 | doowb |

$3

Jon Schlinkert

* LinkedIn Profile
* GitHub Profile
* Twitter Profile

$3

Copyright © 2018, Jon Schlinkert.
Released under the MIT License.

*

_This file was generated by verb-generate-readme, v0.6.0, on March 07, 2018._