Safely Evaluate ESTree Expressions

Common errors

• ReferenceError: 'myVariable' is not defined

  cause An expression attempts to access a variable or property ('myVariable') that is not present in the provided `context` object.
  fix Ensure all variables referenced in the expression are explicitly provided as properties in the `context` object passed to `evaluate` or `evaluate.sync`.

• SyntaxError: Assign expression is not supported

  cause The input AST (from the parsed expression) contains an assignment operation (e.g., `x = 10`) or a statement not supported by the evaluator.
  fix The library is designed for pure expressions. Do not attempt to evaluate JavaScript statements or expressions that modify state. Remove assignment operators or convert them to pure expressions where possible.

• TypeError: 'myFunction' is not a function

  cause An expression attempts to call a function (`myFunction`) when the `functions` option is not explicitly enabled, or a function expression/statement is present without the `generate` option.
  fix If you intend to allow function calls, enable the `functions: true` option in the `evaluate` options. If you need to evaluate full function expressions or statements, use `generate: true` (with extreme caution due to security implications).

Warnings

• breaking Version 3.x and later of `eval-estree-expression` requires Node.js version 14 or greater. This may break existing applications running on older Node.js runtimes.
  Fix: Upgrade your Node.js environment to version 14 or higher. If you must support older Node.js, consider using an earlier major version of the library (e.g., v2.x).
• gotcha Enabling the `functions: true` or `generate: true` options can introduce security vulnerabilities by allowing arbitrary function calls or function expressions/statements to be evaluated. This can lead to remote code execution if expressions or contexts originate from untrusted user input.
  Fix: Avoid enabling `functions: true` or `generate: true` when evaluating untrusted user-supplied expressions or when context objects can contain malicious functions. Carefully sanitize or whitelist any user input before parsing or evaluating.
• gotcha The library is designed for expressions and does not support JavaScript assignment operators (e.g., `=`, `+=`, `--`) or general statements by default. Attempting to evaluate code with these constructs will result in an error.
  Fix: Ensure that the input AST represents only pure expressions. If you need to allow specific assignments or statements, consider alternative, more powerful (and potentially less safe) evaluation mechanisms or pre-process the AST to remove/transform unsupported nodes.
• gotcha While `eval-estree-expression` avoids direct `eval()`, it does not inherently provide a secure sandbox against all forms of malicious code execution. If user-controlled data is passed in the `context` object, especially if it contains objects with malicious getters or methods, it could potentially be exploited.
  Fix: Always validate and sanitize the `context` object when it's populated by untrusted sources. Ensure that context values are primitive types or objects whose properties are strictly controlled and do not expose system-level APIs or sensitive operations.

Install

• npm install eval-estree-expression npm
• yarn add eval-estree-expression yarn
• pnpm add eval-estree-expression pnpm

Imports

• evaluate
  wrong:

  const { evaluate } = require('eval-estree-expression');

  correct:

  import { evaluate } from 'eval-estree-expression';

  While CommonJS `require` is still supported, ESM `import` is the preferred and more modern approach for Node.js 14+ environments. The `evaluate` function itself returns a Promise for asynchronous evaluation.
• evaluate.sync

  import { evaluate } from 'eval-estree-expression';
  const result = evaluate.sync(ast, context);

  The synchronous evaluation method is a property of the main `evaluate` export. No separate named export exists for `evaluate.sync`.
• parseExpression (from @babel/parser)
  wrong:

  import { parse } from '@babel/parser'; // parseExpression is typically more suitable for expressions than general `parse`

  correct:

  import { parseExpression } from '@babel/parser';

  `eval-estree-expression` consumes ASTs, it does not parse strings itself. You need an external parser like `@babel/parser` to convert expression strings into an AST first.

Quickstart

Demonstrates parsing a JavaScript expression string using `@babel/parser` and then evaluating it both synchronously and asynchronously with `eval-estree-expression`, providing a custom context object. It also highlights the flexibility of changing context for different evaluations.

import { evaluate } from 'eval-estree-expression';
import { parseExpression } from '@babel/parser';

async function runEvaluation() {
  const expressionString = 'user.age > 18 && user.status === "active" ? "Eligible" : "Not Eligible"';
  const context = {
    user: {
      name: 'Alice',
      age: 25,
      status: 'active'
    }
  };

  try {
    // Parse the expression string into an ESTree AST
    const ast = parseExpression(expressionString, {
      sourceType: 'script', // or 'module'
      plugins: ['estree'] // Ensure Babel outputs ESTree-compatible AST
    });

    // Synchronous evaluation
    const syncResult = evaluate.sync(ast, context);
    console.log('Synchronous result:', syncResult); // Expected: Eligible

    // Asynchronous evaluation (returns a Promise)
    const asyncResult = await evaluate(ast, { ...context, functions: true }); // functions option enabled for example
    console.log('Asynchronous result:', asyncResult); // Expected: Eligible

    // Example with a different context
    const anotherContext = {
      user: {
        name: 'Bob',
        age: 16,
        status: 'inactive'
      }
    };
    const syncResult2 = evaluate.sync(ast, anotherContext);
    console.log('Synchronous result (Bob):', syncResult2); // Expected: Not Eligible

  } catch (error) {
    console.error('Evaluation error:', error.message);
  }
}

runEvaluation();