Get deeply nested values from an object, like dot-prop and get-value, but with support for advanced features like bracket-notation and more.
Install with npm:
$ npm install --save expand-valuePlease consider following this project's author, Jon Schlinkert, and consider starring the project to show your ❤️ and support.
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.
Examples for using the main export (the expand function).
Access nested properties using dot notation.
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'Access properties using bracket notation with string keys.
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'Use bracket notation with variables to access properties dynamically.
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.
import expand from 'expand-value';
const data = {
items: ['apple', 'banana', 'cherry'],
index: 2
};
console.log(expand(data, 'items[index]')); //=> 'cherry'Combine dot notation and bracket notation in the same path.
import expand from 'expand-value';
const data = { foo: { bar: { baz: 'correct' } } };
console.log(expand(data, 'foo["bar"].baz')); //=> 'correct'Access array elements using numeric indices.
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.
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'Access array elements from the end using negative indices.
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'Handle special JavaScript number values like NaN and Infinity.
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'Access properties defined with Symbol keys.
import expand from 'expand-value';
const symbolKey = Symbol('mySymbol');
const data = { [symbolKey]: 'symbol value' };
console.log(expand(data, 'Symbol(mySymbol)')); //=> 'symbol value'Handle escaped characters in property names.
import expand from 'expand-value';
const data = { 'prop.with.dots': 'escaped value' };
console.log(expand(data, 'prop\\.with\\.dots')); //=> 'escaped value'Execute functions found in the property path.
import expand from 'expand-value';
const data = {
user: {
getName: function () {
return 'Brian';
},
context: 'user object'
}
};
console.log(expand(data, 'user.getName')); //=> 'Brian'Use custom helper functions to process values.
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'Provide fallback values when properties don't exist.
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'Enable strict mode to throw errors for undefined variables.
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"'
}Use custom separators instead of dots for property access.
import expand from 'expand-value';
const data = { user: { profile: { email: 'brian@example.com' } } };
console.log(expand(data, 'user->profile->email', { separator: '->' })); //=> 'brian@example.com'Use custom validation to control which properties can be accessed.
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)); //=> undefinedUse parentheses with range expressions for complex operations.
import expand from 'expand-value';
const data = { items: ['a', 'b', 'c', 'd', 'e'] };
console.log(expand(data, 'items[1..3]')); //=> ['b', 'c', 'd']Access properties with spaces or special characters using quoted strings.
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'Resolve complex property chains with multiple levels of nesting.
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'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' }
]
}Use the async export to resolve promise-backed values while walking a path.
import expand from 'expand-value/async';
const data = {
config: Promise.resolve({ theme: 'dark' }),
themes: Promise.resolve({
dark: Promise.resolve({ background: 'black', text: 'white' }),
light: Promise.resolve({ background: 'white', text: 'black' })
}),
setting: Promise.resolve('theme')
};
console.log(await expand(data, 'setting')); //=> 'theme'
console.log(await expand(data, 'config[setting]')); //=> 'dark'
console.log(await expand(data, 'themes[config[setting]].background')); //=> 'black'
console.log(await expand(data, 'themes[config[setting]].text')); //=> 'white'Read changelog.md for details on each release.
- dry: Dry is superset of the Liquid templating language, with first-class support for advanced inheritance features… more | homepage
- eval-estree-expression: Safely evaluate JavaScript (estree) expressions, sync and async. | homepage
- get-value: Use property paths like 'a.b.c' to get a nested value from an object. Even works… more | homepage
- set-value: Set nested properties on an object using dot notation. | homepage
- whence: Add context awareness to your apps and frameworks by safely evaluating user-defined conditional expressions. Useful… more | homepage
Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
Please read the contributing guide for avice on opening issues, pull requests, and coding standards.
(This document was generated by verb-generate-readme (a verb generator), please don't edit the readme directly. Any changes to the readme must be made in .verb.md.)
To generate the readme and API documentation with verb:
$ npm install -g verb verb-generate-readme && verbInstall dev dependencies:
$ npm install -d && npm testJon Schlinkert
Copyright © 2026, Jon Schlinkert. MIT
This file was generated by verb-generate-readme, v0.1.31, on June 03, 2026.