dot-prop

Returns an array of every path. Non-empty plain objects and arrays are deeply recursed and are not themselves included.

This can be useful to help flatten an object for an API that only accepts key-value pairs or for a tagged template literal.

Parameter object

The object to iterate through.

Example 1

import {getProperty, deepKeys} from 'dot-prop';

const user = {
	name: {
		first: 'Richie',
		last: 'Bendall',
	},
	activeTasks: [],
	currentProject: null
};

for (const property of deepKeys(user)) {
	console.log(`${property}: ${getProperty(user, property)}`);
	//=> name.first: Richie
	//=> name.last: Bendall
	//=> activeTasks: []
	//=> currentProject: null
}

Delete the property at the given path.

Parameter object

Object or array to delete the path value.

Parameter path

Path of the property in the object, using . to separate each nested key. Use \\. if you have a . in the key. Array indices can be accessed using bracket notation ('users[0].name') or dot notation ('users.0.name'). Both syntaxes are equivalent and will create arrays when setting values. Numeric strings in dot notation (like 'users.0.name') are automatically coerced to numbers. When using array paths, numeric strings are normalized to numbers for simplicity (treating ['users', '0'] the same as ['users', 0]).

Returns

A boolean of whether the property existed before being deleted.

Example 1

import {deleteProperty} from 'dot-prop';

const object = {foo: {bar: 'a'}};
deleteProperty(object, 'foo.bar');
console.log(object);
//=> {foo: {}}

object.foo.bar = {x: 'y', y: 'x'};
deleteProperty(object, 'foo.bar.x');
console.log(object);
//=> {foo: {bar: {y: 'x'}}}

Escape special characters in a path. Useful for sanitizing user input.

Parameter path

The dot path to sanitize.

Example 1

import {getProperty, escapePath} from 'dot-prop';

const object = {
	foo: {
		bar: '👸🏻 You found me Mario!',
	},
	'foo.bar' : '🍄 The princess is in another castle!',
};
const escapedPath = escapePath('foo.bar');

console.log(getProperty(object, escapedPath));
//=> '🍄 The princess is in another castle!'

Get the value of the property at the given path.

Parameter object

Object or array to get the path value.

Parameter path

Path of the property in the object, using . to separate each nested key. Use \\. if you have a . in the key. Array indices can be accessed using bracket notation ('users[0].name') or dot notation ('users.0.name'). Both syntaxes are equivalent and will create arrays when setting values. Numeric strings in dot notation (like 'users.0.name') are automatically coerced to numbers. When using array paths, numeric strings are normalized to numbers for simplicity (treating ['users', '0'] the same as ['users', 0]).

Parameter defaultValue

Default value.

Example 1

import {getProperty} from 'dot-prop';

getProperty({foo: {bar: 'unicorn'}}, 'foo.bar');
//=> 'unicorn'

getProperty({foo: {bar: 'a'}}, 'foo.notDefined.deep');
//=> undefined

getProperty({foo: {bar: 'a'}}, 'foo.notDefined.deep', 'default value');
//=> 'default value'

getProperty({foo: {'dot.dot': 'unicorn'}}, 'foo.dot\\.dot');
//=> 'unicorn'

getProperty({foo: [{bar: 'unicorn'}]}, 'foo[0].bar');
//=> 'unicorn'

getProperty({foo: [{bar: 'unicorn'}]}, 'foo.0.bar');
//=> 'unicorn'

Check whether the property at the given path exists.

Parameter object

Object or array to test the path value.

Parameter path

Path of the property in the object, using . to separate each nested key. Use \\. if you have a . in the key. Array indices can be accessed using bracket notation ('users[0].name') or dot notation ('users.0.name'). Both syntaxes are equivalent and will create arrays when setting values. Numeric strings in dot notation (like 'users.0.name') are automatically coerced to numbers. When using array paths, numeric strings are normalized to numbers for simplicity (treating ['users', '0'] the same as ['users', 0]).

Example 1

import {hasProperty} from 'dot-prop';

hasProperty({foo: {bar: 'unicorn'}}, 'foo.bar');
//=> true

Parse a dot path into an array of path segments.

Parameter path

Path to parse. Use \\. if you have a . in the key. Array indices can be accessed using bracket notation ('users[0].name') or dot notation ('users.0.name'). Both syntaxes are equivalent. Numeric strings in dot notation (like 'users.0.name') are automatically coerced to numbers.

Returns

An array of path segments where numbers represent array indices and strings represent object keys.

Example 1

import {parsePath} from 'dot-prop';

parsePath('foo.bar');
//=> ['foo', 'bar']

parsePath('foo[0].bar');
//=> ['foo', 0, 'bar']

parsePath('foo.0.bar');
//=> ['foo', 0, 'bar']

parsePath('foo\\.bar');
//=> ['foo.bar']

// Use case: Iterate over path segments to build up a nested object
const path = 'users[0].profile.settings.theme';
const segments = parsePath(path);
//=> ['users', 0, 'profile', 'settings', 'theme']

Set the property at the given path to the given value.

Parameter object

Object or array to set the path value.

Parameter path

Path of the property in the object, using . to separate each nested key. Use \\. if you have a . in the key. Array indices can be accessed using bracket notation ('users[0].name') or dot notation ('users.0.name'). Both syntaxes are equivalent and will create arrays when setting values. Numeric strings in dot notation (like 'users.0.name') are automatically coerced to numbers. When using array paths, numeric strings are normalized to numbers for simplicity (treating ['users', '0'] the same as ['users', 0]).

Parameter value

Value to set at path.

Returns

The object.

Example 1

import {setProperty} from 'dot-prop';

const object = {foo: {bar: 'a'}};
setProperty(object, 'foo.bar', 'b');
console.log(object);
//=> {foo: {bar: 'b'}}

const foo = setProperty({}, 'foo.bar', 'c');
console.log(foo);
//=> {foo: {bar: 'c'}}

setProperty(object, 'foo.baz', 'x');
console.log(object);
//=> {foo: {bar: 'b', baz: 'x'}}

setProperty(object, 'foo.biz[0]', 'a');
console.log(object);
//=> {foo: {bar: 'b', baz: 'x', biz: ['a']}}

setProperty(object, 'foo.items.0', 'first');
console.log(object);
//=> {foo: {bar: 'b', baz: 'x', biz: ['a'], items: ['first']}}

Convert an array of path segments back into a path string.

Parameter pathSegments

Array of path segments where numbers represent array indices and strings represent object keys.

Parameter options

Options for stringifying the path.

Example 1

import {stringifyPath} from 'dot-prop';

stringifyPath(['foo', 'bar']);
//=> 'foo.bar'

stringifyPath(['foo', 0, 'bar']);
//=> 'foo[0].bar'

stringifyPath(['foo', '0', 'bar']);
//=> 'foo[0].bar'

// With preferDotForIndices option
stringifyPath(['foo', 0, 'bar'], {preferDotForIndices: true});
//=> 'foo.0.bar'

Convert an object with dot paths into a nested object.

Uses the same path rules and escaping as the rest of the API.

Parameter object

A plain object mapping paths to values.

Returns

A new nested object.

Example 1

import {unflatten} from 'dot-prop';

const flat = {
	'unicorn.name': 'Rainbow Dash',
	'unicorn.color': '🦄',
	'unicorn.treasures[0]': 'sparkles',
	'unicorn.treasures[1]': 'glitter',
};

unflatten(flat);
//=> {
//=> 	unicorn: {
//=> 		name: 'Rainbow Dash',
//=> 		color: '🦄',
//=> 		treasures: ['sparkles', 'glitter']
//=> 	}
//=> }