uvm

library1.0.2jsnpmunverified

UVM (Universal Virtual Machine) is a JavaScript library designed to provide a consistent API for executing code in isolated contexts, leveraging Node.js Worker Threads and Web Workers in browser environments. This abstraction simplifies cross-context communication via an event emitter-based bridge, enabling developers to run potentially untrusted or computationally intensive code without blocking the main thread. Currently at version 4.0.1 (last published 10 months ago, as of current date), the library appears to be actively maintained. Its key differentiator lies in offering a 'universal' approach to sandboxed code execution, providing a unified development experience across different JavaScript runtimes, making it suitable for applications requiring secure and efficient off-main-thread processing. The project originates from Postman Labs.

http-networking devops

npm install uvm

github ↗package ↗

INSTALL

IMPORT

SIG · UVM

uvm

http-networkingjavascriptv1.0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

uvm

✓ import uvm from 'uvm';

✗ const uvm = require('uvm');

For modern Node.js environments (>=18) and browser bundlers, ESM import is the preferred method for the main UVM object. The library is dual-published or transpiled to support both, but ESM is recommended for new projects.

uvm

✓ const uvm = require('uvm');

✗ import uvm from 'uvm';

CommonJS `require` is supported, as shown in the README, for compatibility with older Node.js projects or specific build setups. Use this if your project does not support ESM.

spawn

✓ import uvm from 'uvm'; const context = uvm.spawn({ /* options */ });

✗ import { spawn } from 'uvm';

`spawn` is a static method of the default `uvm` export, not a named export itself. It's the primary function for creating new isolated virtual machine contexts.

This quickstart demonstrates how to create an isolated UVM context, send data to it, receive data back using an event emitter bridge, and handle basic lifecycle events including disconnection for resource management. It showcases cross-context communication between the main process/thread and the UVM sandbox.

import uvm from 'uvm'; const context = uvm.spawn({ bootCode: ` // Code running inside the isolated VM/Worker context bridge.on('loopback', function (data) { console.log(`VM received: ${data}`); bridge.dispatch('loopback', data + ' World!'); }); // Example of handling potential errors inside the VM try { // Some potentially error-prone code // throw new Error('Simulated VM error'); } catch (e) { bridge.dispatch('error', e.message); } ` }); context.on('loopback', function (data) { console.log(`Main context received: ${data}`); // Expected: Hello World! }); context.on('error', function (errorMessage) { console.error(`VM Error: ${errorMessage}`); }); context.dispatch('loopback', 'Hello'); // To demonstrate cleanup (important for resource management) setTimeout(() => { console.log('Disconnecting UVM context...'); context.disconnect(); }, 1000);

Debug

Known issues

breakingUVM `v3.x` and `v4.x` likely introduced breaking changes related to ESM support and Node.js Worker Threads APIs. Projects upgrading from older `v2.x` versions, especially those relying solely on CommonJS or targeting older Node.js versions, may require code adjustments. Always consult the GitHub releases for specific upgrade guides.

fix

Review the official GitHub release notes for your target version. Update import statements (`require` to `import`) and ensure your Node.js environment meets the `engines.node` requirement (>=18 for v4.x). Verify data serialization for cross-context communication.

affects: >=3.0

gotchaData passed between the main context and the spawned UVM context (Node.js Worker Thread or Web Worker) must be serializable. Complex objects, functions, or non-primitive data types might not transfer correctly or may throw serialization errors.

fix

Ensure all data passed via `bridge.dispatch` or in `bootCode` options consists of primitive values, plain objects, arrays, or other structured clone algorithm compatible types. Avoid passing functions, DOM elements, or class instances directly.

affects: >=1.0

gotchaThe code executed within the UVM `bootCode` runs in an isolated scope. It does not have direct access to variables or globals from the main application context unless explicitly passed during `spawn` or through the `bridge` mechanism. This isolation is by design for security and stability but can be a source of confusion.

fix

Explicitly pass any necessary configuration, initial data, or environment variables to the UVM context via the `spawn` options or by dispatching events after the context has booted. Understand that functions and objects cannot be directly shared, only their serializable data representations.

affects: >=1.0

gotchaWhile UVM provides an isolated environment, it's not a complete security sandbox for running arbitrary, malicious untrusted code, especially in Node.js. Node.js's native `vm` module and `worker_threads` have known limitations regarding true sandboxing against sophisticated attacks.

fix

For highly critical security requirements, consider additional layers of security like running worker processes with restrictive permissions, using containerization, or specialized sandboxing solutions (e.g., `vm2`, though it has also faced vulnerabilities). Do not solely rely on UVM for absolute security against untrusted code.

affects: >=1.0

Errors

Common errors & fixes

TypeError: require is not a function

Attempting to use CommonJS `require` syntax in an ESM module context when `uvm` is imported as an ESM module, or when the project is configured for ESM-only.

fix

If your project is ESM, change `const uvm = require('uvm');` to `import uvm from 'uvm';`. Ensure your `package.json` has `"type": "module"` or use `.mjs` file extensions for ESM.

Uncaught DOMException: Failed to execute 'postMessage' on 'Worker': An object could not be cloned.

Attempting to pass a non-serializable object (e.g., a DOM element, a function, or a complex class instance) across the UVM bridge to or from a Web Worker.

fix

Before dispatching data across the `bridge`, ensure that the data is structured clone algorithm compatible. Convert complex objects into plain JavaScript objects (POJOs), serialize functions to strings, or extract only necessary primitive values.

ReferenceError: bridge is not defined

This error typically occurs if `bridge.on` or `bridge.dispatch` is called outside the `bootCode` context or before the UVM context has fully initialized and established its `bridge` object.

fix

Ensure that `bridge.on` and `bridge.dispatch` calls are exclusively within the `bootCode` string provided to `uvm.spawn`, which defines the code to run inside the isolated VM/Worker. The main context interacts via `context.on` and `context.dispatch`.

Upgrade

Version history

1.0.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

14 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/postmanlabs/uvm ↗

packagehttps://www.npmjs.com/package/uvm ↗