@filtron/core

@filtron/core

A fast, human-friendly filter language for JavaScript and TypeScript. Parse expressions like age > 18 AND verified into a type-safe AST.

Why Filtron?

Let users filter data with readable expressions:

price < 100 AND category : ["electronics", "books"] AND inStock

Filtron parses these expressions into a structured AST you can use to generate SQL, filter arrays, or build custom query backends — safely, with no risk of injection attacks.

Filtron works best when your data has dynamic or user-defined fields that aren't part of your type system: e-commerce catalogs, log aggregation, CMS taxonomies, or multi-tenant platforms with custom metadata.

Installation

npm install @filtron/core

Optional helpers:

• @filtron/sql — Generate parameterized SQL WHERE clauses
• @filtron/js — Filter JavaScript arrays in-memory

Usage

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

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

if (result.success) {
	console.log(result.ast);
} else {
	console.error(result.error);
}

Syntax

// Comparisons
parse("age > 18");
parse('status = "active"');
parse('role != "guest"');

// Boolean logic
parse("age > 18 AND verified");
parse("admin OR moderator");
parse("NOT suspended");
parse("(admin OR mod) AND active");

// Field existence
parse("email?");
parse("profile EXISTS");

// Contains (substring)
parse('name ~ "john"');

// One-of (IN)
parse('status : ["pending", "approved"]');

// Ranges
parse("age = 18..65");
parse("price = 9.99..99.99");

// Nested fields
parse("user.profile.age >= 18");

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 logic	a AND (b OR c)

API

parse(input: string): ParseResult

Parses a filter expression and returns a result object.

const result = parse("age > 18");

if (result.success) {
	result.ast; // ASTNode
} else {
	result.error; // string - error message
	result.position; // number - position in input where error occurred
}

parseOrThrow(input: string): ASTNode

Parses a filter expression, throwing FiltronParseError on invalid input.

import { parseOrThrow, FiltronParseError } from "@filtron/core";

try {
	const ast = parseOrThrow("age > 18");
} catch (error) {
	if (error instanceof FiltronParseError) {
		console.error(error.message); // error description
		console.error(error.position); // position in input where error occurred
	}
}

Types

All AST types are exported for building custom consumers:

import {
	FiltronParseError, // Error class thrown by parseOrThrow
	type ParseResult,
	type ASTNode,
	type AndExpression,
	type OrExpression,
	type NotExpression,
	type ComparisonExpression,
	type ExistsExpression,
	type BooleanFieldExpression,
	type OneOfExpression,
	type NotOneOfExpression,
	type RangeExpression,
	type Value,
	type ComparisonOperator,
	type StringValue,
	type NumberValue,
	type BooleanValue,
	type IdentifierValue,
} from "@filtron/core";

The Lexer types are also available if you want to use them for syntax highlighting or other purposes:

import { Lexer, LexerError } from "@filtron/core";
import type { Token, TokenType, StringToken, NumberToken, BooleanToken } from "@filtron/core";

AST structure

Node Type	Fields	Example input
and	left, right	a AND b
or	left, right	a OR b
not	expression	NOT a
comparison	field, operator, value	age > 18
exists	field	email?
booleanField	field	verified
oneOf	field, values	status : ["a", "b"]
notOneOf	field, values	status !: ["a", "b"]
range	field, min, max	age = 18..65

Example output:

parse('age > 18 AND status = "active"')

// Returns:
{
  success: true,
  ast: {
    type: "and",
    left: {
      type: "comparison",
      field: "age",
      operator: ">",
      value: { type: "number", value: 18 }
    },
    right: {
      type: "comparison",
      field: "status",
      operator: "=",
      value: { type: "string", value: "active" }
    }
  }
}

Performance

Recursive descent parser. ~9 KB minified, zero dependencies.

Query complexity	Parse time	Throughput
Simple	~90-250ns	4-11M ops/sec
Medium	~360-870ns	1.1-2.8M ops/sec
Complex	~0.9-1.5μs	650K-1.1M ops/sec

License

MIT