dataQuery

Lightweight lib (~2kb) to Query / Filter a set of Object Literal ("JSON"), which can be an Array or Object Literal, with powerfull methods to be used as a filter, like: RegEx for value or properties; dot notation to identify properties to be filtered; Array comparison; and more...

Out of the box support for:

• Node
• Angular (module name zk.dataQuery, filter and factory name dataQuery)
• Browser (All the good browsers and ie9+)

Key Features and Goals

• The dataset to be filtered can be an Array of Objects [{},{}] or a structure of nested Objects { key1: {}, key2: {} }

• The filter can be a simple object literal. e.g. { status: 'published', author: 'zk' }. The properties included on the filter will be treated like an AND clause, so if all the properties match (but not exclusively), the object will be considered found.

• The path of a property to be matched and filtered can be set as a string with a dot notation. e.g. 'root.level1.level2'

• The filter object can mix properties written literally or via dot notation. e.g. { 'publication.status': 'published', author: 'zk' }.

• The filtering can be based just on the existence of a path of properties 'root.level1.level2', or it can be checked against a value 'someStringValue' or an object representing a filter { status: 'published', author: 'zk' }

• RegEx is supported for the value to be checked e.g. ['z', /z/] e.g. /z|k/, so you can get an OR clause for the value match

• RegEx also is supported for the name of the properties '/^file/', even on deep structures 'root./^file*/.published'

• Command-line interface (CLI). e.g. $ data-query --dataSrc=$(< src.json) --filter=$(< filter.json)

Installation

NPM / Node

npm install data-query

And to be used via CLI:

npm install data-query -g

npx data-query --help

Bower

bower install data-query

Usage / Examples

Object to be queried / filtered:

var objToBeQueried = [{
    id: 1,
    arrayWithAnObject: [
        1, {
            z: 'k'
        },
        2
    ],
    deep: {
        obj: {
            veryDeep: [
                'z',
                'k'
            ]
        }
    },
    twoWithTheSameValue: 'zk'
}, {
    id: 2,
    deep: {
        obj: {
            veryDeep: 'zk'
        }
    },
    someInner: {
        date: new Date(2014)
    }
}, {
    id: 3,
    deep: {
        obj: {
            veryDeep: 'kz'
        }
    },
    twoWithTheSameValue: 'zk',
    someInner: {
        date: new Date(2015)
    }
}, {
    id: 4,
    root: {
        filePDF: {
            url: 'http://file.com'
        }
    }
}, {
    id: 5,
    root: {
        fileDOC: {
            url: 'http://file.com.br'
        }
    }
}];

Searching with a clause which only one object will match:

    dataQuery(objToBeQueried, 'id', 1);

    // or by using an Object Literal as a search clause
    dataQuery(objToBeQueried, {id: 1});

The result will be:

      {id: 1, ...}

Searching with a clause where more than one object will match

    dataQuery(objToBeQueried,  'twoWithTheSameValue', 'zk');

    // or by using an Object Literal as a search clause
    dataQuery(objToBeQueried,  {twoWithTheSameValue: 'zk'});

The return will be these two objects:

      {id: 1, ...} and {id: 3, ...}

Searching with more than one clause that needs to match for the same object ( AND )

      dataQuery(objToBeQueried,  {twoWithTheSameValue: 'zk', id: 3});

The result will be just the object:

      [{id: 3, ...}]

Searching with more than one clause that needs to match for the same object, mixing properties with dot notations and literal properties ( AND )

      dataQuery(objToBeQueried,  {twoWithTheSameValue: 'zk', 'deep.obj.veryDeep': 'kz');

The result will be just the object:

      [{id: 3, ...}]

Searching for a value deep down in the object structure

    dataQuery(objToBeQueried, 'deep.obj.veryDeep', 'zk');

    // or by using an Object Literal as a search clause
    dataQuery(objToBeQueried,  {
        deep: {
            obj: {
                veryDeep: 'zk'
            }
        }
    });

result:

      [{id: 2, ...}]

Searching for multiple values for the same property ( OR )

    dataQuery(objToBeQueried, 'id',  /1|2/);

    // or by using an Object Literal as a search clause
    dataQuery(objToBeQueried, { id: /1|2/ });

result:

      [{id: 1, ...}, {id: 2, ...}]

OBS: "OR clause" using array was deprecated. Use RegEx as shown above case

RegEx :: Searching for multiple values deep down in the object structure, using RegEx

    dataQuery(objToBeQueried, 'deep.obj.veryDeep', /z|k/);

result:

      [{id: 1, ...}, {id: 2, ...}, {id: 3, ...}]

RegEx :: Searching for the existence of a property using RegEx at the property path

    dataQuery(objToBeQueried, 'root./^file*/.url');

result:

      [{id: 4, ...}, {id: 5, ...}]

RegEx :: Using RegEx for property name and value

    dataQuery(objToBeQueried, 'root./^file*/.url', /\.com\.br/);

result:

      [{id: 5, ...}]

Comparing Arrays :: Having a property and a filter as an Array of Strings or Numbers (not Objects), they will match when both have the same length and the same value on its positions, regardless of its order

    dataQuery(objToBeQueried, 'deep.obj.veryDeep', [
        'z',
        'k'
    ]);

    // or

    dataQuery(objToBeQueried, {
        deep: {
            obj: {
                veryDeep: [
                    'k',
                    'z'
                ]
            }
        }
    });

result:

      [{id: 1, ...}]

When comparing an Array against one value or one RegExp, it will return the objects whose one of its positions's values matches with the filter value

    dataQuery(objToBeQueried, 'deep.obj.veryDeep', /^z$/)
    // or
    dataQuery(objToBeQueried, 'deep.obj.veryDeep', 'z')

result:

      [{id: 1, ...}]

Comparing an Array with an Object Literal, it will return the objects whose one of its positions's objects matches with the filter value

    dataQuery(objToBeQueried, 'arrayWithAnObject', {'z': 'k'});
    // or
    dataQuery(objToBeQueried, {
        arrayWithAnObject: {
            'z': 'k'
        }
    });

result:

      [{id: 1, ...}]

Comparing Date Objects

    dataQuery(objToBeQueried, 'someInner.date', new Date(2014));
    // or
    dataQuery(objToBeQueried, {
        someInner: {
            date: new Date(2014)
        }
    });

result:

      [{id: 2, ...}]

Function as a filter :: As a param you have the value of the property matched.

    // e.g. Only the ones whose value is an Array
    dataQuery(objToBeQueried, 'deep.obj.veryDeep', function(propValue){
        return propValue.constructor == Array;
    });

    // or using an Object Literal

    dataQuery(objToBeQueried, {
        deep: {
            obj: {
                veryDeep: function(propValue) {
                    return propValue.constructor == Array;
                }
            }
        }
    })

result:

      [{id: 1, ...}]

Function as a filter :: With the entire object as a param.

    dataQuery(objToBeQueried,  function(v){
        return v.id > 2 && v.id < 5; // e.g. Matching id in a specific range
    });

result:

      [{id: 3, ...}, {id: 4, ...}]

Command-line interface (CLI): The arguments, parameters, are dataSrc (JSON data source) and filter (JSON filter).

    $ data-query --dataSrc="$(<src.json)" --filter="$(<filter.json)"