sval

library0.1.2jsnpmunverified

Sval is a JavaScript interpreter written entirely in JavaScript, leveraging the Acorn parser to support modern ECMAScript features while maintaining compatibility with ES5 environments. As of version 0.6.12, it provides robust capabilities for executing JavaScript code in either an isolated sandbox or an invasive mode, depending on user requirements. This flexibility makes it particularly useful for environments where native `eval`, `setTimeout`, or `new Function` might be disabled or restricted due to security policies. The package is actively maintained, with frequent updates addressing bug fixes and dependency bumps, ensuring ongoing support for new JavaScript syntax and improved stability. Key differentiators include its ability to run cutting-edge ES features on older runtimes and its explicit support for both script and module source types, alongside TypeScript type definitions for enhanced developer experience.

web-framework http-networking

npm install sval

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SVAL

sval

web-frameworkjavascriptv0.1.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.

Sval

✓ import Sval from 'sval'

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

✓ const Sval = require('sval')

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

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

Debug

Known issues

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

affects: >=0.6.10

gotchaThe `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()`.

affects: >=0.6.0

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

affects: >=0.6.0

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

affects: >=0.6.0

Errors

Common errors & fixes

ReferenceError: [variable_name] is not defined

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"'

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

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

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.

Upgrade

Version history

0.1.2latest on npm

Audit

Dependencies

acornrequiredSval internally uses Acorn for JavaScript parsing. While not a peer dependency, understanding its role is crucial for advanced use cases like custom parsers.

Agent activity

14 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Siubaak/sval ↗

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

homepagehttps://sval.dev ↗