jql-matcher
v1.0.3
Published
JSON Query Language - Matcher. Filter a json-array based on a given query.
Downloads
20
Maintainers
Readme
JQL-Matcher
JSON Query Language - Matcher. Filter a json-array based on a given query.
Getting started
This library was developed and tested on Node Environment, but you can still use it for the web.
npm i -S jql-matcher
If you are using it for web app, I suggest using the built source codes:
import jql from 'jql-matcher/build';
If you are using it for NodeJS, you don't need to use the built source codes:
const jql = require('jql-matcher/src');
Example usage
const data = [
{ id: 1 },
{ id: 2 },
{ id: 3 }
];
// select * from list where id === 3
const query = { id: 3 };
const result = jql(query, data);
jql-matcher
only accepts two arguments:
query
- The query object that will be used to filter the results.data
- Anarray
ofJSON
data.
JQL Query Expressions
JQL has standard operations
that it uses to execute this filtering process. Operation names are always prefixed with a $
sign.
Example query
const data = [
{
id: 1,
email: '[email protected]',
password: 'SSBjYW4gc2VlIHRoYXQgeW91IGxpa2Ugd29uZGVyaW5nIGRvd24gdGhlIHJhYmJpdCBob2xlLg=='
watchesAnime: false,
watchesCartoons: false,
watchesRickAndMorty: true
},
{
id: 2,
email: '[email protected]',
password: 'QXJlIHlvdSBwbGFubmluZyB0byBkZWNvZGUgYWxsIG9mIHRoZW0/',
watchesAnime: true,
watchesCartoons: true,
watchesRickAndMorty: true
},
{
id: 3,
email: '[email protected]',
password: 'UmVhbGx5Pw==',
watchesAnime: false,
watchesCartoons: true,
watchesRickAndMorty: true
},
{
id: 4,
email: '[email protected]',
password: 'SlNPTiBRdWVyeSBMYW5ndWFnZQ==',
watchesAnime: true,
watchesCartoons: false,
watchesRickAndMorty: true
}
];
// select * from users
// where
// email === "[email protected]" or
// email === "[email protected]" or
// email === "[email protected]"
const query = {
email: {
$in: ['[email protected]', '[email protected]', '[email protected]']
}
};
const result = jql(query, data);
Operators
are abstract, therefore, there could be different approach to achieving the same result and it's also prone to abuse. The example above is what I would call a good query
because it is short and precise. A bad counterpart would be:
const query = {
$or: [
{ email: '[email protected]' },
{ email: '[email protected]' },
{ email: '[email protected]' }
]
};
The query above gives you the same result but it's labeled as bad
because it's unnecessarily long and complex. JQL-Matcher
is designed and intended to be extremely performant (to a point of sacrificing a little dev experience points for the sake of keeping it performant) but it should not be abused. As a general rule of thumb ALWAYS REDUCE YOUR QUERY DOWN TO IT'S SIMPLEST FORM. Prefer the shortest and simplest code.
All queries are treated as and
, unless you explicitly use $or
.
// select * from list
// where
// watchesAnime === true and
// watchesCartoons === true and
// watchesRickAndMorty === true
{
watchesAnime: true
watchesCartoons: true
watchesRickAndMorty: true
}
PS: Rick and Morty is not a cartoon! It's a simulation.
Deep querying
Don't be afraid to go as deep as you need to. Given this sample data:
const sampleData = [
{
id: 1,
posts: {
id: 1,
body: 'Lorem ipsum dolor sit amet,',
comments: [
{
id: 1,
body: 'consectetur adipiscing elit.'
}
]
},
preferences: {
notifications: {
outsideNotifications: {
email: true
}
}
}
}
];
The query below will return all rows where preferences.notifications.outsideNotifications.email === true
.
// select * from list
// where
// preferences.notifications.outsideNotifications.email === true
const query = {
preferences: {
notifications: {
outsideNotifications: {
email: true
}
}
}
};
// ...
You can also filter even when a key contains an array value. The query below will return all rows if
preferences.notifications.outsideNotifications.email === true
- There's a one of the comments in the posts has id of 1.
// select * from list
// where
// posts.comments has id === 1 and
// preferences.notifications.outsideNotifications.email === true
const query = {
posts: {
comments: {
id: 1
}
},
preferences: {
notifications: {
outsideNotifications: {
email: true
}
}
}
};
// ...
You can do even further query where you query a value inside an array of an array inside another giant array.
You can also nest $or
and $and
operators together whenever it makes sense to do it. Just always keep the rule of thumb in mind, ALWAYS REDUCE YOUR QUERY DOWN TO IT'S SIMPLEST FORM. Prefer the shortest and simplest code.
Operations
docs.
Contributing
- Have a question, clarification, discussion, feature request, or bug to report? File an issue.
- Want to contribute to the code? Please see projects and email me.