vega-expression
Advanced tools
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.
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); // 10Custom 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); // 15Math.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 (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 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.
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, but does not allow assignment operators, new expressions, or 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.
See the Vega expression language documentation for more details about supported JavaScript expressions, and see below for the constants and functions provided by this package. All other functions are provided by the vega-functions package.
Parse the JavaScript expression string and return the resulting abstract syntax tree in the ESTree format. The parser is a stripped-down version of the Esprima parser.
Create a new output code generator configured according to the provided options. The resulting 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 allowed).
The supported options include:
constants: A hash of allowed top-level constant values. This object maps from constant names to constant values. The constant values are strings that will be injected as-is into generated code. If this option is not specified, the constants object is used by default.
functions: A function that is given an AST visitor instance as input and returns an object of allowed functions. The resulting object 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). If this option is not specified, the functions method is used by default.
forbidden: An array of variable names that may not be referenced within the expression scope. These may correspond to disallowed global variables.
allowed: 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 global variables (see globalvar below).
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: (Required) 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. Alternatively, this property can be a function that maps from variable names in the source input to generated code to write to the output.
An object defining default constant values for the Vega expression language. The object maps from constant identifiers to JavaScript code to defining the constant value (for example, 'PI' maps to 'Math.PI').
Given a codegen instance (generated by the codegen method) as input, returns an object defining all valid function names for use within an expression. The resulting object 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).
Constructor for a node in an expression abstract syntax tree (AST). Accepts a type string as input, which then become the type property of the resulting node. AST nodes also support a visit method which takes a visitor function as input in order to traverse the AST for static analysis.
This package provides the following constants and functions:
Constants
Math Functions
Date/Time Functions
nowutcdatetimedatedayyearmonthhoursminutessecondsmillisecondstimetimezoneoffsetutcdateutcdayutcyearutcmonthutchoursutcminutesutcsecondsutcmillisecondsSequence (Array or String) Functions
String Functions
RegExp Functions
FAQs
Vega expression parser and code generator.
We found that vega-expression demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.