deep-getter-setter
1. Introduction
The package deep-getter-setter is a very small but powerful tool.
1.1. What is it for?
Basically:
Understanding that...
- a nesteable is any object or array.
...then it is used to...
- get deep values from a nesteable.
- set deep values to a nesteable.
- modify deep values of a nesteable.
- check deep values of a nesteable.
- ensure deep values of a nesteable.
...or in other words...
-
From this:
{a:{b:{c:{d:{e:{f:{g:{h:{i:{j:{k:{l:{m:888}}}}}}}}}}}}}
-
And this:
'a b c d e f g h i j k l m'.split(' ')
-
You can get this:
888
And from this simple idea, you can:
· get
· set
· modify
· check
· ensure
Note: Pssst!!! All of them are done by the modify
method under the hood!
2. Installation
Just:
~$ npm install deep-getter-setter
In Node.js (include literally to compatibilize the examples):
const DeepGetterSetter = ;
In browsers:
3. API comment
For the next examples:
Consider this line included:
var getsetmodifyexistsensure = DeepGetterSetter;
It just decouples the whole API by its properties.
The API
The API to master here:
get (data, selector)
:
Returns the item value.
set (data, selector, value)
:
Redefines the item value.
modify (data, selector, modifier)
:
Modifies the item value through a function.
exists (data, selector, success, error)
:
Do different things depending on its existence.
ensure (data, selector, value)
:
Same than set but when value is not provided, it sets a {}.
That is all.
3.1. How does it work?
The 2 common parameters:
-
The
data
: nestable object or array with the data to be searched in. -
The
selector
: array with strings for each nested property to be accessed.
The other parameters:
- The
modifier
atmodify (data, selector, modifier)
:
Function that can return whatever in the last moment of the function.
- The
value
atset (data, selector, value)
:
Value (of any type) that is going to set at the selected holder.
// Then x.a === 4
- The
success
anderror
atexists(data, selector, success, error)
:
Both are functions, and none obligatory.
By default, it will return true when exists, and false when it does not exist.
// Then true if a is in x.
6, The value
at ensure (data, selector, value)
When the selected node does not exist, it is created with this provided value.
// Then x.a will be something, or {}. // Then x.a will be something, or 50.
4. Usage
a) Start retrieving the API from the master object:
var getsetmodifyexistsensure = DeepGetterSetter;
test/deep-getter-setter-spec.js
):
b) Test the example (found at ~$ npm run test
Which will execute some examples that demonstrate what we can expect from the API:
// In Node.js:const DeepGetterSetter = ; // Retrieve the 3 functions:var getsetmodifyexistsensure = DeepGetterSetter; // Some random data:var data = a:b:0510; // Check that that the getter works okay:console; // Use the setter:; console; // Check that the setter worked good:console; // Use the modifier:; // Check that the modifiers worked fine:console; // Use the exists:console; // Check that the exists worked fine:console; // Use the ensurer:; // Check that the ensurer worked fine:console;console;
It must print everything "Passed!", and nothing "Failed - ...".
5. Conclusion
This is a small tool that you can use in any type of your projects, to easily retrieve and reset values, among other operations.