vega-expression

What is vega-expression?

The vega-expression npm package is a library used for parsing and evaluating expressions in the Vega visualization grammar. It allows users to define dynamic expressions for data transformations, visual encodings, and other operations within Vega specifications.

What are vega-expression's main functionalities?

Expression Parsing

This feature allows you to parse a string expression into an abstract syntax tree (AST). The parsed AST can then be used for further analysis or transformation.

const vegaExpression = require('vega-expression');
const code = 'datum.value * 2';
const ast = vegaExpression.parse(code);
console.log(ast);

Expression Evaluation

This feature allows you to evaluate a parsed expression within a given context. In this example, the expression 'datum.value * 2' is evaluated with datum.value set to 5, resulting in 10.

const vegaExpression = require('vega-expression');
const code = 'datum.value * 2';
const context = { datum: { value: 5 } };
const fn = vegaExpression.codegen({ code }).code;
const result = fn(context);
console.log(result); // 10

Custom Functions

This feature allows you to define and use custom functions within your expressions. In this example, a custom function 'customFunc' is defined to multiply the input by 3, and it is used within the expression.

const vegaExpression = require('vega-expression');
const code = 'customFunc(datum.value)';
const context = { datum: { value: 5 }, customFunc: (x) => x * 3 };
const fn = vegaExpression.codegen({ code }).code;
const result = fn(context);
console.log(result); // 15

Other packages similar to vega-expression

mathjs

Math.js is an extensive math library for JavaScript and Node.js. It features a flexible expression parser and supports a wide range of mathematical functions and operations. Compared to vega-expression, math.js is more focused on mathematical computations and less on data visualization contexts.

jsep

JSEP (JavaScript Expression Parser) is a library for parsing JavaScript expressions into an AST. It is lightweight and can be used for various purposes, including custom expression evaluation. While it provides similar parsing capabilities as vega-expression, it does not include built-in support for data visualization-specific contexts.

expr-eval

Expr-eval is a small, fast JavaScript expression parser and evaluator. It supports basic arithmetic, logical operations, and custom functions. Compared to vega-expression, expr-eval is more general-purpose and not specifically tailored for data visualization tasks.

README

vega-expression

Vega expression parser and code generator.

Parses a limited subset of JavaScript expressions into an abstract syntax tree, and provides code generation utilities for generating eval'able output code. The parser recognizes basic JavaScript expressions, excluding assignment operators, new expressions, and control flow statements (for, while, switch, etc). The configurable code generator further limits the set of allowable function invocations and variable names. The goal is to provide simple, expressive and security-conscious expression evaluation.

API Usage

The top-level export includes three methods:

parse(input)

Parse the input JavaScript expression string and return the resulting abstract syntax tree in the ESTree (formerly Mozilla AST) format. The parser is based on a stripped-down version of the Esprima parser.

codegen(options)

Creates a new code generator instance configured according to the provided options. The resulting code generator function accepts a parsed AST as input and returns eval'able JavaScript code as output. The output is an object hash with the properties code (the generated code as a string), fields (a hash of all properties referenced within the fieldVar scope), and globals (a hash of all properties referenced outside a provided white list).

The supported options are:

• constants: A hash of allowed top-level constant values. The hash maps from constant names to constant values. The constant values are strings that will be injected as-is into generated code.

• functions: A function that is given a code generator instance as input and returns a hash of allowed top-level functions. The resulting hash maps from function names to function values. The values may either be strings (which will be injected as-is into generated code and subsequently appended with arguments) or functions (which take an array of argument AST nodes as input and return generated code to inject).

• idWhiteList: An array of variable names that may be referenced within the expression scope. These typically correspond to function parameter names for the expression. Variable names not included in the white list will be collected as assumed global variables (see globalVar below). If idWhiteList is specified, idBlackList will be ignored.

• idBlackList: An array of variable names that may not be referenced within the expression scope. These may correspond to disallowed global variables. If idWhiteList is specified, idBlackList will be ignored.

• fieldVar: The name of the primary data input argument within the generated expression function. For example, in the function function(d) { return d.x * d.y; }, the variable d serves as the field variable, and x and y are it's accessed properties. All properties accessed under the scope of fieldVar will be tracked by the code generator and returned as part of the output. This is necessary to perform dependency tracking of referenced data fields.

• globalVar: The name of the variable upon which to lookup global variables. This variable name will be included in the generated code as the scope for any global variable references. This option is only used when idWhiteList is provided: any identifier that is not included in the white list is assumed to be within the scope of the global variable.

compiler(args, options)

A convenience method that performs parsing, code generation and compilation of an invocable function (using the JavaScript Function constructor). The output is identical to the codegen method, except that an additional fn property is added to the output object, referencing the generated Function instance. The args parameter is an array of variable names that serves as the argument signature for the generated function. The options parameter is the options hash for the codegen method.