README
simple-object-query
npm install simple-object-query
bower install simple-object-query
Really simple lib to find a deep value in an object
I'll use this source object for all examples
var source = {
data: [
{
item: {
name: 'select',
options: {
length: 4,
property: {
name: 'input'
}
}
}
},
{
item: {
name: 'group',
options: {
length: 2,
property: {
name: 'input'
}
},
type: 'number'
}
}
]
};
get
This function will return value of deep field if it is own property. You can use *
if you don't know exact index in array.
var get = require('simple-object-query').get;
get(source, 'data.*.item.name'); // 'select'
get(source, 'data.1.item.name'); // 'group'
get(source, 'data.*.item.type'); // 'number'
Basically you will use this method only when you need a *
because without it you can get value just with regular code.
where
This is filter function for array. It will return all items which deep fields will be equal to query values. You can use regular expression to test deep field value.
var where = require('simple-object-query').where;
where(source.data, {
'item.name': /(select|group)/,
'item.type': 'number',
'item.options': function (value) {
return typeof value === 'object';
}
});
/*
[
{
item: {
name: 'group',
type: 'number',
options: {...},
}
}
]
*/
You can do even more complicated query with array of queries. Items of this array can be one of three types:
Object
- regular queryFunction
- should be map function which will return new value instead of previous resultString
- shortcut for map function withget
function with current query string(item) => get(item, string)
var src = {
root: {
node: [
{a: {b: 1}},
{a: {c: 2}},
{a: {d: 3, g: [{e: 3},{f: 4}]}},
{a: {d: 3, g: [{e: 5},{f: 5}]}},
{a: {d: 4, g: [{e: 3},{f: 4}]}},
{a: {d: 4, g: [{e: 5},{f: 5}]}}
]
}
};
var q = require('simple-object-query'),
_ = require('underscore');
q.where(src.root.node, [
{
'a.d': 3
},
'a.g',
_.flatten, // or lite version (single level) analog q.flatten
{
'e': 5
}
]);
/*
[
{a: {d: 3, g: [{e: 5},{f: 5}]}}
]
*/
find
This function will recursively find a deep object which has deep fields as in query object and their values are equal to values from query object. As values in query object you can use regular expressions.
var find = require('simple-object-query').find;
find(source, {
'options.property.name': 'input'
});
/*
[
{name: 'select', options: {...}},
{name: 'group', options: {...}}
]
*/
find(source, {
'name': 'group',
'options.property.name': 'input'
});
/*
[
{name: 'group', options: {...}}
]
*/
find(source, {
'options.length': /\d+/
});
/*
[
{name: 'select', options: {...}},
{name: 'group', options: {...}}
]
*/
search
Difference between find
is that it takes parameters as object of type
{
source: object,
query: object, // same object as for "find"
exclude: array, // array of names of properties which are links to other objects in source (circular links)
recursion: true, // deep search or not
callback: function (object) {} // optional callback for each found target
}
If you will not set callback then search
will return array of objects of next type
{
parent: object, // link to parent object
field: 'string', // name of parent property of target object
target: object, // searched object
path: ['path', 'to', 'object'] // this path means that target is in source.path.to.object property
}
Warning: if your input object has circular links (like parent
fields or like previousSibling
in DOM) then you should set path to this fields in exclude
array to prevent endless recursion.
var search = require('simple-object-query').search;
search({
source: source,
query: {
'options.property.name': 'input'
}
});
/*
[
{
parent: {item: {...}},
field: 'item',
path: ['data', '0', 'item'],
target: {name: 'select', options: {...}}
},
{
parent: {item: {...}},
field: 'item',
path: ['data', '1', 'item'],
target: {name: 'group', options: {...}}
}
]
*/
source.data[0].item.list = source.data;
search({
source: source,
query: {
'length': 2
},
exclude: [
'list',
// or more specifically
'item.list'
]
});
/*
[
{
parent: {name: 'group', options: {...}},
field: 'options',
path: ['data', '1', 'item', 'options'],
target: {length: 2, property: {...}}
}
]
*/
replace
This method will replace or remove (if callback will return undefined
) target object.
var replace = require('simple-object-query').replace;
replace(source, {length: /\d+/}, function (target, parent, field, path) {
return target.length > 3 ? 'test' : undefined;
});
console.log(source.data[0].item.options); // 'test'
console.log(source.data[1].item.hasOwnProperty('options')); // false
Off course if you don't want to remove target
just return itself.
Instead of callback you can pass some value.
replace(source, {length: /\d+/}, 'test');
console.log(source.data[0].item.options); // 'test'
console.log(source.data[2].item.options); // 'test'
Or if you will not pass anything it will remove all targets
replace(source, {length: /\d+/});
console.log(source.data[0].item.hasOwnProperty('options')); // false
console.log(source.data[1].item.hasOwnProperty('options')); // false
If your target
is in array, it will be removed correctly
replace(source, {name: 'select'});
console.log(source.data.length); // 1
console.log(source.data[0].item.name); // 'group'
If you need set exclude
parameter then you should pass all parameters as object just like for search
only with callback
parameter
replace({
source: source,
query: {length: /\d+/},
exclude: ['item.list'],
callback: function (target, parent, field, path) {
return target.length > 3 ? 'test' : undefined;
}
});