UVM (Universal Virtual Machine)

Common errors

• TypeError: require is not a function

  cause 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.

  cause 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

  cause 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`.

Warnings

• breaking UVM `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.
• gotcha Data 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.
• gotcha The 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.
• gotcha While 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.

Install

• npm install uvm npm
• yarn add uvm yarn
• pnpm add uvm pnpm

Imports

• uvm
  wrong:

  const uvm = require('uvm');

  correct:

  import uvm from '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
  wrong:

  import uvm from 'uvm';

  correct:

  const uvm = require('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
  wrong:

  import { spawn } from 'uvm';

  correct:

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

  `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.

Quickstart

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);