eval-estree-expression
![Tests](https://github.com/jonschlinkert/eval-estree-expression/actions/workflows/main.yml/badge.svg)
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.
(TOC generated by verb using markdown-toc)
Install
Install with npm :
$ npm install --save eval-estree-expression
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');
evaluate(expressionTree[, context]);
evaluate.sync(expressionTree[, context]);
See the unit tests for hundreds of additional usage examples.
Params
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');
const ast = parseExpression('1 + 2);
// evaluate synchronously
console.log(evaluate.sync(ast)); //=> 3
// or asynchronously
console.log(await evaluate(ast)); //=> 3
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;
console.log(evaluate.sync(ast));
console.log(await evaluate(ast));
API
.evaluate
Evaluate expresssions asynchronously.
console.log(await evaluate(parse('1 + 2')));
console.log(await evaluate(parse('5 * 2')));
console.log(await evaluate(parse('1 > 2')));
console.log(await evaluate(parse('1 < 2')));
console.log(await evaluate(parse('page.title === "home"'), { page: { title: 'home' } }));
.evaluate.sync
Evaluate expresssions synchronously.
console.log(evaluate.sync(parse('1 + 2')));
console.log(evaluate.sync(parse('5 * 2')));
console.log(evaluate.sync(parse('1 > 2')));
console.log(evaluate.sync(parse('1 < 2')));
console.log(evaluate.sync(parse('page.title === "home"'), { page: { title: 'home' } }));
.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')));
console.log(variables(parseExpression('(a || b) ? c + d : e * f')));
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 }));
console.log(await evaluate(parse('a && b'), { a: undefined, b: false }));
console.log(await evaluate(parse('a || b'), { a: false, b: null }));
console.log(await evaluate(parse('a || b'), { a: false, b: undefined }));
const options = {
booleanLogicalOperators: true
};
console.log(await evaluate(parse('a || b'), { a: false, b: null }, options));
console.log(await evaluate(parse('a && b'), { a: undefined, b: true }, options));
console.log(await evaluate(parse('a && b'), { a: undefined, b: false }, options));
console.log(await evaluate(parse('a || b'), { a: false, b: undefined }, options));
functions
Type: boolean
Default: false
Allow function calls to be evaluated. This is unsafe, please enable this option at your own risk.
Example
const { parse } = require('esprima');
const { generate } = require('escodegen');
const { evaluate } = require('eval-estree-expression');
const options = {
functions: true
};
console.log(evaluate.sync(parse('/([a-z]+)/.exec(" foo ")'), { x: 2 }, options));
console.log(evaluate.sync('a.upper("b")', { a: { upper: v => v.toUpperCase() } }, options);
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.
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.
Example
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)));
regexOperator
Type: boolean
Default: true
Enable the =~
regex operator to support testing values without using functions (example name =~ /^a.*c$/
).
Why is this needed?
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 an functions.
In other words, instead of having to do this:
console.log(evaluate.sync(parse('/^ab+c$/ig.test("abbbbbc")'), {}, { functions: true }));
You can do this:
console.log(evaluate.sync(parse('name =~ /^a.*c$/'), { name: 'abc' }));
console.log(evaluate.sync(parse('name =~ regex'), { name: 'abc', regex: /^a.*c$/ }));
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):
evaluate('a + b');
evaluate('a - b');
evaluate('a / b');
evaluate('a * b');
evaluate('a % b');
evaluate('a ** b');
evaluate('a instanceof b');
evaluate('a < b');
evaluate('a > b');
evaluate('a <= b');
evaluate('a >= b');
evaluate('a !== b');
evaluate('a === b');
evaluate('a != b');
evaluate('a == b');
evaluate('a << b');
evaluate('a >> b');
evaluate('a >>> b');
evaluate('a & b');
evaluate('a | b');
evaluate('a ^ b');
evaluate('a && b');
evaluate('a || b');
evaluate('a ?? b');
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
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
Related projects
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
Jon Schlinkert
License
Copyright © 2021, Jon Schlinkert.
Released under the MIT License.
This file was generated by verb-generate-readme, v0.8.0, on September 25, 2021.