expand-value   

> Get deeply nested values from an object, like dot-prop and get-value, but with support for advanced features like bracket-notation and more.

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

Install

Install with npm:

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

Usage

Similar to get-value and dot-prop (and passes all of the get-value unit tests), but supports more complex expressions for accessing deeply nested properties. For example, this library is used by Dry for resolving values in expressions in user-defined templates.

expand

Examples for using the main export (the expand function).

$3

Access nested properties using dot notation.

`ts
import expand from 'expand-value';

const data = { user: { name: 'Brian', username: 'doowb' }, key: 'username' };

console.log(expand(data, 'user.name')); //=> 'Brian'
console.log(expand(data, 'user.username')); //=> 'doowb'
`

$3

Access properties using bracket notation with string keys.

`ts
import expand from 'expand-value';

const data = { user: { name: 'Brian', username: 'doowb' }, key: 'username' };

console.log(expand(data, 'user["name"]')); //=> 'Brian'
console.log(expand(data, 'user["username"]')); //=> 'doowb'
`

$3

Use bracket notation with variables to access properties dynamically.

`ts
import expand from 'expand-value';

const data = {
user: { name: 'Brian', username: 'doowb' },
key: 'username'
};

console.log(expand(data, 'user[key]')); //=> 'doowb'
`

Get array values using computed property names.

`ts
import expand from 'expand-value';

const data = {
items: ['apple', 'banana', 'cherry'],
index: 2
};

console.log(expand(data, 'items[index]')); //=> 'cherry'
`

$3

Combine dot notation and bracket notation in the same path.

`ts
import expand from 'expand-value';

const data = { foo: { bar: { baz: 'correct' } } };

console.log(expand(data, 'foo["bar"].baz')); //=> 'correct'
`

$3

Access array elements using numeric indices.

`ts
import expand from 'expand-value';

const data = { items: ['first', 'second', 'third'] };

console.log(expand(data, 'items[0]')); //=> 'first'
console.log(expand(data, 'items[1]')); //=> 'second'
console.log(expand(data, 'items.2')); //=> 'third'
`

Access array elements using basic math expressions.

`ts
import expand from 'expand-value';

const data = { items: ['first', 'second', 'third', 'fourth'] };

console.log(expand(data, 'items[items.length - 1]')); //=> 'fourth'
console.log(expand(data, 'items[1 + 1]')); //=> 'third'
`

$3

Access array elements from the end using negative indices.

`ts
import expand from 'expand-value';

const data = { items: ['first', 'second', 'third'] };

console.log(expand(data, 'items[-1]')); //=> 'third'
console.log(expand(data, 'items[-2]')); //=> 'second'
`

$3

Handle special JavaScript number values like NaN and Infinity.

`ts
import expand from 'expand-value';

const data = {
'NaN': 'not a number',
'Infinity': 'infinite',
'-Infinity': 'negative infinite',
'-0': 'negative zero'
};

console.log(expand(data, 'NaN')); //=> 'not a number'
console.log(expand(data, 'Infinity')); //=> 'infinite'
console.log(expand(data, '-Infinity')); //=> 'negative infinite'
console.log(expand(data, '-0')); //=> 'negative zero'
`

$3

Access properties defined with Symbol keys.

`ts
import expand from 'expand-value';

const symbolKey = Symbol('mySymbol');
const data = { [symbolKey]: 'symbol value' };

console.log(expand(data, 'Symbol(mySymbol)')); //=> 'symbol value'
`

$3

Handle escaped characters in property names.

`ts
import expand from 'expand-value';

const data = { 'prop.with.dots': 'escaped value' };

console.log(expand(data, 'prop\\.with\\.dots')); //=> 'escaped value'
`

$3

Execute functions found in the property path.

`ts
import expand from 'expand-value';

const data = {
user: {
getName: function () {
return 'Brian';
},
context: 'user object'
}
};

console.log(expand(data, 'user.getName')); //=> 'Brian'
`

$3

Use custom helper functions to process values.

`ts
import expand from 'expand-value';

const data = { items: ['apple', 'banana', 'cherry'] };
const options = {
helpers: {
first: arr => (Array.isArray(arr) ? arr[0] : arr),
last: arr => (Array.isArray(arr) ? arr[arr.length - 1] : arr)
}
};

console.log(expand(data, 'items.first', options)); //=> 'apple'
console.log(expand(data, 'items.last', options)); //=> 'cherry'
`

$3

Provide fallback values when properties don't exist.

`ts
import expand from 'expand-value';

const data = { user: { name: 'Brian' } };

console.log(expand(data, 'user.missing', 'default value')); //=> 'default value'
console.log(expand(data, 'user.missing', { default: 'fallback' })); //=> 'fallback'
`

$3

Enable strict mode to throw errors for undefined variables.

`ts
import expand from 'expand-value';

const data = { user: { name: 'Brian' } };

try {
expand(data, 'user.missing', { strict: true });
} catch (error) {
console.log(error.message); //=> 'Variable is undefined: "missing"'
}
`

$3

Use custom separators instead of dots for property access.

`ts
import expand from 'expand-value';

const data = { user: { profile: { email: 'brian@example.com' } } };

console.log(expand(data, 'user->profile->email', { separator: '->' })); //=> 'brian@example.com'
`

$3

Use custom validation to control which properties can be accessed.

`ts
import expand from 'expand-value';

const data = {
public: { info: 'accessible' },
private: { secret: 'hidden' }
};

const options = {
isValid: (key, obj) => !key.startsWith('private')
};

console.log(expand(data, 'public.info', options)); //=> 'accessible'
console.log(expand(data, 'private.secret', options)); //=> undefined
`

$3

Use parentheses with range expressions for complex operations.

`ts
import expand from 'expand-value';

const data = { items: ['a', 'b', 'c', 'd', 'e'] };

console.log(expand(data, 'items[1..3]')); //=> ['b', 'c', 'd']
`

$3

Access properties with spaces or special characters using quoted strings.

`ts
import expand from 'expand-value';

const data = { 'property with spaces': 'value', 'special-chars!': 'works' };

console.log(expand(data, '"property with spaces"')); //=> 'value'
console.log(expand(data, "'special-chars!'")); //=> 'works'
`

$3

Resolve complex property chains with multiple levels of indirection.

`ts
import expand from 'expand-value';

const data = {
config: { theme: 'dark' },
themes: {
dark: { background: 'black', text: 'white' },
light: { background: 'white', text: 'black' }
},
setting: 'theme'
};

console.log(expand(data, 'themes[config[setting]].background')); //=> 'black'
`

.parse

`ts
import { parse } from 'expand-value';

const { ast } = parse('a.b.c');
console.log(ast);

// results in
{
type: 'root',
nodes: [
{ type: 'ident', value: 'a' },
{ type: 'separator', value: '.' },
{ type: 'ident', value: 'b' },
{ type: 'separator', value: '.' },
{ type: 'ident', value: 'c' }
]
}
`

About

$3

You might also be interested in these projects:

* dry: Dry is superset of the Liquid templating language, with first-class support for advanced inheritance features… more | homepage
* get-value: Use property paths like 'a.b.c' to get a nested value from an object. Even works… more | homepage.")

$3

| Commits | Contributor |
| --- | --- |
| 16 | jonschlinkert |
| 1 | aykutkardas |

$3

Jon Schlinkert

* GitHub Profile
* Twitter Profile
* LinkedIn Profile

$3

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

*

_This file was generated by verb-generate-readme, v0.8.0, on December 15, 2025._