dot-prop

What is dot-prop?

The dot-prop npm package allows for getting, setting, and deleting properties from objects using dot-path notation. This can be particularly useful for accessing deeply nested properties without having to check each level of the object structure.

What are dot-prop's main functionalities?

Get a property

Retrieve a property from an object by specifying its path as a string.

const dotProp = require('dot-prop');
const object = {foo: {bar: 'a'}};
console.log(dotProp.get(object, 'foo.bar')); //=> 'a'

Set a property

Set a property on an object at a specified path, creating any necessary objects along the path.

const dotProp = require('dot-prop');
let object = {foo: {bar: 'a'}};
dotProp.set(object, 'foo.bar', 'b');
console.log(object.foo.bar); //=> 'b'

Delete a property

Delete a property from an object at a specified path.

const dotProp = require('dot-prop');
let object = {foo: {bar: 'a'}};
dotProp.delete(object, 'foo.bar');
console.log(object); //=> { foo: {} }

Check if an object has a property

Check if an object has a property at a specified path.

const dotProp = require('dot-prop');
const object = {foo: {bar: 'a'}};
console.log(dotProp.has(object, 'foo.bar')); //=> true

Other packages similar to dot-prop

lodash.get

Similar to the 'get' functionality of dot-prop, lodash.get allows accessing a property value of an object using a dot-path. While lodash offers a broader utility toolkit, dot-prop focuses specifically on dot-path property manipulation.

object-path

object-path provides similar functionality to dot-prop for getting, setting, and deleting properties using a dot-path notation. It offers a similar API but might have different performance characteristics or additional minor features.

README

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

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
}

Sparse arrays are supported. In general, avoid using sparse arrays.

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.