nested-structure
This module is useful for when you have to work with nested object structures. For example:
//Typicalvar isValid = item && item0 && item0propertyName === true; //Nested-structurevar ns = ;var isValid = value === true;
It's also useful for avoiding Cannot read property X of undefined
:
var item = {}; ifitemcustomerid === 1 //Cannot read property 'id' of undefined var ns = ;ifvalue === 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 = value; //John, Lisa, Rob var customersWithRights = 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 = ;var item = Customers: Name: 'John' Name: 'Lisa' Name: 'Rob';var customerNames = 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.
nestedString
, defaultValue
)
get(Will return the values found matching the specified nestedstring, or defaultValue
.
var ns = ;var item = one: two: three: value: 123;value; //123value; //999value; //undefined var items = one: two: three: value: 123 one: two: three: value: 321 ;var values = value; //[123, 321]
nestedString
, value
, options
)
set(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 = ;var item = one: two: ;; //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.
value()
Will return the current value of the API-chain.
done()
Removes any and all references to the original object.
nestedString
, property
)
has(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 = ; //TRUEvar items = one: two: value: 123 one: two: {};hasProperty = ; //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