Sval JavaScript Interpreter

Common errors

• ReferenceError: [variable_name] is not defined

  cause The interpreted code is attempting to access a variable or function that exists in the host environment but has not been explicitly imported into the `sval` interpreter's scope.
  fix Use `interpreter.import('variable_name', hostVariable)` or `interpreter.import({ variable_name: hostVariable })` to make the host variable accessible within the interpreter's context.

• SyntaxError: 'import' and 'export' may only appear with 'sourceType: "module"'

  cause The interpreted JavaScript code contains ES module syntax (e.g., `import` statements, `export` statements) but the `Sval` instance was initialized with the default `sourceType: 'script'`.
  fix Initialize the `Sval` interpreter with `new Sval({ sourceType: 'module', ... })` to enable ES module parsing and execution.

• TypeError: Cannot read properties of undefined (reading 'log')

  cause This often occurs when trying to access `console.log` (or other host globals) within a module-type script (`sourceType: 'module'`) or when `this` is `undefined` at the top level, and `console` was not explicitly imported.
  fix When using `sourceType: 'module'`, top-level `this` is `undefined`. Explicitly import global objects like `console` or `Math` into the interpreter's scope: `interpreter.import('console', console);`.

• Error: [Parser Error] (e.g., 'Unexpected token', 'Unexpected keyword')

  cause The `ecmaVer` option is set to an older ECMAScript version that does not support the syntax used in the interpreted code, or there's a general syntax error.
  fix Ensure `ecmaVer` is set to `'latest'` or a specific year that supports the syntax in your code (e.g., `ecmaVer: '2024'`). Double-check the interpreted code for any actual syntax errors.

Warnings

• breaking In `sval` versions 0.6.10 and later, the behavior of `sourceType: 'module'` was updated to strictly align with ECMAScript module semantics. This includes treating the top-level `this` as `undefined` and enforcing strict mode by default for module contexts.
  Fix: If your code relies on `this` referring to the global object at the top level of a module, it will break. Refactor your module code to avoid top-level `this` or explicitly import global objects (e.g., `interpreter.import('globalThis', globalThis)`). For scripts requiring classic global `this` behavior, ensure `sourceType` is set to `'script'`.
• gotcha The `sandBox` option, which defaults to `true`, is crucial for security. When `sandBox: false` (invasive mode), the interpreted code can directly interact with and mutate the host environment's global scope, posing a significant security risk if executing untrusted code.
  Fix: Always explicitly set `sandBox: true` unless you have absolute trust in the executed code and specifically require direct global scope interaction. When `sandBox: true`, explicitly import any host objects (like `console` or `window`) that the interpreted code needs to access via `interpreter.import()`.
• gotcha The `import` method's behavior is context-dependent based on the `sourceType`. When `sourceType: 'script'`, `import` makes provided values available as global variables within the script's scope. However, for `sourceType: 'module'`, `import` is intended to pre-populate the module's internal import map, behaving closer to how ES modules resolve dependencies.
  Fix: Be mindful of your `sourceType`. For simple variable injection into a script, `sourceType: 'script'` with `interpreter.import({ varName: value })` is appropriate. For true ES module behavior with `import`/`export` statements inside the interpreted code, use `sourceType: 'module'`.
• gotcha While `sval` is often used as a safer alternative to `eval` for executing dynamic code, it still executes arbitrary JavaScript. Without proper sandboxing (`sandBox: true`) and input validation, it can still be exploited if fed malicious code.
  Fix: Never execute untrusted, unsanitized user-generated code with `sval` in invasive mode (`sandBox: false`). Even in sandboxed mode, be cautious about the host objects you expose via `interpreter.import()`, as access to powerful APIs can still compromise security. Always validate and sanitize inputs thoroughly.

Install

• npm install sval npm
• yarn add sval yarn
• pnpm add sval pnpm

Imports

• Sval
  wrong:

  import { Sval } from 'sval'

  correct:

  import Sval from 'sval'

  Sval is a default export for ES Modules. Attempting to use a named import will result in a runtime error.
• Sval (CommonJS)
  wrong:

  const { Sval } = require('sval')

  correct:

  const Sval = require('sval')

  For CommonJS environments, the module's default export is directly assigned when requiring the package.
• SvalOptions (Type)

  import type { SvalOptions } from 'sval'

  TypeScript users can import the `SvalOptions` interface for type-safe configuration of the interpreter.

Quickstart

Demonstrates how to create a `Sval` interpreter instance, configure it with options, import host functions and variables, and execute a JavaScript string in a sandboxed environment.

import Sval from 'sval';

const interpreter = new Sval({
  ecmaVer: 'latest', // Support latest ECMAScript features
  sourceType: 'script', // Treat code as a standard script
  sandBox: true, // Run code in an isolated environment (recommended)
});

// Import host-environment variables or modules into the interpreter's scope
interpreter.import({
  log: console.log,
  greet: (name: string) => `Hello, ${name} from interpreter!`,
});

try {
  // Execute JavaScript code as a string
  interpreter.run(`
    const message = greet('Sval User');
    log(message);
    
    const sum = (a, b) => a + b;
    log('2 + 3 =', sum(2, 3));

    // Accessing built-in globals like Math
    log('Math.PI =', Math.PI);
  `);
} catch (error) {
  console.error('Interpreter Error:', error);
}