For improved performance and interoperability with other libraries, you can also pass paths as arrays instead of strings. This avoids the overhead of parsing string paths.
import {getProperty, setProperty} from 'dot-prop';const object = { users: [ {name: 'Alice', role: 'admin'}, {name: 'Bob', role: 'user'} ]};// Using array paths - no parsing overheadgetProperty(object, ['users', 0, 'name']);//=> 'Alice'setProperty(object, ['users', 1, 'role'], 'moderator');console.log(object.users[1].role);//=> 'moderator'// Useful for interoperability with libraries that return paths as arraysconst
Array paths:
Avoid the parse/stringify cycle when you already have path segments
Work with all functions: getProperty, setProperty, hasProperty, deleteProperty
Numeric strings are automatically normalized to numbers for simplicity
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!'
parsePath(path)
Parse a dot path into an array of path segments.
Returns an array of path segments where numbers represent array indices and strings represent object keys.
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 objectconst path = 'users[0].profile.settings.theme';const segments = parsePath(path);//=> ['users', 0, 'profile', 'settings', 'theme']
stringifyPath(pathSegments, options?)
Convert an array of path segments back into a path string.
Returns a string path that can be used with other dot-prop functions.
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 optionstringifyPath(['foo', 0, 'bar'], {preferDotForIndices: true});//=> 'foo.0.bar'
pathSegments
Type: Array<string | number>
Array of path segments where numbers represent array indices and strings represent object keys.
options
Type: object
preferDotForIndices
Type: boolean
Default: false
When true, numeric indices will use dot notation instead of bracket notation when not the first segment.
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.
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 | Array<string | number>
Path of the property in the object.
String paths: Use . to separate each nested key. Use \\. if you have a . in the key. Array indices can be accessed using bracket notation (like 'users[0].name') or dot notation (like '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.
Array paths: Pass an array of path segments for better performance and interoperability. Numbers create arrays (like ['users', 0, 'name']). Numeric strings are normalized to numbers for simplicity. No parsing overhead.
The following path components are invalid and result in undefined being returned: __proto__, prototype, constructor.
[!IMPORTANT]
Sanitizing untrusted path input is your responsibility. Use escapePath to treat it as a literal key.
Apart from the components above, no protection against attacker-controlled paths is attempted. A path can reach anything reachable from the object, including inherited properties and built-ins. Only you know which parts of your object graph are safe to expose, so guard that where the path enters your program.
value
Type: unknown
Value to set at path.
defaultValue
Type: unknown
Default value.
unflatten(object)
Convert an object with dot paths into a nested object.
Uses the same path rules and escaping as the rest of the API.
[!IMPORTANT]
Numeric keys become array indices, so nodes with numeric keys turn into arrays. The deepKeys → unflatten round-trip is therefore lossy for such objects ({a: {0: 'x', name: 'y'}} → {a: ['x']}), and untrusted input can yield arrays where you expected objects.