nested-structure

This module is useful for when you have to work with nested object structures. For example:

//Typical
var isValid = item && item[0] && item[0].propertyName === true;

//Nested-structure
var ns = require('nested-structure');
var isValid = ns(item).get('0.propertyName').value() === true;

It's also useful for avoiding Cannot read property X of undefined:

var item = {};

if(item.customer.id === 1) {
//Cannot read property 'id' of undefined
}

var ns = require('nested-structure');
if(ns(item).get('customer.id').value() === 1) {
//No error
)

Lodash

The module completely inherits Lodash onto its prototype. While there may not be use cases for a lot of lodash's functions, this still allows for convenient syntax such as:

var item = {Customers: [{Name: 'John', Rights: false}, {Name: 'Lisa', Rights: true}, {Name: 'Rob', Rights: true}]};
var customerNames = ns(item).get('Customers').map('Name').value(); //John, Lisa, Rob

var customersWithRights = ns(item).get('Customers').filter(function(item) { return item.Rights === true; }).map('Name').value(); //Lisa, Rob

You can keep chaining lodash functions without having to call .chain.

Note: set, get and has are internal functions of nested-structure and are not inherited from Lodash.

Syntax

nested-structure uses dotnotation and also supports asterix (*) for arrays:

var ns = require('nested-structure');
var item = {Customers: [{Name: 'John'}, {Name: 'Lisa'}, {Name: 'Rob'}]};
var customerNames = ns(item).get('Customers.*.Name').value(); //John, Lisa, Rob

API

You must always call .value() to get the value of the current chain. Calling .value(true) will indicate that are you done with the instance and will auto-cleanup references to your original object.

get(nestedString, defaultValue)

Will return the values found matching the specified nestedstring, or defaultValue.

var ns = require('nested-structure');
var item = {one: {two: {three: {value: 123}}}};
ns(item).get('one.two.three.value').value(); //123
ns(item).get('one.two.three.value.doesNotExist', 999).value(); //999
ns(item).get('one.two.three.value.doesNotExist').value(); //undefined

var items = [{one: {two: {three: {value: 123 }}}},  {one: {two: {three: {value: 321}}}}, ];
var values = ns(items).get('*.one.two.three.value').value(); //[123, 321]

set(nestedString, value, options)

Will set the property value to value based on the nestedString. The property to be set is always the last field in dotnation from the nestedString.

nestedString can be an object for when you need to set values for several paths.

Value: Can be a function. The Function receives the current value of the property and the propertyname that is going to be set.

options

• Force: When explicitly defined as true, it will set all required properties on the object. When false, will not set the value unless the property already exists on the object.

var ns = require('nested-structure');
var item = {one: {two: { }};
ns(item).set('one.two.value', 123); //item = {one: {two: {value: 123}}};

//This will NOT change the object, because the property 'three' does not exist, and Force was not explicitly defined as true.
ns(item).set('one.two.three.value', 123, {force: false);

//Force is explicitly defined as true, so the object will be updated.
ns(item).set('one.two.three.value', 123, {force: true); // item = {one: {two: {value: 123, three: {value: 123}}}};

//Supports multi-set
ns(item).set({
'one.two.value': 321,
'one.two.three.value': 321
}, {force: true}); // item = {one: {two: {value: 321, three: {value: 321}}}}

//Supports function as a value
ns(item).set('one.two.value', function(currentValue) {
	return currentValue * 10;
}); // item = {one: {two: {value: 3210, three: {value: 321}}}}

value()

Will return the current value of the API-chain.

done()

Removes any and all references to the original object.

has(nestedString, property)

Will return true if all matching objects from the nestedString has the property. This function calls for get(nestedString) to get the matching objects. Note: This function only returns true if ALL matched items contain the property.

var item = {one: {two: {value: 123 }}};
var hasProperty = ns(item).has('one.two', 'value'); //TRUE
var items = [{one: {two: {value: 123 }}}, {one: {two: {}}}];
hasProperty = ns(items).has('*.one.two', 'value'); //FALSE, the second item does not have the 'value' property.

Changelog

2.0.0.

Breaking changes

• .value() must be called after using .get()

• Complete rewrite of the module. Now integrates with lodash as a utility belt.
• Deprecated setObject() - The object is no longer mutated
• Deprecated getWithDefault() - Use .get() instead
• Deprecated .setOptions() - No longer has a purpose.
• Deprecated warnings and throws about invalid wrapper object.

Tests from previous version are still in the project, and are passing.

1.0.5

• Added .value()
• Added .setObject(..)
• Option to disable input validation when calling nested-structure
• The .set(..) function now returns the NestedStructure instance for chaining purposes.

1.0.4

• The set function can now take a function as a value argument.

1.0.3

• getWithDefault should only return the default value if the value is explicitly undefined.

1.0.2

• Fixed a bug where using an empty string ('') as your nestedString would return undefined rather than the input object.

1.0.1

• Added Options to always return array, always return with underscore, and always return with underscore chain, for flow-simplicity. (1.0.1)

1.0.0

• Initial release