Vega Utilities

Common errors

• ERR_REQUIRE_ESM

  cause Attempting to `require()` `vega-util` in a CommonJS context when the package is ESM-only since v6.0.0.
  fix Change `const { ... } = require('vega-util');` to `import { ... } from 'vega-util';` and ensure your project is configured for ES modules (e.g., `"type": "module"` in `package.json`).

• TypeError: (0 , vega_util__WEBPACK_IMPORTED_MODULE_0__.isObject) is not a function

  cause This Webpack/ESM bundling error typically occurs when attempting to import a default export that doesn't exist, or when a named export is incorrectly treated as a default.
  fix Ensure you are using named imports for `vega-util` functions: `import { isObject } from 'vega-util';`. Do not use `import isObject from 'vega-util';`.

• TS2305: Module '"vega-util"' has no exported member 'someFunction'.

  cause Attempting to import a function that is not exported by `vega-util` or has been renamed/removed in a new version.
  fix Verify the function name and its availability in the specific `vega-util` version you are using by checking the official API documentation or source code. Ensure your TypeScript configuration is correctly resolving module types.

Warnings

• breaking Vega, including `vega-util`, transitioned to ESM-only in v6.0.0. Projects must use ES module imports (`import ... from 'vega-util'`) and cannot use CommonJS `require()` syntax.
  Fix: Migrate your project to use ES modules. Ensure your `package.json` specifies `"type": "module"` or use `.mjs` file extensions. Update all `require()` statements to `import` statements.
• breaking A security advisory (GHSA-7f2v-3qq3-vvjf, CVE-2025-59840) addressed Cross-Site Scripting (XSS) vulnerabilities in Vega expressions abusing `toString` calls. This was fixed in `vega` v5.33.1 and implicitly affects packages consuming `vega-expression` or `vega-interpreter`.
  Fix: Upgrade to `vega` version 5.33.1 or higher for v5.x series, or any v6.x version. If directly using `vega-expression` or `vega-interpreter`, ensure those packages are updated to their latest compatible versions.
• breaking Another XSS vulnerability (GHSA-963h-3v39-3pqf, CVE-2025-27793) related to `RegExp.prototype[@@replace]` when running Vega/Vega-Lite JSON definitions was patched. Users running untrusted specifications could execute unexpected JavaScript.
  Fix: Update `vega` (and implicitly its sub-packages) to version 5.32.0 or higher. Always sanitize or validate untrusted Vega/Vega-Lite specifications, especially if not using `vega-interpreter`'s CSP mode.
• gotcha The `Object.prototype.hasOwnProperty` usage was replaced with `Object.hasOwn` in `vega-util` v5.31.0. While not directly breaking for most users, this change enhances security by guarding against overridden `Object.prototype` built-ins. Code relying on custom `hasOwnProperty` behavior on `Object.prototype` might see subtle differences, though this is an uncommon pattern.
  Fix: No direct fix is required for most applications, as `Object.hasOwn` is a safer and more robust alternative. If you have highly customized `Object.prototype` behavior, review its interaction with this change.

Install

• npm install vega-util npm
• yarn add vega-util yarn
• pnpm add vega-util pnpm

Imports

• isObject
  wrong:

  const isObject = require('vega-util').isObject;

  correct:

  import { isObject } from 'vega-util';

  Since v6.0.0, vega-util is ESM-only. CommonJS `require` is not supported.
• merge
  wrong:

  import merge from 'vega-util';

  correct:

  import { merge } from 'vega-util';

  All core utility functions are named exports, not default exports.
• error
  wrong:

  import { error as vegaError } from 'vega-util/src/error';

  correct:

  import { error } from 'vega-util';

  Import directly from the package root; avoid importing from internal paths like `src/` as they are not part of the public API and may change.

Quickstart

Demonstrates importing and using core utility functions like `isObject`, `merge`, `truthy`, and `pad`.

import { isObject, merge, truthy, pad } from 'vega-util';

console.log('Is { a: 1 } an object?', isObject({ a: 1 }));
console.log('Is "hello" an object?', isObject('hello'));

const obj1 = { a: 1, b: { c: 2 } };
const obj2 = { b: { d: 3 }, e: 4 };
const merged = merge(obj1, obj2);
console.log('Merged object:', merged); // Expected: { a: 1, b: { d: 3 }, e: 4 }

const value = 42;
console.log(`Is ${value} truthy?`, truthy(value));
console.log(`Is null truthy?`, truthy(null));

const str = 'Vega';
const paddedStr = pad(str, 10, ' ', 'left');
console.log(`Padded string: "${paddedStr}"`);

// Example demonstrating a common utility pattern with conditional logic
function processConfig(userConfig: object = {}) {
  const defaultConfig = { theme: 'light', animation: true, logLevel: 'info' };
  if (!isObject(userConfig)) {
    error('Invalid configuration: must be an object.');
    return defaultConfig; // Fallback to default
  }
  return merge(defaultConfig, userConfig);
}

const myConfig = processConfig({ animation: false, logLevel: 'debug' });
console.log('Processed configuration:', myConfig);

const invalidConfig = processConfig('not an object');
console.log('Invalid config handling resulted in:', invalidConfig);