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 ❤️ and support.

Install

Install with npm:

$ npm install --save expand-value

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

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).

Basic Property Access

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'

Bracket Notation

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'

Computed Property Access

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'

Mixed Notation

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'

Array Index Access

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'

Negative Array Indices

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'

Special Number Values

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'

Symbol Properties

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'

Escaped Characters

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'

Function Properties

Execute functions found in the property path.

import expand from 'expand-value';

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

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

Helper Functions

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'

Fallback Values

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'

Strict Mode

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"'
}

Custom Separators

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'

Property Validation

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)); //=> undefined

Range Expressions

Use 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']

Quoted Property Names

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'

Chained Property Resolution

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'

.parse

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' }
  ]
}

Async expand

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'

Options

default

Type: any

Default: undefined

Value to return when the property cannot be resolved. A non-object third argument is treated as the default value.

console.log(expand({ user: {} }, 'user.name', { default: 'Anonymous' })); //=> 'Anonymous'
console.log(expand({ user: {} }, 'user.name', 'Anonymous')); //=> 'Anonymous'

fallback

Type: any

Default: undefined

Alias for default. When both options are defined, default takes precedence.

console.log(expand({ user: {} }, 'user.name', { fallback: 'Anonymous' })); //=> 'Anonymous'

helpers

Type: Record<string, Function>

Default: built-in helpers

Define functions that transform the current value when a matching property cannot be resolved. Custom helpers are merged with the built-in helpers when expressions are compiled, and may override them.

const options = {
  helpers: {
    uppercase: value => String(value).toUpperCase()
  }
};

console.log(expand({ user: { name: 'Brian' } }, 'user.name.uppercase', options)); //=> 'BRIAN'

The async export awaits helper results.

isValid

Type: (key, object) => boolean

Default: undefined

Function called before a property is accessed. Return false to prevent access and return the fallback value. For safety, __proto__, constructor, and prototype are always rejected.

const options = {
  isValid: (key, object) => !String(key).startsWith('_')
};

console.log(expand({ public: 'yes', _private: 'no' }, 'public', options)); //=> 'yes'
console.log(expand({ public: 'yes', _private: 'no' }, '_private', options)); //=> undefined

newlines

Type: boolean

Default: true

Set to false to omit newline nodes from the token stream and AST returned by parse.

const { tokens } = parse('foo\nbar', { newlines: false });

console.log(tokens.some(token => token.type === 'newline')); //=> false

onResolve

Type: (object, key) => void

Default: undefined

Function called before each segment is resolved in a dot-separated or array path. The async export awaits the returned value.

const keys = [];
const options = {
  onResolve: (object, key) => keys.push(key)
};

expand({ user: { name: 'Brian' } }, 'user.name', options);
console.log(keys); //=> ['user', 'name']

resolve

Type: (target, prop, value, state) => any

Default: undefined

Function called after each property is read, including when the property value is undefined. target is the object providing the property, prop is the current path segment, and value is the value read from the target. state contains the full segments array and the current segment index.

Use this option to provide, unwrap, or transform intermediate values while a path is resolved. The original value is used when the function returns null or undefined. The async export awaits both property values and the value returned by resolve.

const data = {
  user: {}
};

const options = {
  resolve(target, prop, value, state) {
    if (prop === 'profile' && value === undefined) {
      return { name: 'Brian' };
    }

    return value;
  }
};

console.log(expand(data, 'user.profile.name', options)); //=> 'Brian'

separator

Type: string

Default: .

Define a custom separator for parsing and resolving property paths.

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

console.log(expand(data, 'user/profile/name', { separator: '/' })); //=> 'Brian'

strict

Type: boolean

Default: false

Throw an error when a path segment resolves to undefined and no fallback value is defined.

const data = { user: {} };

expand(data, 'user.name', { strict: true });
//=> Error: Variable is undefined: "name"

Release History

Read changelog.md for details on each release.

About

Contributing

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

Please read the contributing guide for advice on opening issues, pull requests, and coding standards.

Running Tests

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

$ npm install && npm test

Building docs

(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)

To generate the readme, run the following command:

$ npm install -g verbose/verb#dev verb-generate-readme && verb

Related projects

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
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

Contributors

Commits	Contributor
25	jonschlinkert
1	aykutkardas

Author

Jon Schlinkert

License

This file was generated by verb-generate-readme, v0.8.0, on July 10, 2026.

Name		Name	Last commit message	Last commit date
Latest commit History 27 Commits
.github		.github
examples		examples
src		src
test		test
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.verb.md		.verb.md
LICENSE		LICENSE
README.md		README.md
changelog.md		changelog.md
eslint.config.mts		eslint.config.mts
index.ts		index.ts
package.json		package.json
prettier.config.js		prettier.config.js
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

expand-value

Install

Usage

expand

Basic Property Access

Bracket Notation

Computed Property Access

Mixed Notation

Array Index Access

Negative Array Indices

Special Number Values

Symbol Properties

Escaped Characters

Function Properties

Helper Functions

Fallback Values

Strict Mode

Custom Separators

Property Validation

Range Expressions

Quoted Property Names

Chained Property Resolution

.parse

Async expand

Options

default

fallback

helpers

isValid

newlines

onResolve

resolve

separator

strict

Release History

About

Related projects

Contributors

Author

License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages