@tsmx/json-traverse
Traverse and manipulate JSON objects.
Usage
Basic usage
const jt = require('@tsmx/json-traverse');
const callbacks = {
processValue: (key, value, level, path, isObjectRoot, isArrayElement, cbSetValue) => {
/* your logic here */
},
enterLevel: (level, path) => {
/* your logic here */
},
exitLevel: (level, path) => {
/* your logic here */
}
};
var obj = { /* your JSON object */ };
jt.traverse(obj, callbacks);Example 1: print out a simple object
var simpleObj = {
MyValue: 'test',
OtherValue: 'zzz',
NumberValue: 311,
MyArray: [1, 2, 3, 50, 60, 70]
};
const callbacks = {
processValue: (key, value, level, path, isObjectRoot, isArrayElement, cbSetValue) => {
console.log(level + ' ' + (path.length > 0 ? (path.join('.') + '.') : '') + key + ' = ' + value);
}
};
const jt = require('@tsmx/json-traverse');
jt.traverse(simpleObj, callbacks);
// 0 MyValue = test
// 0 OtherValue = xxx
// 0 NumberValue = 311
// 0 MyArray._0 = 1
// 0 MyArray._1 = 2
// 0 MyArray._2 = 3
// 0 MyArray._3 = 50
// 0 MyArray._4 = 60
// 0 MyArray._5 = 70
// flat array-mode: flattenArray = true (arrays are treated as one value)
jt.traverse(simpleObj, callbacks, true);
// 0 MyValue = test
// 0 OtherValue = xxx
// 0 NumberValue = 311
// 0 MyArray = 1,2,3,50,60,70Example 2: change values of an object
var simpleObj = {
MyValue: 'test',
OtherValue: 'zzz',
NumberValue: 311,
MyArray: [1, 2, 3, 50, 60, 70]
};
const callbacks = {
processValue: (key, value, level, path, isObjectRoot, isArrayElement, cbSetValue) => {
// change values of properties starting with 'My' and
// multiply all numeric array values greater then 50 by 100
if (key.startsWith('My')) {
cbSetValue('MyNew-' + value);
}
if (isArrayElement && parseInt(value) > 50) {
cbSetValue(100 * parseInt(value));
}
}
};
const jt = require('@tsmx/json-traverse');
jt.traverse(simpleObj, callbacks);
// {
// MyValue : "MyNew-test",
// OtherValue: "xxx",
// NumberValue: 311,
// MyArray: [ 1, 2, 3, 50, 6000, 7000 ]
// }Example 3: convert a more complex object to a collapsible HTML list
var htmlObj = {
MyArray: [0, 0],
ArrayInArray: [0, 1, ['two', 'three', [4, 5, 6]]],
MyNumber: 123,
MyString: 'test',
Child: {
ChildVal: 1,
SubChild: {
SubChildVal: 777
},
ChildArray: [1, 2, 66, 9, 900]
},
TrailingValue: 'testtesttest'
}
const callbacksHtmlList = {
processValue: (key, value, level, path, isObjectRoot, isArrayElement, cbSetValue) => {
if (isObjectRoot) {
console.log((' ').repeat(level) + ' <li class=\"caret\">Key: ' + key + '</li>')
}
else {
console.log((' ').repeat(level) + ' <li>Key: ' + key + ', Value: ' + value + '</li>')
};
},
enterLevel: (level, path) => {
if (level == 0) {
console.log('<ul>');
}
else {
console.log((' ').repeat(level) + '<ul class=\"nested\">');
};
},
exitLevel: (level, path) => { console.log((' ').repeat(level) + '</ul>'); }
};
const jt = require('@tsmx/json-traverse');
jt.traverse(htmlObj, callbacksHtmlList, true);
// <ul>
// <li>Key: MyArray, Value: 0,0</li>
// <li>Key: ArrayInArray, Value: 0,1,two,three,4,5,6</li>
// <li>Key: MyNumber, Value: 123</li>
// <li>Key: MyString, Value: test</li>
// <li class="caret">Key: Child</li>
// <ul class="nested">
// <li>Key: ChildVal, Value: 1</li>
// <li class="caret">Key: SubChild</li>
// <ul class="nested">
// <li>Key: SubChildVal, Value: 777</li>
// </ul>
// <li>Key: ChildArray, Value: 1,2,66,9,900</li>
// </ul>
// <li>Key: TrailingValue, Value: testtesttest</li>
// </ul>Key-features
- Define your callbacks for the following events:
-
processValue: processing a traversed value -
enterLevel: entering a new nesting level -
exitLevel: leaving nesting level
-
- For every inspected value you will get rich meta-data
- key name
- level of nesting
-
isObjectRootflag to indicate if it's an object root (root of a nested object) -
isArrayElementflag to indicate if it's an array item - full path to the key as an array of path elements
- Provides
cbSetValuefunction to change any value in-place (directly in the traversed object) - Supports deep inspection of
- Subobjects
- Arrays
- Arrays-in-Arrays
- Subobjects-in-Arrays
- Optional array flattening (treat arrays as flat values)
API
traverse(obj, callbacks = null, flattenArray = false)
Traverse the obj and apply the defined callbacks while traversing.
obj
Type: Object
The object to be traversed.
callbacks
Type: Object
Default: null
An Object containing the callback functions that should be applied while traversing obj. Every callback is optional. The expected form is:
callbacks = {
processValue: (key, value, level, path, isObjectRoot, isArrayElement, cbSetValue) => {
/* your logic here */
},
enterLevel: (level, path) => {
/* your logic here */
},
exitLevel: (level, path) => {
/* your logic here */
}
};processValue(key, value, level, path, isObjectRoot, isArrayElement, cbSetValue)
Defined callback function that is executed on each value when traversing the object. Receives the following input parameters:
key
Type: String
The key of the current value that is processed. If an array is deep-inspected the key for each processed item is _ + Index (_0, _1, _2,...).
value
Type: String
The actual value for key.
level
Type: Number
The nesting level. 0 indicates the first level.
path
Type: Array
An array containing all keys that where passed to reach the current key/value pair. Example:
{
child: {
subchild: {
myvalue: 123;
}
}
}When processing the value 123 with key myvalue, path would be ['child', 'subchild' ].
For deep-inspected arrays the path would contain the name of the array itself whereas the key would be the index of the processed value. Example:
{
child: {
subchild: {
myvalues: [1, 2, 3]
}
}
}When processing the array the keys would be _0, _1 and _2 and the path would always be ['child', 'subchild', 'myvalues'].
isObjectRoot
Type: Boolean
true if the currently processed key is the root of another sub-object. In our example:
{
child: {
subchild: {
myvalue: 123;
}
}
}isObjectRoot would be true for the keys child and subchild.
isArrayElement
Type: Boolean
true if the currently processed key is an item of an array.
cbSetValue(newValue)
Type: Function
Callback function receiving the newValue that should replace the currently traversed value.
Note: Setting a new value directly changes the traversed object! So if you need the original later on be sure to create a copy of the object first.
enterLevel(level, path)
Defined callback function that is executed on entering a new nesting level when traversing the object. Receives the following input parameters:
level
Type: Number
0-based index of the nesting level that is entered.
path
Type: Array
An array containing all keys that where passed to reach the current level that is entered.
exitLevel(level, path)
Defined callback function that is executed on leaving a nesting level when traversing the object. Receives the following input parameters:
level
Type: Number
0-based index of the nesting level that is exited.
path
Type: Array
An array containing all keys that where passed to reach the current level that is exited.
flattenArray
Type: Boolean
Default: false
If set to true arrays will not be iterated but treated as one single value. The default is false, where arrays are iterated and each entry is processed separately including deep-inspection, e.g. if the entry is an object or another array.
