jexl

library2.3.0jsnpmunverified

Jexl is a powerful context-based expression parser and evaluator for JavaScript, enabling safe evaluation of expressions against a context object. Version 2.3.0 is the latest stable release; the library is mature with infrequent updates. Unlike newer alternatives like jsonpath-plus or JMESPath, Jexl supports sync and async evaluation, custom transforms, functions, and binary operators, making it extensible for complex filtering, math, string concatenation, and conditional logic. It works in Node.js and browser (bundled), with no dependencies. The API uses both Promise-based eval and synchronous evalSync, plus a tagged template literal for compiling reusable expressions.

devops

npm install jexl

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · JEXL

jexl

devopsjavascriptv2.3.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.

default (Jexl instance)

✓ import jexl from 'jexl'

✗ const jexl = require('jexl')

Since v2.0, Jexl is ESM-first. The default export is a singleton instance with methods like eval, evalSync, addTransform, etc. CommonJS require still works in Node.

jexl (singleton)

✓ const jexl = require('jexl')

✗ const { jexl } = require('jexl')

CommonJS require returns the default export (the singleton instance). Named destructuring is incorrect.

Jexl (constructor)

✓ import { Jexl } from 'jexl'

✗ import Jexl from 'jexl'

Jexl constructor is a named export, not default. Use it to create independent instances: const jexl = new Jexl()

Demonstrates Jexl's core features: async eval, sync eval, custom transforms, and expression compilation.

import jexl from 'jexl'; const context = { name: { first: 'Sterling', last: 'Archer' }, assoc: [ { first: 'Lana', last: 'Kane' }, { first: 'Cyril', last: 'Figgis' }, { first: 'Pam', last: 'Poovey' } ], age: 36 }; // Async evaluation const result = await jexl.eval('assoc[.first == "Lana"].last', context); console.log(result); // "Kane" // Synchronous evaluation const syncResult = jexl.evalSync('age * (3 - 1)', context); console.log(syncResult); // 72 // Custom transform jexl.addTransform('upper', (val) => val.toUpperCase()); const transformed = await jexl.eval('"hello"|upper', context); console.log(transformed); // "HELLO" // Compiled expression const compiled = jexl.compile('name.first + " " + name.last'); const compiledResult = compiled.evalSync(context); console.log(compiledResult); // "Sterling Archer"

Debug

Known issues

breakingJexl v2 is ESM-only by default; the old require('jexl') no longer works without a bundler or Node --experimental-require-module.

fix

Use import statements or a bundler that handles ESM. For Node <12.17.0, stick with Jexl v1.x.

affects: >=2.0.0

deprecatedThe default export Jexl instance is a singleton; creating new instances via new Jexl() is deprecated in favor of the singleton pattern.

fix

Use the default import jexl instead of new Jexl(). If you need isolation, create a new instance with import { Jexl } from 'jexl'; const myJexl = new Jexl()

affects: >=2.0.0 <3.0.0

gotchaevalSync will throw if the expression contains async transforms or operators; it does not await Promises.

fix

Use eval for async expressions, or ensure all transforms/operators are synchronous when using evalSync.

affects: >=2.0.0

breakingJexl v2 no longer supports the deprecated 'transform' option from v1; use addTransform instead.

fix

Replace old transform configuration with jexl.addTransform(name, fn).

affects: >=2.0.0

gotchaIn v2, the default operator precedence has changed; the '^' operator now has higher precedence than '*' and '/', breaking expressions like '2^3*4' which now evaluate as (2^3)*4 instead of 2^(3*4).

fix

Add parentheses explicitly: '2^(3*4)' to get the v1 behavior.

affects: >=2.0.0

deprecatedThe 'reject' method from v1 is removed; use filtering with boolean negation instead.

fix

Replace jexl.eval('list[reject(.active)]') with jexl.eval('list[.!active]') or similar.

affects: >=2.0.0

Errors

Common errors & fixes

Cannot find module 'jexl'

Installed Jexl v2 via npm but used require('jexl') in a CommonJS environment without ESM support.

fix

Upgrade Node to >=12.22.0 or use import with a bundler. Alternatively, downgrade to jexl@1.

jexl.eval is not a function

Using the wrong import: import { jexl } from 'jexl' instead of import jexl from 'jexl' or require('jexl').

fix

Use default import: import jexl from 'jexl' or require('jexl').

TypeError: Cannot read properties of undefined (reading 'last')

Expression accesses a property that does not exist in the context object.

fix

Check that the context object includes the required nested structure. Use optional chaining in expressions if needed, but Jexl does not support ?. - add a custom binary operator instead.

Error: Expression '1/0' evaluated to Infinity

Division by zero returns Infinity, which may be unexpected.

fix

Wrap problematic expressions in try/catch or add a custom operator to handle division by zero.

Error: Maximum call stack size exceeded

Circular reference in context object causes infinite recursion during evaluation.

fix

Avoid circular structures in context, or limit expression depth. Use a deep-copy library to sanitize context.

Upgrade

Version history

2.3.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/TomFrost/jexl ↗

packagejexl ↗

homepagehttps://github.com/TomFrost/jexl ↗