intuitive-json-query-language

A simple, human-readable query language implementation for being able to filter for specific JavaScript/JSON objects in an array.

Motivation

My main motivation was to create a JQL-like query language for JSON objects which I can use to define complex criterias for generating smart music playlist from my music library.

My plan was to enable filtering and testing JSON objects (as music metadata) against queries that are able to check for more than one criteria in metadata object.

Install

npm i intuitive-json-query-language

Usage

const ijql = require('intuitive-json-query-language');

const musicMetadata = [
    {
        ...
    }
]

// to filter elements of an array for a query
const matchingElements = ijql.filter(
    musicMetaData,
    'artist IS Bruno Mars AND comments INCLUDES favorite'
);

// to check an object against a query (if you might save on iterations)
const isMatching = ijql.testElementAgainstQuery(
    musicMetadatap[0],
    'albumArtist IS Phil Collins AND (comments INCLUDES energic OR comments INCLUDES party)'
);

Methods

filter(elements, query)

Filter those elements from the elements array which are matching to the query.

• elements is an array of Objects
• query is a string containing a query detailed below

Returns: an array which is subset of the elements array.

testElementAgainstQuery(element, query)

Check complience of the object in element with the query.

• element object to check against query
• query is a string containing a query detailed below

Returns: true / false

Query syntax

Syntax

Conditions

<propertyPathOnTestedObject> <operator> <lookupValue>

• propertyPathOnTestedObject is a string and can describe a deep path on the object
• operator: see below the list of operators
• lookUp value is what we need equality/containment etc.

For example:

{
    name: {
        fistName: 'Peter'
    }
}

name.firstName IS Peter

Parens and embedded logical expressions

IJQL supports any levels of logical grouping, like (by shortening conditions into single letter)

a OR (b AND (c OR d) AND e) AND f

OR is always evaluated later than a same-level AND oeprator.

Operators

IMPORTANT: Space is always needed around operators!

• AND - logical AND - only true if all operands are true
• OR - logical OR - only false if all operands are false
• NOT INCLUDES - check if an array or a string NOT contains the look-up value on its right
• INCLUDES - check if an array or a string NOT contains the look-up value on its right
• IS - check if the value on the property path strict equals to the look-up value on its right
• IS NOT - check if the value on the property path not strictly equals to the look-up value on its right
• < - check if the value on the property path is less than the given look-up value
• > - check if the value on the property path is greater than the given look-up value