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). It works best when your data has dynamic or user-defined fields that aren't part of your type system: e-commerce catalogs with varying product attributes, log entries with arbitrary fields, CMS taxonomies, or multi-tenant platforms with custom metadata.

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 > 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 > 18 AND status = "active"').ast);

const query = `SELECT * FROM users WHERE ${sql}`;
// SELECT * FROM users WHERE (age > $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 > 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; the adapters generate SQL or a JavaScript filter 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

In context: API request lifecycle

Full HTTP request filtering 500 users with (role = "admin" OR role = "moderator") AND age > 25 through an Elysia API with in-memory SQLite. Filtron adds less than 1% to total request time.

41μs

883ns

245ns

110μs

41μs

192μs

Request Parse SQL Database Response

All benchmarks were run on an Apple MacBook Pro M5

Installation

npm install @filtron/core

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