Sval ·

A JavaScript interpreter written in JavaScript, based on the Acorn parser.

• Runs on ES5, supporting the latest ES features
• Both invasive and sandbox modes are available

It is useful for evaluating code targeting higher ECMAScript editions, or for environments where eval, setTimeout, and new Function are disabled.

Try Sval on the playground.

Installation

Node

Install Sval with npm.

npm install sval

Browser

Simply include it from unpkg. Alternatively, download from releases, get the minified file dist/min/sval.min.js, and include it in your HTML page. The global variable Sval will then be accessible directly.

<script type="text/javascript" src="https://unpkg.com/sval"></script>

Get Started

import Sval from 'sval'

// Create an interpreter
const interpreter = new Sval({
  // ECMA Version of the code
  // 3 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15
  // or 2015 | 2016 | 2017 | 2018 | 2019 | 2020 | 2021 | 2022 | 2023 | 2024
  // or "latest"
  ecmaVer: 'latest',
  // Code source type
  // "script" or "module"
  sourceType: 'script',
  // Whether the code runs in a sandbox
  sandBox: true,
})

// Parse and run the code
interpreter.run(`
  console.log('Hello World')
`)

Usage

The Sval constructor accepts three options: ecmaVer, sourceType, and sandBox.

• ecmaVer specifies the ECMAScript edition of the code. Currently, 3, 5, 6(2015), 7(2016), 8(2017), 9(2018), 10(2019), 11(2020), 12(2021), 13(2022), 14(2023), 15(2024), and "latest" are supported, and the default value is "latest".

• sourceType is either "script" or "module", which declares how Sval handles the code. A value of "script" means the code will be treated as a normal script, while "module" means the code will be treated as an ES module with global strict mode and support for import and export declarations. The default type is "script".

• sandBox is true for sandbox mode or false for invasive mode. Sandbox mode runs the code in an isolated environment and will not pollute your global scope. Invasive mode allows you to run code in the same global scope as your current environment. The default setting is true.

A Sval instance has two main methods: parse and run.

• parse parses the code with the internal Acorn or a custom parser to get the corresponding AST, as in parse(code: string) or parse(code: string, parser: (code: string, options: SvalOptions) => estree.Node).

• run evaluates the provided code, accepting either a string like run(code: string) or an AST conforming to the ESTree spec like run(ast: estree.Node).

In addition, a Sval instance has one method, import, and one object, exports, for modularization.

• import is used to import modules into the Sval instance scope. This method behaves differently depending on the sourceType.

  For "script", this method expects a name and a module as arguments like import(name: string, mod: any), or an object containing the modules like import({ [name: string]: any }). The modules will be automatically declared as global variables in the Sval instance scope. This method is most commonly used in sandbox mode.

  For "module", this method expects a path and a module declaration as arguments like import(path: string, mod: Module), or an object containing the module declarations like import({ [path: string]: Module }). The Module is either an ES module export object like { default?: any, [name: string]: any } or a function returning one like () => ({ default?: any, [name: string]: any }). The Module can also be a promise or a function returning a promise for use with dynamic imports. The modules will not be automatically declared as global variables in the Sval instance scope, and the code should use import declarations to import them.

• exports holds what was exported from runs, merged across multiple runs if applicable. This object also behaves differently depending on the sourceType.

  For "script", this object is automatically declared as a global variable in the Sval instance scope, and the code can simply mount properties on it to export values.

  For "module", this object is not automatically declared as a global variable in the Sval instance scope, and the code must use export declarations to export values.

Here are examples for import and exports:

Example for "script":

import Sval from 'sval'

// Create an interpreter for script
const scriptInterpreter = new Sval({ sourceType: 'script' })

// Add global modules in interpreter
scriptInterpreter.import('importWhatYouNeed', 'AllKindsOfStuffs')
// Or scriptInterpreter.import({ importWhatYouNeed: 'AllKindsOfStuffs' })

// Parse and run the code
scriptInterpreter.run(`
  exports.mod = importWhatYouNeed
`)

// Get exports from runs
console.log(scriptInterpreter.exports.mod) // Get 'AllKindsOfStuffs'

Example for "module":

import Sval from 'sval'

// Create an interpreter for module
const moduleInterpreter = new Sval({ sourceType: 'module' })

// Add ES modules in interpreter
moduleInterpreter.import('./import-what-you-need', { default: 'AllKindsOfStuffs' })
// Or moduleInterpreter.import('./import-what-you-need', () => ({ default: 'AllKindsOfStuffs' }))
// Or moduleInterpreter.import({ './import-what-you-need': { default: 'AllKindsOfStuffs' } })
// Or moduleInterpreter.import({ './import-what-you-need': () => ({ default: 'AllKindsOfStuffs' }) })

// Add ES modules in interpreter for dynamic import
moduleInterpreter.import('./dynamic-import-what-you-need', Promise.resolve({ default: 'AllKindsOfStuffs' }))

// Parse and run the code
moduleInterpreter.run(`
  import importWhatYouNeed from './import-what-you-need'
  import('./dynamic-import-what-you-need').then(m => console.log(m.default)) // Get 'AllKindsOfStuffs'
  export { importWhatYouNeed as mod }
`)

// Get exports from runs
console.log(moduleInterpreter.exports.mod) // Get 'AllKindsOfStuffs'

Reference

• estree
• acorn
• jsjs

Related

• sval-rhino-gs

License

Sval is licensed under the MIT.