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
var obj = {
a: {
b: "d",
c: ["e", "f"],
'\u1200': 'unicode key',
'dot.dot': 'key'
}
};
var objectPath = require("object-path");
objectPath.get(obj, "a.b");
objectPath.get(obj, ["a", "dot.dot"]);
objectPath.get(obj, 'a.\u1200');
objectPath.coalesce(obj, ['a.z', 'a.d', ['a','b']], 'default');
objectPath.empty(obj, 'a.b');
objectPath.empty(obj, 'a.c');
objectPath.empty(obj, 'a');
objectPath.get(obj, "a.c.1");
objectPath.get(obj, ["a","c","1"]);
objectPath.get(obj, ["a.c.b"], "DEFAULT");
objectPath.set(obj, "a.h", "m");
objectPath.get(obj, "a.h");
objectPath.set(obj, "a.j.0.f", "m");
objectPath.insert(obj, "a.c", "m", 1);
objectPath.push(obj, "a.k", "o");
objectPath.ensureExists(obj, "a.k.1", "DEFAULT");
var oldVal = objectPath.ensureExists(obj, "a.b", "DEFAULT");
objectPath.del(obj, "a.b");
objectPath.del(obj, ["a","c",0]);
objectPath.has(obj, "a.b");
objectPath.has(obj, ["a","d"]);
var model = objectPath({
a: {
b: "d",
c: ["e", "f"]
}
});
model.get("a.b");
model.get(["a.c.b"], "DEFAULT");
model.del("a.b");
model.has("a.b");
How object-path
deals with inherited properties
By default object-path
will only access an object's own properties. Look at the following example:
var proto = {
notOwn: {prop: 'a'}
}
var obj = Object.create(proto);
objectPath.get(obj, 'notOwn.prop');
objectPath.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:
var objectPath = require("object-path");
var objectPathWithInheritedProps = objectPath.create({includeInheritedProps: true})
Alternatively, object-path
exposes an instance already configured to handle inherited properties (objectPath.withInheritedProps
):
var objectPath = require("object-path");
var objectPathWithInheritedProps = objectPath.withInheritedProps
Once you have the new instance, you can access inherited properties as you access other properties:
var proto = {
notOwn: {prop: 'a'}
}
var obj = Object.create(proto);
objectPath.withInheritedProps.get(obj, 'notOwn.prop');
objectPath.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