object-path

Access deep properties using a path

Changelog

0.11.8

• SECURITY FIX. Fix a prototype pollution vulnerability in the del(), empty(), push(), insert() functions when using the "inherited props" mode (e.g. when a new object-path instance is created with the includeInheritedProps option set to true or when using the withInheritedProps default instance. To help with preventing this type of vulnerability in the client code, also the get() function will now throw an exception if an object's magic properties are accessed. The vulnerability does not exist in the default instance exposed by object path (e.g objectPath.del()) if using version >= 0.11.0.

0.11.6

• SECURITY FIX. Fix a circumvention of the security fix released in 0.11.5 when non-string/non-numeric values are used in the path (e.g. op.withInheritedProps.set({}, [['__proto__'], 'polluted'], true))

0.11.5

• SECURITY FIX. Fix a prototype pollution vulnerability in the set() function when using the "inherited props" mode (e.g. when a new object-path instance is created with the includeInheritedProps option set to true or when using the withInheritedProps default instance. The vulnerability does not exist in the default instance exposed by object path (e.g objectPath.set()) if using version >= 0.11.0.

0.11.0

• Introduce ability to specify options and create new instances of object-path
• Introduce option to control the way object-path deals with inherited properties (includeInheritedProps)
• New default object-path instance already configured to handle not-own object properties (withInheritedProps)

0.10.0

• Improved performance of get, set, and push by 2x-3x
• Introduced a benchmarking test suite
• BREAKING CHANGE: del, empty, set will not affect not-own object's properties (made them consistent with the other methods)

Install

Node.js

npm install object-path --save

Bower

bower install object-path --save

Typescript typings

typings install --save dt~object-path

Usage

1
2var obj = {
3  a: {
4    b: "d",
5    c: ["e", "f"],
6    '\u1200': 'unicode key',
7    'dot.dot': 'key'
8  }
9};
10
11var objectPath = require("object-path");
12
13//get deep property
14objectPath.get(obj, "a.b");  //returns "d"
15objectPath.get(obj, ["a", "dot.dot"]);  //returns "key"
16objectPath.get(obj, 'a.\u1200');  //returns "unicode key"
17
18//get the first non-undefined value
19objectPath.coalesce(obj, ['a.z', 'a.d', ['a','b']], 'default');
20
21//empty a given path (but do not delete it) depending on their type,so it retains reference to objects and arrays.
22//functions that are not inherited from prototype are set to null.
23//object instances are considered objects and just own property names are deleted
24objectPath.empty(obj, 'a.b'); // obj.a.b is now ''
25objectPath.empty(obj, 'a.c'); // obj.a.c is now []
26objectPath.empty(obj, 'a'); // obj.a is now {}
27
28//works also with arrays
29objectPath.get(obj, "a.c.1");  //returns "f"
30objectPath.get(obj, ["a","c","1"]);  //returns "f"
31
32//can return a default value with get
33objectPath.get(obj, ["a.c.b"], "DEFAULT");  //returns "DEFAULT", since a.c.b path doesn't exists, if omitted, returns undefined
34
35//set
36objectPath.set(obj, "a.h", "m"); // or objectPath.set(obj, ["a","h"], "m");
37objectPath.get(obj, "a.h");  //returns "m"
38
39//set will create intermediate object/arrays
40objectPath.set(obj, "a.j.0.f", "m");
41
42//will insert values in array
43objectPath.insert(obj, "a.c", "m", 1); // obj.a.c = ["e", "m", "f"]
44
45//push into arrays (and create intermediate objects/arrays)
46objectPath.push(obj, "a.k", "o");
47
48//ensure a path exists (if it doesn't, set the default value you provide)
49objectPath.ensureExists(obj, "a.k.1", "DEFAULT");
50var oldVal = objectPath.ensureExists(obj, "a.b", "DEFAULT"); // oldval === "d"
51
52//deletes a path
53objectPath.del(obj, "a.b"); // obj.a.b is now undefined
54objectPath.del(obj, ["a","c",0]); // obj.a.c is now ['f']
55
56//tests path existence
57objectPath.has(obj, "a.b"); // true
58objectPath.has(obj, ["a","d"]); // false
59
60//bind object
61var model = objectPath({
62  a: {
63    b: "d",
64    c: ["e", "f"]
65  }
66});
67
68//now any method from above is supported directly w/o passing an object
69model.get("a.b");  //returns "d"
70model.get(["a.c.b"], "DEFAULT");  //returns "DEFAULT"
71model.del("a.b"); // obj.a.b is now undefined
72model.has("a.b"); // false
73

How object-path deals with inherited properties

By default object-path will only access an object's own properties. Look at the following example:

1var proto = {
2  notOwn: {prop: 'a'}
3}
4var obj = Object.create(proto);
5
6//This will return undefined (or the default value you specified), because notOwn is
7//an inherited property
8objectPath.get(obj, 'notOwn.prop');
9
10//This will set the property on the obj instance and not the prototype.
11//In other words proto.notOwn.prop === 'a' and obj.notOwn.prop === 'b'
12objectPath.set(obj, 'notOwn.prop', 'b');

To configure object-path to also deal with inherited properties, you need to create a new instance and specify the includeInheritedProps = true in the options object:

1var objectPath = require("object-path");
2var objectPathWithInheritedProps = objectPath.create({includeInheritedProps: true})

Alternatively, object-path exposes an instance already configured to handle inherited properties (objectPath.withInheritedProps):

1var objectPath = require("object-path");
2var objectPathWithInheritedProps = objectPath.withInheritedProps

Once you have the new instance, you can access inherited properties as you access other properties:

1var proto = {
2  notOwn: {prop: 'a'}
3}
4var obj = Object.create(proto);
5
6//This will return 'a'
7objectPath.withInheritedProps.get(obj, 'notOwn.prop');
8
9//This will set proto.notOwn.prop to 'b'
10objectPath.set(obj, 'notOwn.prop', 'b');

NOTE: For security reasons object-path will throw an exception when trying to access an object's magic properties (e.g. __proto__, constructor) when in "inherited props" mode.

Immutability

If you are looking for an immutable alternative of this library, you can take a look at: object-path-immutable

Credits

• Mario Casciaro - Author
• Paulo Cesar - Major contributor