Package Exports

nested-property

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (nested-property) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Nested property

Read, write or test a data structure's nested property via a string like 'my.nested.property'. It works through arrays and objects.

Installation

npm install nested-property

How to use

Require nested-property:

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

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

Caveat!

var object = {};
nestedProperty.set(object, "0.1.2", "new object");

// will not create arrays, but objects such as:
{
  "0": {
    "1": {
      "2": "new object"
    }
  }
}

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 a "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

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 valid to return true:

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

Unless the validPath option is set to true:

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

CHANGELOG

1.0.3 - 15 JAN 2020

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

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

LICENSE

MIT