filtering-query v0.1.0-alpha.1

Simple expression language for objects filtering

A simple, safe, JavaScript expression engine, allowing end-users to enter arbitrary expressions without p0wning you.

Installation

npm i --save filtering-query

Quick start

import {compile} from 'filtering-query'

// Input from a user (e.g. a search filter)
const expression = 'transactions <= 5 and customer.name = "My customer"';

// Compile expression to an executable function
const fn = compile(expression);

// Execute function
fn({transactions: 3, customer: { name: "My customer" }); // returns true
fn({transactions: 3, customer: { name: "Other customer" }); // returns false

Under the hood, the above expression gets compiled to a clean and fast JavaScript function, looking something like this:

// Resulting function
function(item) {
  return item.transactions <= 5 && customer.name === "My customer";
}

Why?

There are many cases where you want a user to be able enter an arbitrary expression through a user interface to filter/search across items using multiple fields.

Sure, you could do that with JavaScript and eval(), but this would increase chances of p0wning you.

This library takes a different approach. It defines a grammar for a really simple expression language, produces a lexer and a parser for it, and uses it to compile down the expression into a fast JavaScript filtering function, which can be used runtime.

The expression laguage is very simple so that anyone who's ever used a spreadsheet should be familiar with it.

Moreover, the library provides a type assist functionality based on JSON schema, so writting an expression is even simplier.

Syntax

Operator precedence follows that of any sane language.

Examples

product.name = "Some product name"
product.price.value >= 100.5 and product.price.value <= 300
product.name ~= "some"
product.name = "Some product" and (product.categories = "Appliances" or product.categories = "Electronics")
product.name = "Some product" and not product.availability

See the grammar definition for more details.