Filtrex

3.1.0 verified Fri May 01 auth: no javascript

A JavaScript expression compiler that safely evaluates end-user-defined filter expressions by compiling them into sandboxed JavaScript functions. Current stable version is 3.1.0, with regular maintenance releases. Key differentiators: simple spreadsheet-like syntax, no eval, no loops or recursion (predictable), supports custom data and functions, ships TypeScript types, and is fast due to compiled output. Follows semver, breaking changes in v3 include stricter property access and boolean preservation.

Common errors

error Error: Cannot access property 'xxx' of undefined ↓

cause Expression references a property not present in the data object (breaking change in v3).

fix

Ensure all properties accessed in the expression exist in the data object, or use optional chaining via custom functions.

error TypeError: Expression returned ... instead of boolean ↓

cause Expression returns a number or string where a boolean is expected (e.g., using + on booleans).

fix

Use logical operators (and, or, not) instead of arithmetic on booleans.

error SyntaxError: Unexpected token '}' ↓

cause String literal contains unescaped backslash or invalid escape sequence (e.g., '\n' instead of literal newline).

fix

Escape backslashes: use '\\' for a backslash, or wrap string in double quotes and use literal newline.

error Error: Unknown function 'foo' ↓

cause Expression calls a function not defined in the customFunctions option.

fix

Warnings

breaking Property access on non-existent data properties now throws an error instead of returning undefined. ↓

fix Update expressions to only access properties present in the data object, or add a check before passing data.

breaking Logical operations now return proper booleans (true/false) instead of 1/0. ↓

fix Review expressions that relied on numeric coercion of booleans, e.g., `(a > 5) + (b < 3)` will now throw an error instead of summing numbers.

breaking Exponentiation operator precedence corrected; `2 ** 3 ** 2` is now `2 ** (3 ** 2)` = 512 instead of `(2 ** 3) ** 2` = 64. ↓

fix Add parentheses to ensure intended order: `(2 ** 3) ** 2` if right-to-left not desired.

breaking Modulo operator now always returns a positive result (like JavaScript's % but with sign of divisor). ↓

fix If negative results are needed, use custom function with Math.abs or adjust logic.

breaking Backslash must be escaped in string literals: `"\\"` for a single backslash. ↓

fix Escape backslashes in all string literals used in expressions.

deprecated Old GitHub repository URL `github.com/m93a/filtrex` is deprecated; use `github.com/cshaa/filtrex`. ↓

fix Update links and references to point to new repo.

Install

npm install filtrex

yarn add filtrex

pnpm add filtrex

Imports

compileExpression
wrong
```
import filtrex from 'filtrex'
```
correct
```
import { compileExpression } from 'filtrex'
```
Default export not available; use named import since v1.
compileExpression (CommonJS)
wrong
```
const filtrex = require('filtrex')
```
correct
```
const { compileExpression } = require('filtrex')
```
CommonJS require must destructure the named export.
TypeScript types
```
import type { FiltrexExpression } from 'filtrex'
```
Types are included; FiltrexExpression is the type of the compiled function.

Quickstart

Compile and execute a filter expression with data and custom functions.

import { compileExpression } from 'filtrex';

// Compile user-provided filter expression
const expr = compileExpression(`category == "meal" and (calories * weight > 2000.0 or subcategory in ("cake", "pie"))`);

// Execute on data
const data = {
  category: 'meal',
  calories: 500,
  weight: 5,
  subcategory: 'cake'
};

console.log(expr(data)); // true

// With custom functions
const expr2 = compileExpression(`x > 10`, { customFunctions: { double: (n) => n * 2 } });
console.log(expr2({ x: 15 })); // true