As an open-source project, joewalnes/filtrex has picked up 1.1k stars on GitHub (JavaScript). A simple, safe, JavaScript Filter Expression compiler for end-users
Snapshot summary built from the project's own GitHub metadata — there's no written TopGit review yet. The page will update automatically when a full review is published.
WHY NO REVIEW YET
TopGit writes full reviews for the most-starred, most-requested repositories. This page is a snapshot until then — see the READ ME tab for the original README in full.
A simple, safe, JavaScript expression engine, allowing end-users to enter arbitrary expressions without p0wning you.
category == "meal" and (calories * weight > 2000.0 or subcategory in ("cake", "pie"))
Why?
There are many cases where you want a user to be able enter an arbitrary expression through a user interface. e.g.
Plot a chart (example)
Filter/searching across items using multiple fields (example)
Colorize items based on values (example)
Implement a browser based spreadsheet
Sure, you could do that with JavaScript and eval(), but I'm sure I don't have to tell you how stupid that would be.
Filtrex defines a really simple expression language that should be familiar to anyone who's ever used a spreadsheet and compile it into a JavaScript function at runtime.
Features
Simple! End user expression language looks like this transactions <= 5 and abs(profit) > 20.5
Fast! Expressions get compiled into JavaScript functions, offering the same performance as if it had been hand coded. e.g. function(item) { return item.transactions <=5 && Math.abs(item.profit) > 20.5; }
Safe! You as the developer have control of which data can be accessed and the functions that can be called. Expressions cannot escape the sandbox.
Pluggable! Add your own data and functions.
Predictable! Because users can't define loops or recursive functions, you know you won't be left hanging.
Get it
DOWNLOAD filtrex.js
10 second tutorial
// Input from user (e.g. search filter)
var expression = 'transactions <= 5 and abs(profit) > 20.5';
// Compile expression to executable function
var myfilter = compileExpression(expression);
// Execute function
myfilter({transactions: 3, profit:-40.5}); // returns 1
myfilter({transactions: 3, profit:-14.5}); // returns 0
Under the hood, the above expression gets compiled to a clean and fast JavaScript function, looking something like this:
There are only 2 types: numbers and strings. Numbers may be floating point or integers. Boolean logic is applied on the truthy value of values (e.g. any non-zero number is true, any non-empty string is true, otherwise false).
Values
Description
43, -1.234
Numbers
"hello"
String
foo, a.b.c, 'foo-bar'
External data variable defined by application (may be numbers or strings)
Numeric arithmetic
Description
x + y
Add
x - y
Subtract
x * y
Multiply
x / y
Divide
x % y
Modulo
x ^ y
Power
Comparisons
Description
x == y
Equals
x < y
Less than
x <= y
Less than or equal to
x > y
Greater than
x >= y
Greater than or equal to
x ~= y
Regular expression match
x in (a, b, c)
Equivalent to (x == a or x == b or x == c)
x not in (a, b, c)
Equivalent to (x != a and x != b and x != c)
Boolean logic
Description
x or y
Boolean or
x and y
Boolean and
not x
Boolean not
x ? y : z
If boolean x, value y, else z
( x )
Explicity operator precedence
Built-in functions
Description
abs(x)
Absolute value
ceil(x)
Round floating point up
floor(x)
Round floating point down
log(x)
Natural logarithm
max(a, b, c...)
Max value (variable length of args)
min(a, b, c...)
Min value (variable length of args)
random()
Random floating point from 0.0 to 1.0
round(x)
Round floating point
sqrt(x)
Square root
Operator precedence follows that of any sane language.
Adding custom functions
When integrating in to your application, you can add your own custom functions.
// Custom function: Return string length.
function strlen(s) {
return s.length;
}
// Compile expression to executable function
var myfilter = compileExpression(
'strlen(firstname) > 5',
{strlen:strlen}); // custom functions
myfilter({firstname:'Joe'}); // returns 0
myfilter({firstname:'Joseph'}); // returns 1
FAQ
Why the name?
Because it was originally built for FILTeR EXpressions.
What's Jison?
Jison is bundled with Filtrex – it's a JavaScript parser generator that does the underlying hard work of understanding the expression. It's based on Flex and Bison.
License?
MIT
Unit tests?
Here: Source, Results
What happens if the expression is malformed?
Calling compileExpression() with a malformed expression will throw an exception. You can catch that and display feedback to the user. A good UI pattern is to attempt to compile on each keystroke and continuously indicate whether the expression is valid.
Contributors
@joewalnes Joe Walnes – the author of this repository
@msantos Michael Santos – quoted symbols, regex matches and numerous fixes
@alexgorbatchev Alex Gorbatchev – NPM package and housekeeping
@m93a Michal Grňo – critical fixes of security bug
Like this? Want other thingies?
websocketd – Turn any program that uses STDIN/STDOUT into a WebSocket server. Like inetd, but for WebSockets.
ReconnectingWebSocket – Simplest way to add some robustness to your WebSocket connections.
Smoothie Charts – JavaScript charts for streaming data.
Visit The Igloo Lab to see and subscribe to other thingies I make.
No homepage URL was recorded for joewalnes/filtrex in TopGit's last sync. The README tab above frequently contains screenshots and demo links, or check the repository description on GitHub.
Does joewalnes/filtrex have any tags?
TopGit's last sync did not record any GitHub topics for joewalnes/filtrex. GitHub topics appear in the right sidebar of a repository page; that's the authoritative place to check.
How active is development on joewalnes/filtrex?
The most recent commit recorded on joewalnes/filtrex was 5.7 years ago, based on the GitHub push timestamp. The repository has 73 forks — one of the better signals of community interest.
How many stars does joewalnes/filtrex have?
joewalnes/filtrex has 1.1k GitHub stars — refresh the page for the live number, or check github.com/joewalnes/filtrex. TopGit mirrors GitHub's count but does not claim minute-by-minute accuracy.
What language is joewalnes/filtrex written in?
joewalnes/filtrex is written primarily in JavaScript. GitHub's language field is based on the largest share of bytes in the default branch.
What license does joewalnes/filtrex use?
joewalnes/filtrex is released under the MIT license. Always verify the LICENSE file directly on GitHub for the authoritative terms — license strings can be edited out of sync with a project's actual stance.
Where do I read more about joewalnes/filtrex?
This TopGit page is a snapshot — the READ ME tab shows the project's own README content (links stripped, images preserved). The GitHub repository at github.com/joewalnes/filtrex is the definitive source.
Read full README in the tab above.
Is filtrex worth your time?
ChatGPT, Claude and Perplexity can all read this page. Ask one of them what it makes of filtrex.