Nested property

Traverse a deeply nested JS data structure to get, set values, or test if values are part of the data structure. Nested property offers a simple syntax to define a path to access a value with.

For instance:

const data = { 
  a: {
    b: [
      10,
      20
    ]
  }
 };

nestedProperty.get(data, "a.b.1"); // returns 20, or sdata.a.b[1]

The syntax also supports array wildcards to access all items within an array:

const array = [
  { ssn: "123-456-7890", name: "alice" },
  { ssn: "234-567-8901", name: "bob" },
  { ssn: "456-789-0123", name: "charlie" }
]

nestedProperty.set(array, "+.ssn", "<redacted>"); // sets all `ssn` values to <redacted>

Install

npm install nested-property

Use

Require nested-property:

var nestedProperty = require("nested-property");

nestedProperty.get(data, "path")

You can get a nested property from an object:

var object = {
  a: {
    b: {
      c: {
        d: 5
      }
    }
  }
};

nestedProperty.get(object, "a"); // returns object.a
nestedProperty.get(object, "a.b.c"); // returns object.a.b.c
nestedProperty.get(object, "a.b.c.d"); // returns 5
nestedProperty.get(object, "a.d.c"); // returns undefined
nestedProperty.get(object); // returns object
nestedProperty.get(null); // returns null

It also works through arrays:

var array = [{
  a: {
    b: [0, 1]
  }
  }];

nestedProperty.get(array, "0"); // returns array[0]
nestedProperty.get(array, "0.a.b"); // returns array[0].a.b
nestedProperty.get(array, "0.a.b.0"); // returns 0
nestedProperty.get(array, "1.a.b.c"); // returns undefined

You may also use wildcards to access multiple values:

var array = [
  { a: 0, b: 1, c: 2 },
  { a: 10, b: 11, c: 12 },
  { a: 20, b: 21, c: 22 }
]

nestedProperty.get(array, "+.b"); // returns [1, 11, 21]

nestedProperty.set(data, "path", value)

You can set a nested property on an object:

var object = {
  a: {
    b: {
      c: {
        d: 5
      }
    }
  }
};

nestedProperty.set(object, "a", 1); // object.a == 1
nestedProperty.set(object, "a.b.c", 1337); // object.a.b.c == 1337
nestedProperty.set(object, "e.f.g", 1); // object.e.f.g == 1, it creates the missing objects!
nestedProperty.set(object); // returns object
nestedProperty.set(null); // returns null

You can also set a nested property through arrays:

var array = [
 {
   a: [0, 1]
 }
];

nestedProperty.set(array, "0.a.0", 10); // array[0].a[0] == 10
nestedProperty.set(array, "0.b.c", 1337); // array[0].b.c == 1337

You may also use wildcards to set multiple values:

var array = [
  { a: 0, b: 1, c: 2 },
  { a: 10, b: 11, c: 12 },
  { a: 20, b: 21, c: 22 }
]

nestedProperty.set(array, "+.b", 0); // array[0].b === 0, array[1].b === 0, array[2].b === 0 

nestedProperty.has(data, "path")

You can also test if a data structure has a nested property:

var array = [
 {
   a: [0, 1]
 }
];

nestedProperty.has(array, "0.a"); // true
nestedProperty.has(array, "0.a.1"); // true
nestedProperty.has(array, "0.a.2"); // false
nestedProperty.has(array, "1.a.0"); // false

The example shows that it works through array, but of course, plain objects are fine too.

If it must be an "own" property (i.e. not in the prototype chain) you can use the own option:

function DataStructure() {}
DataStructure.prototype.prop = true;

var obj = new DataStructure();

nestedProperty.has(obj, "prop", { own: true }); // false
nestedProperty.has(obj, "prop"); // true

Alternatively, you can use the hasOwn function:

var obj = Object.create({ prop: true });

nestedProperty.hasOwn(obj, "prop"); // false

Just like other methods, you may also use array wildcards. For instance, testing if any item in an array has a given property:

var array = [
  { a: 0, b: 1, c: 2 },
  { a: 10, b: 11, c: 12, d: 13 },
  { a: 20, b: 21, c: 22 }
]

nestedProperty.has(array, "+.d"); // returns true, since array[1].d exists

nestedProperty.isIn(data, "path", value)

And finally, you can test if an object is on the path to a nested property:

var obj = {
    nested: [
        {
            property: true
        }
    ]
};

nestedProperty.isIn(obj, "nested.0.property", obj); // true
nestedProperty.isIn(obj, "nested.0.property", obj.nested); // true
nestedProperty.isIn(obj, "nested.0.property", obj.nested[0]); // true

nestedProperty.isIn(obj, "nested.0.property", {}); // false

The path doesn't have to be completely valid to return true, as long as the value exists within the valid portion.

nestedProperty.isIn(obj, "nested.0.property.foo.bar.path", obj.nested[0]); // true

Unless the validPath option is set to true, in this case the full path needs to be valid:

nestedProperty.isIn(obj, "nested.0.property.foo.bar.path", obj.nested[0], { validPath: true }); // false

Note that if instead of an object you give it the value of the nested property, it'll return true:

nestedProperty.isIn(obj, "nested.0.property", obj.nested[0].property); // true
nestedProperty.isIn(obj, "nested.0.property", true); // true

nestedProperty.ObjectPrototypeMutationError

Note that it's not permitted to mutate Object.prototype:

nestedProperty.set({}, '__protot__.a', 1); // throws nestedProperty.ObjectPrototypeMutationError

LICENSE

MIT

CHANGELOG

4.0.0 - 30 SEP 2020

• Add type definitions for typescript projects. Note that this is the loosest definition possible to allow typescript projects to compile without errors. Also embeds some useful documentation

3.0.0 - 27 SEP 2020

• Prevent mutation of Object.prototype to address a security issue. (Full report coming soon)

2.0.2 - 22 AUG 2020

• Upgrade dependencies to fix vulnerabilites reported by dependa bot

2.0.0 - 18 FEB 2020

• Official 2.0.0 release, removing the -beta1 version
• Extract CHANGELOG into a separate file as per #13

2.0.0-beta1 - 02 FEB 2020

• Add array wildcard + to access all properties nested within an array. For example:

// sets all `name` property in the array to "<redacted>"
nestedProperty.set(array, "+.name", "<redacted>"); 

Closes Issue #8. Thanks vemuez for the suggestion!

2.0.1 - 23 JUNE 2020

• Upgrading dev dependencies to fix npm audit issues

2.0.0 - 18 FEB 2020

• Add support for array wildcards
• Add support for older browsers using babel

1.0.4 - 18 JAN 2020

• Fix license field in package.json. Thanks zr87 for raising the issue!

1.0.3 - 15 JAN 2020

• replaced usage of const with var to maintain support of pre-ES6 JS interpreters. Thanks stefanorie for the contribution!

1.0.2 - 20 NOV 2019

• Update package-lock and remove yarn.lock to remove security alerts on dependencies

1.0.1 - 22 JUNE 2019

• Update to mocha 6.4.1 to remove security alerts on dependencies

1.0.0 - 22 JUNE 2019

• Breaking Change: When calling set() with an integer in the path and nested-property creates an object at the location, the object is now an array instead of an object. Hopefully, no user of the nested-property package should have been expecting to see an object instead of an array, but this constitutes a breaking changes, hence the major update in the semver.

Thanks igor-barbosa for the suggestion: PR #2

0.0.7 - 09 AUG 2016

• Remove unused require('assert'), thanks to Nilz11

0.0.6 - 01 MAR 2015

• Fix a bug where an invalid path to search an object into is invalid and the isInNestedProperty would throw an error instead of return false

0.0.5 - 19 JAN 2015

• Add isIn, to tell if an object is on the path to a nested property.

0.0.4 - 15 JAN 2015

• Add {own: true} option to .has to ensure that a nested property isn't coming from the prototype chain
• Add hasOwn, that calls .has with the {own: true} option

0.0.3 - 14 JAN 2015

• Add has with tests and documentation