Skip to content

sindresorhus/dot-prop

main
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
December 31, 2017 17:44
June 20, 2018 14:09
December 31, 2017 17:44
December 31, 2017 17:44
February 17, 2022 10:42
July 12, 2022 12:14
February 19, 2022 14:19
October 7, 2020 22:26
February 17, 2022 10:44
June 24, 2022 14:50
July 12, 2022 12:14
February 16, 2022 16:20

dot-prop

Get, set, or delete a property from a nested object using a dot path

Install

npm install dot-prop

Usage

import {getProperty, setProperty, hasProperty, deleteProperty} from 'dot-prop';

// Getter
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'

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

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

// Deleter
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'}}}

API

getProperty(object, path, defaultValue?)

Get the value of the property at the given path.

Returns the value if any.

setProperty(object, path, value)

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

Returns the object.

hasProperty(object, path)

Check whether the property at the given path exists.

Returns a boolean.

deleteProperty(object, path)

Delete the property at the given path.

Returns a boolean of whether the property existed before being deleted.

escapePath(path)

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

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

deepKeys(object)

Returns an array of every path. Plain objects 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.

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

const user = {
	name: {
		first: 'Richie',
		last: 'Bendall',
	},
};

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

object

Type: object | array

Object or array to get, set, or delete the path value.

You are allowed to pass in undefined as the object to the get and has functions.

path

Type: string

Path of the property in the object, using . to separate each nested key.

Use \\. if you have a . in the key.

The following path components are invalid and results in undefined being returned: __proto__, prototype, constructor.

value

Type: unknown

Value to set at path.

defaultValue

Type: unknown

Default value.


Get professional support for this package with a Tidelift subscription
Tidelift helps make open source sustainable for maintainers while giving companies
assurances about security, maintenance, and licensing for their dependencies.