Filtron

Human-friendly filter expressions for your data

Available fields

shape	["circle", "triangle", "square"]
color	["red", "blue", "green", "orange", "purple"]
size	1..5

Learn more ↓

What is Filtron?

Filtron parses human-friendly filter strings into a typed AST (Abstract Syntax Tree). The core parser only handles parsing, giving you full control over what happens next. Use the included adapters to generate SQL or JavaScript filters, or traverse the AST to build your own integrations.

@filtron/corecore@filtron/sqlsql@filtron/jsjs

import { parse } from "@filtron/core";

const result = parse('age &gt; 18 AND status = "active"');

if (result.success) {
 // result.ast contains the parsed query
}

import { parse } from "@filtron/core";
import { toSQL } from "@filtron/sql";

const { sql, params } = toSQL(parse('age &gt; 18 AND status = "active"').ast);

const query = `SELECT * FROM users WHERE ${sql}`;
// SELECT * FROM users WHERE (age &gt; $1 AND status = $2)

console.log(params);
// [18, "active"]

import { parse } from "@filtron/core";
import { toFilter } from "@filtron/js";

const users = [
 { name: "Alice", age: 25 },
 { name: "Bob", age: 32 },
];

const filter = toFilter(parse('age &gt; 18').ast);
const adults = users.filter(filter);
// [{ name: "Alice", age: 25 }, { name: "Bob", age: 32 }]

Syntax

Comparisons

age > 18
price <= 99.99
status = "active"
role != "guest"

Boolean logic

age > 18 AND verified
admin OR moderator
NOT suspended
(admin OR mod) AND active

Field existence

email?
profile EXISTS

Contains and one-of

name ~ "john"
status : ["pending", "approved", "rejected"]

Ranges

age = 18..65
temperature = -10..10

Operators

Operator	Meaning	Example
`=` `:`	Equal	`status = "active"`
`!=` `!:`	Not equal	`role != "guest"`
`>` `>=` `<` `<=`	Comparison	`age >= 18`
`~`	Contains	`name ~ "john"`
`?` `EXISTS`	Field exists	`email?`
`..`	Range	`age = 18..65`
`: [...]`	One of	`status : ["a", "b"]`
`AND` `OR` `NOT`	Boolean	`a AND (b OR c)`

Performance

Overhead added by Filtron when processing a query. Parse converts the query string to an AST; filter creation generates the JavaScript function. Both are one-time costs per query.

Query	Parse	SQL	Filter
`level > 3 AND message ~ "timeout"`	2μs	1μs	1μs
`status : ["error", "warning", "critical"]`	3μs	2μs	2μs
`(user? AND role = "admin") OR sudo`	5μs	3μs	3μs

Benchmarked on Apple M5

Installation

npm install @filtron/core

# Optional helpers
npm install @filtron/sql # SQL WHERE clauses
npm install @filtron/js # Array filtering