Registry / serialization / vega-expression

vega-expression

JSON →
library6.1.0jsnpmunverified

vega-expression is a JavaScript/TypeScript library that provides a secure and configurable expression parser and code generator, forming a core component of the broader Vega visualization toolkit. It processes a limited subset of JavaScript expressions into an Abstract Syntax Tree (AST) and then generates `eval`'able JavaScript code. The library intentionally restricts language features like assignment operators, `new` expressions, and control flow to prioritize security and prevent unwanted side effects, making it suitable for user-provided expressions in visualization contexts. It is currently in active development, with version 6.2.0 as the latest stable release at the time of this entry, following a fairly active release cadence that often aligns with the larger Vega monorepo. Its key differentiators include its security-first approach, a stripped-down Esprima-based parser, and highly configurable code generation options for managing constants, functions, and variable scopes, including tracking data field dependencies.

npm install vega-expression
INSTALL
IMPORT
SIG · VEGA-EXPRESSION
V
vega-expression
serializationjavascriptv6.1.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

parse
import { parse } from 'vega-expression';
const parse = require('vega-expression').parse;
Vega v6.0.0 and above are ESM-only. Use `import` statements. For older v5.x versions, CommonJS `require` was standard.
codegen
import { codegen } from 'vega-expression';
const codegen = require('vega-expression').codegen;
Vega v6.0.0 and above are ESM-only. Use `import` statements. `codegen` is a function that returns a generator function.
CodegenOptions
import type { CodegenOptions } from 'vega-expression';
Explicit type import for TypeScript users to define options passed to `codegen`.

This quickstart demonstrates parsing a basic mathematical expression, generating executable JavaScript code, and evaluating it within a defined data context. It highlights the use of `parse` and `codegen` with `fieldvar` and `allowed` options.

import { parse, codegen } from 'vega-expression'; interface DataItem { value: number; category: string; } // 1. Define the expression string const expressionString = "datum.value * 2 + 5"; // 2. Parse the expression into an AST const ast = parse(expressionString); console.log('Parsed AST:', JSON.stringify(ast, null, 2)); // 3. Create a code generator, specifying the field variable ('datum' in this case) // and any allowed globals/functions if needed. const generator = codegen({ fieldvar: 'datum', allowed: ['datum'], // 'datum' is an allowed variable in the expression scope // You can also provide custom functions or constants functions: () => ({ pow: (args: any[]) => `Math.pow(${args[0]}, ${args[1]})` }) }); // 4. Generate the executable code from the AST const { code, fields, globals } = generator(ast); console.log('\nGenerated Code:', code); console.log('Referenced Fields:', fields); console.log('Referenced Globals:', globals); // 5. Evaluate and use the generated function // NOTE: Using `Function` constructor is generally discouraged due to CSP issues. // For Vega runtime, `vega-interpreter` offers CSP-compliant evaluation. const evaluateExpression = new Function('datum', `return ${code};`); const sampleData: DataItem = { value: 10, category: 'A' }; const result = evaluateExpression(sampleData); console.log(`\nResult for { value: 10 } (10 * 2 + 5):`, result); // Expected: 25 const anotherData: DataItem = { value: 7, category: 'B' }; const anotherResult = evaluateExpression(anotherData); console.log(`Result for { value: 7 } (7 * 2 + 5):`, anotherResult); // Expected: 19
Debug
Known issues
breakingVega v6.0.0, including `vega-expression`, transitioned to ESM-only. CommonJS `require()` statements will no longer work, leading to import errors.
fix
Migrate all `require()` calls to `import` statements. Ensure your project is configured for ESM, typically by setting `"type": "module"` in `package.json` or using `.mjs` file extensions.
affects: >=6.0.0
breakingA prototype pollution vulnerability (GHSA-7f2v-3qq3-vvjf, CVE-2025-59840) was identified in `vega-expression` versions prior to `5.33.1`. This could allow cross-site scripting (XSS) via expressions abusing `toString` calls in specific environments. While fixed in newer versions, users on older `v5.x` releases should upgrade immediately.
fix
Upgrade to `vega-expression@5.33.1` or higher (including all `v6.x` versions) to mitigate the prototype pollution vulnerability. Always validate user-provided expressions carefully.
affects: <5.33.1
gotchaThe `vega-expression` language is a restricted subset of JavaScript. It does not allow assignment operators (`=`, `+=`, etc.), pre/postfix updates (`++`), `new` expressions, or most control flow statements (`for`, `while`, `switch`). Function calls involving nested properties (e.g., `foo.bar()`) are also forbidden.
fix
Ensure expressions adhere to the allowed syntax. Refer to the Vega expression language documentation for a full list of supported features, constants, and functions. Use the `codegen` options (`forbidden`, `allowed`, `functions`) to explicitly control what can be referenced.
affects: >=1.0.0
gotchaWhen using `codegen`, the `Function` constructor is used to evaluate the generated code. This can violate Content Security Policies (CSPs) that prohibit `unsafe-eval`. For CSP-compliant evaluation, consider using the `vega-interpreter` package, which evaluates expressions by traversing the AST directly.
fix
If CSP is a concern, integrate `vega-interpreter` into your runtime. Invoke the Vega parser with the `{ast: true}` option and pass the interpreter as an option to the Vega View constructor to enable AST-based evaluation.
affects: >=1.0.0
Errors
Common errors & fixes
ReferenceError: require is not defined
Attempting to use CommonJS `require()` syntax in a project after upgrading to `vega-expression` v6.0.0 or later, which is ESM-only.
fix
Replace `const { parse } = require('vega-expression');` with `import { parse } from 'vega-expression';`. Ensure your `package.json` has `"type": "module"` or use `.mjs` file extensions for ESM files.
Error: Invalid AST Node Type: AssignmentExpression
The parsed expression contains forbidden JavaScript syntax, such as an assignment operator (`=`).
fix
Rewrite the expression to use only the allowed subset of JavaScript. Avoid assignment operators, `new` expressions, `for`/`while` loops, and direct method calls on nested properties.
ReferenceError: myGlobalVar is not defined
The generated code attempts to access a global variable (`myGlobalVar`) that was not explicitly allowed or provided in the `codegen` options.
fix
When creating the code generator, use the `allowed` array for variables within the expression scope, or the `globalvar` option to specify the object through which global variables should be looked up.
Upgrade
Version history
6.1.0latest on npm
Audit
Dependencies
vega-functionsrequiredProvides additional custom functions beyond the basic utilities, many specific to Vega dataflows.
Agent activity
17 hits · last 30 days
node
14
OpenAI (training)
1
Resources