Skip to content package
eval-estree-expression v3.0.1 Safely evaluate JavaScript (estree) expressions, sync and async.
node any 0 deps cjs open source
overview readme
license MIT
deps 0
unpacked 48.3 kB
files 11
node any $ npm install eval-estree-expression@3.0.1n npmREADME GitHub-flavored package documentation.
downloads Across all versions.
Download trend unavailable.
compatibility Runtime metadata.
keywords Tagged topics.
@babel @babel/parser 6to5 abstract analysis ast babel babel-cli compiler context ecma ecmascript
install size Estimated unpacked size across 1 packages.
48.3 kB
Includes dependencies.
versions Latest published Jun 10, 2026
maintainers Registry package owners.
contents eval-estree-expression
Safely evaluate JavaScript (estree) expressions, sync and async.
Please consider following this project's author, Jon Schlinkert , and consider starring the project to show your :heart: and support.
Apr 19, 2025
Install $ npm install --save eval-estree-expression copy
Usage Requires Node.js version 14 or greater.
Evaluates an estree expression from [@babel/parser][], esprima , acorn , or any other library that parses and returns a valid estree expression.
const { evaluate } = require ( 'eval-estree-expression' );
// or
import { evaluate } from 'eval-estree-expression' ;
evaluate. sync (expressionTree[, context]); // sync
evaluate (expressionTree[, context]). then (console.log); // async copy See the unit tests for hundreds of additional usage examples.
The evaluate function takes the following arguments:
expressionTree {object} - a valid estree expression AST.
context {object} - a data object with values to replace variables in expressions
Usage with Babel Most of the examples in this document assume the following setup code is used:
const { evaluate } = require ( 'eval-estree-expression' );
const { parseExpression } = require ( '@babel/parser' );
// parse your JavaScript expression
const ast = parseExpression ( '1 + 2' );
// evaluate synchronously
console. log (evaluate. sync (ast)); //=> 3
// or asynchronously
console. log ( await evaluate (ast)); //=> 3 copy
Usage with Esprima [Esprima][esprimar] doesn't have a "parseExpression" method like @babel/parser, so you'll need to return the expression from the AST, like so:
const { parse } = require ( 'esprima' );
const { evaluate } = require ( 'eval-estree-expression' );
const ast = parse ( '[1, 2, 3].map(n => n * x);' ).body[ 0 ].expression;
// evaluate synchronously
console. log (evaluate. sync (ast)); // => [2, 4, 6]
// or asynchronously
console. log ( await evaluate (ast)); // => [2, 4, 6] copy
API
.evaluate Evaluate expressions asynchronously.
console. log ( await evaluate ( parse ( '1 + 2' ))); //=> 3
console. log ( await evaluate ( parse ( '5 * 2' ))); //=> 10
console. log ( await evaluate ( parse ( '1 > 2' ))); //=> false
console. log ( await evaluate ( parse ( '1 < 2' ))); //=> true
// with context object
console. log ( await evaluate ( parse ( 'page.title === "home"' ), { page: { title: 'home' } })); //=> true copy
.evaluate.sync Evaluate expressions synchronously.
console. log (evaluate. sync ( parse ( '1 + 2' ))); //=> 3
console. log (evaluate. sync ( parse ( '5 * 2' ))); //=> 10
console. log (evaluate. sync ( parse ( '1 > 2' ))); //=> false
console. log (evaluate. sync ( parse ( '1 < 2' ))); //=> true
// with context object
console. log (evaluate. sync ( parse ( 'page.title === "home"' ), { page: { title: 'home' } })); //=> true copy
.variables Get an array of variables from an expression:
const { parseExpression } = require ( '@babel/parser' );
const { variables } = require ( 'eval-estree-expression' );
console. log ( variables ( parseExpression ( 'x * (y * 3) + z.y.x' ))); //=> ['x', 'y', 'z']
console. log ( variables ( parseExpression ( '(a || b) ? c + d : e * f' ))); //=> ['a', 'b', 'c', 'd', 'e', 'f']
copy
Options
booleanLogicalOperators Type: boolean
Default: undefined
Force logical operators to return a boolean result.
console. log ( await evaluate ( parse ( 'a && b' ), { a: undefined, b: true })); //=> undefined
console. log ( await evaluate ( parse ( 'a && b' ), { a: undefined, b: false })); //=> undefined
console. log ( await evaluate ( parse ( 'a || b' ), { a: false , b: null })); //=> null
console. log ( await evaluate ( parse ( 'a || b' ), { a: false , b: undefined })); //=> undefined
//
// With booleanLogicalOperators enabled
//
const options = {
booleanLogicalOperators: true
};
console. log ( await evaluate ( parse ( 'a || b' ), { a: false , b: null }, options)); //=> false
console. log ( await evaluate ( parse ( 'a && b' ), { a: undefined, b: true }, options)); //=> false
console. log ( await evaluate ( parse ( 'a && b' ), { a: undefined, b: false }, options)); //=> false
console. log ( await evaluate ( parse ( 'a || b' ), { a: false , b: undefined }, options)); //=> false copy
functions Type: boolean
Default: false
Allow function calls to be evaluated. This is unsafe, please enable this option at your own risk.
const { parse } = require ( 'esprima' );
const { generate } = require ( 'escodegen' );
const { evaluate } = require ( 'eval-estree-expression' );
const options = {
functions: true
};
// works with native methods
console. log (evaluate. sync ( parse ( '/([a-z]+)/.exec(" foo ")' ), { x: 2 }, options));
//=> [ 'foo', 'foo', index: 1, input: ' foo ', groups: undefined ]
// and functions defined on the context
console. log (evaluate. sync ( 'a.upper("b")' , { a: { upper : v => v. toUpperCase () } }, options));
//=> 'B' copy However, this does NOT support function expressions or function statements.
To enable function statements and expressions (not just function calls) to be evaluated, you must also use the generate option.
Top-Level await To use top-level await with, you need to:
Enable functions
Enable allowAwaitOutsideFunction. This option is passed directly to the babel parser.
const { evaluate } = require ( 'eval-estree-expression' );
const { parseExpression } = require ( '@babel/parser' );
const opts = { functions: true , allowAwaitOutsideFunction: true };
const e = (input, ctx, options) => {
return evaluate ( parseExpression (input, options), ctx, options);
};
const run = async () => {
console. log ( await e ( 'await 1' , {}, opts)); //=> 1
console. log ( await e ( 'Promise.resolve(1)' , { Promise }, opts)); //=> 1
console. log ( await e ( 'await Promise.resolve(1)' , { Promise }, opts)); //=> 1
};
run (); copy
generate Type: boolean
Default: undefined
Enable support for function statements and expressions by enabling the functions option AND by passing the .generate() function from the escodegen library.
const escodegen = require ( 'escodegen' );
const { parse } = require ( 'esprima' );
const { evaluate } = require ( 'eval-estree-expression' );
const options = {
functions: true ,
generate: escodegen.generate
};
console. log ( await evaluate ( parse ( '[1, 2, 3].map(n => n * x);' ), { x: 2 }, options)); // => [2, 4, 6] copy
regexOperator Type: boolean
Default: true
Enable the =~ regex operator to support testing values without using functions (example name =~ /^a.*c$/).
In expressions, if you wish to test a value using a regular expression, you have two options:
Enable function support so that you can use methods like .test() and .match(), or
Use this option, which uses a special syntax to match against regular expressions without evaluating any functions .
In other words, instead of having to do this:
console. log (evaluate. sync ( parse ( '/^ab+c$/ig.test("abbbbbc")' ), {}, { functions: true })); copy console. log (evaluate. sync ( parse ( 'name =~ /^a.*c$/' ), { name: 'abc' }));
console. log (evaluate. sync ( parse ( 'name =~ regex' ), { name: 'abc' , regex: /^a.*c$/ })); copy
strict Type: boolean
Default: false
Throw an error when variables are undefined.
withMembers Type: boolean
Default: undefined
Used with the variables method to return nested variables (e.g., variables with dot notation, like foo.bar.baz).
Examples
Operators Supports all JavaScript operators with the exception of assignment operators (=, +=, etc):
// Arithmetic operators
evaluate ( 'a + b' );
evaluate ( 'a - b' );
evaluate ( 'a / b' );
evaluate ( 'a * b' );
evaluate ( 'a % b' );
evaluate ( 'a ** b' );
// Relational operators
evaluate ( 'a instanceof b' );
evaluate ( 'a < b' );
evaluate ( 'a > b' );
evaluate ( 'a <= b' );
evaluate ( 'a >= b' );
// Equality operators
evaluate ( 'a !== b' );
evaluate ( 'a === b' );
evaluate ( 'a != b' );
evaluate ( 'a == b' );
// Bitwise shift operators
evaluate ( 'a << b' );
evaluate ( 'a >> b' );
evaluate ( 'a >>> b' );
// Binary bitwise operators
evaluate ( 'a & b' );
evaluate ( 'a | b' );
evaluate ( 'a ^ b' );
// Binary logical operators
evaluate ( 'a && b' ); // Logical AND.
evaluate ( 'a || b' ); // Logical OR.
evaluate ( 'a ?? b' ); // Nullish Coalescing Operator. copy
About
Contributing
Pull requests and stars are always welcome. For bugs and feature requests, please create an issue .
Running Tests
Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:
$ npm install && npm test copy
Building docs
(This project's readme.md is generated by verb , please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)
To generate the readme, run the following command:
$ npm install -g verbose/verb#dev verb-generate-readme && verb copy
You might also be interested in these projects:
whence : Add context awareness to your apps and frameworks by safely evaluating user-defined conditional expressions. Useful… more | homepage
Contributors
Author
License