.verb.md

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][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: function () {
      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'

Release History

Read changelog.md for details on each release.