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:

1. query - The query object that will be used to filter the results.
2. data - An array of JSON 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: '[e-mail]',
    password: 'SSBjYW4gc2VlIHRoYXQgeW91IGxpa2Ugd29uZGVyaW5nIGRvd24gdGhlIHJhYmJpdCBob2xlLg=='
    watchesAnime: false,
    watchesCartoons: false,
    watchesRickAndMorty: true
  },
  {
    id: 2,
    email: '[e-mail]',
    password: 'QXJlIHlvdSBwbGFubmluZyB0byBkZWNvZGUgYWxsIG9mIHRoZW0/',
    watchesAnime: true,
    watchesCartoons: true,
    watchesRickAndMorty: true
  },
  {
    id: 3,
    email: '[e-mail]',
    password: 'UmVhbGx5Pw==',
    watchesAnime: false,
    watchesCartoons: true,
    watchesRickAndMorty: true
  },
  {
    id: 4,
    email: '[e-mail]',
    password: 'SlNPTiBRdWVyeSBMYW5ndWFnZQ==',
    watchesAnime: true,
    watchesCartoons: false,
    watchesRickAndMorty: true
  }
];
 
// select * from users
// where
//    email === "[e-mail]" or
//    email === "[e-mail]" or
//    email === "[e-mail]"
const query = {
  email: {
    $in: ['[e-mail]', '[e-mail]', '[e-mail]']
  }
};
 
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: '[e-mail]' },
    { email: '[e-mail]' },
    { email: '[e-mail]' }
  ]
};

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.