filtrex

library3.1.0jsnpmunverified

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.

http-networking web-framework serialization

npm install filtrex

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · FILTREX

filtrex

http-networkingjavascriptv3.1.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

compileExpression

✓ import { compileExpression } from 'filtrex'

✗ import filtrex from 'filtrex'

Default export not available; use named import since v1.

compileExpression (CommonJS)

✓ const { compileExpression } = require('filtrex')

✗ const filtrex = 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.

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

Debug

Known issues

breakingProperty 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.

affects: >=3.0.0

breakingLogical 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.

affects: >=3.0.0

breakingExponentiation 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.

affects: >=3.0.0

breakingModulo 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.

affects: >=3.0.0

breakingBackslash must be escaped in string literals: `"\\"` for a single backslash.

fix

Escape backslashes in all string literals used in expressions.

affects: >=2.0.0

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

fix

Update links and references to point to new repo.

affects: >=3.1.0

Errors

Common errors & fixes

Error: Cannot access property 'xxx' of undefined

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.

TypeError: Expression returned ... instead of boolean

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.

SyntaxError: Unexpected token '}'

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: Unknown function 'foo'

Expression calls a function not defined in the customFunctions option.

fix

Register the function via the customFunctions option in compileExpression's second argument.

Upgrade

Version history

3.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/cshaa/filtrex ↗

packagehttps://www.npmjs.com/package/filtrex ↗

homepagehttps://sisyphus.tech/filtrex ↗