vega2ol

1.1.1 verified Fri May 01 auth: no javascript

A TypeScript library that transpiles Vega expressions to OpenLayers array-based expression format. v1.1.1 (latest), stable release. Key differentiator: bridges Vega-Lite/Vega visualization specs with OpenLayers map styling by converting conditional logic, math/string/array functions, and member access (e.g., datum.field) into OpenLayers expressions like ['case', ['>', ['get', 'value'], 100], 'red', 'blue']. Ideal for OpenLayers users who prefer Vega's concise JavaScript-like syntax.

Common errors

error TypeError: Cannot find module 'vega2ol' ↓

cause Missing installation or incorrect import in CommonJS environment.

fix

Ensure the package is installed: npm install vega2ol. Use ESM import syntax: import { vega2ol } from 'vega2ol'.

error Error: Unsupported expression type: CallExpression with function 'myFunc' ↓

cause The expression uses a function not supported by vega2ol.

fix

Use only supported functions: floor, ceil, round, abs, sqrt, pow, log, exp, sin, cos, tan, min, max, tostring, upper, lower, substring, length, indexof, slice, type, isvalid, isnumber, isstring, isboolean.

error SyntaxError: Expected ')' but got ';' ↓

cause Vega expression syntax error, often due to trailing semicolon or extra punctuation.

fix

Remove trailing semicolons and ensure valid Vega expression syntax. For example, use datum.x > 5 ? 'a' : 'b' without semicolons.

error TypeError: vega2ol is not a function ↓

cause Using default import instead of named import.

fix

Change import statement to import { vega2ol } from 'vega2ol'.

Warnings

gotcha vega2ol does not support all Vega functions (e.g., instanceof, regexp). Unsupported functions will cause a runtime error. ↓

fix Check the documentation for a list of supported functions. Use only supported functionality or manually translate complex expressions.

gotcha The library uses vega-expression to parse expressions, which may have its own quirks (e.g., strict syntax). Incorrect Vega syntax will throw parse errors. ↓

fix Ensure your Vega expression is valid per Vega specification; avoid trailing commas or invalid operators.

gotcha OpenLayers expression format is array-based, not an object or string. vega2ol returns arrays; do not stringify them prematurely. ↓

fix Use the returned array directly in OpenLayers style objects; do not call JSON.stringify() unless you intend to send it as data.

gotcha Member access like datum.x is always converted to ['get', 'x'], which reads from OpenLayers feature properties. If your data is stored differently (e.g., in a different property name), you need to adjust the expression. ↓

fix Use only datum.fieldName pattern; OpenLayers expressions use ['get', 'x'] to access feature attributes. Ensure your feature has the expected property keys.

Install

npm install vega2ol

yarn add vega2ol

pnpm add vega2ol

Imports

vega2ol
wrong
```
const vega2ol = require('vega2ol')
```
correct
```
import { vega2ol } from 'vega2ol'
```
ESM-only, shipped with TypeScript type definitions. Named export only; no default export.
vega2ol (default import)
wrong
```
import vega2ol from 'vega2ol'
```
correct
```
import { vega2ol } from 'vega2ol'
```
Only a named export exists. Default import is not valid and will throw at runtime.
VegaToOLVisitor
wrong
```
import { Visitor } from 'vega2ol'
```
correct
```
import { VegaToOLVisitor } from 'vega2ol'
```
Class for advanced usage if you need to extend or customize the transpiler. Exported but typically not imported directly; use vega2ol() function instead.

Quickstart

Transpile a Vega conditional expression to OpenLayers format and apply to a style object.

import { vega2ol } from 'vega2ol';

const vegaExpr = "datum.population > 1000000 ? '#FF0000' : '#0000FF'";
const olExpr = vega2ol(vegaExpr);
console.log(olExpr);
// ['case', ['>', ['get', 'population'], 1000000], '#FF0000', '#0000FF']

const style = {
  'fill-color': olExpr,
  'fill-opacity': vega2ol("datum.category == 'important' ? 1 : 0.5")
};
console.log(style);