Topscript

Topscript allows to safely eval a subset of javascript. It is written using the acorn javascript parser.

Installation

npm install topscript

Usage

To execute a script, simply do:

import { topscript } from 'topscript';

topscript('1 + 2') // => 3;
topscript('log("hello, world!")', { log: console.log }) // => undefined

topscript(`
  function add(a, b) {
    return a + b;
  }

  add(1, 2)
`) // => 3

topscript('[1, 2, 3].slice(1)') // => [2, 3]

Topscript also allows to validate a supplied script for parsing errors:

import { validate } from 'topscript';

validate('1 + 2')
validate('1 +') // throws an error
validate('return 42', { allowReturnOutsideFunction: true })
validate('await Promise.resolve(42)', { allowAwaitOutsideFunction: true })

Supported Features

Topscript supports a wide range of JavaScript features:

• Variables (const, let)
• Literals (strings, numbers, booleans, objects, arrays)
• Functions (declarations, expressions, arrow functions)
• Control flow (if, else, while)
• Template literals and string interpolation
• Closures and nested scopes
• Compound assignment operators (+=, -=, etc)
• Basic array and object operations
• Rest parameters

Execution Safety Features

Topscript includes several safety mechanisms:

• Timeout: You can specify a execution timeout (ms)

  topscript('while(true) {}', {}, { timeout: 1_000 });

• Disable while loops: You can also disable while statements alltogether

  topscript('while(true) {}', {}, { disableWhileStatements: true }) // throws

• Max stack size: You can specify a max stack size

  topscript('const fn = () => fn(); fn();', {}, { maxStackSize: 10 }) // throws
  topscript('const fn1 = () => fn2(); const fn2 = () => 0; fn1()', {}, { maxStackSize: 1 }); // throws

• Property access: You can specify a validatePropertyAccess function

  topscript('Date.prototype.getFullYear = () => 1990', { Date }, {
    validatePropertyAccess: (obj: object, key: PropertyKey) => {
      if (obj === Date && key === 'prototype') throw new Error('Accessing Date.prototype is not allowed');
    },
  }) // throws

Other options

You can pass allowReturnOutsideFunction to enable:

topscript('if (true) return 42', {}, { allowReturnOutsideFunction: true }) // => 42

Unsupported Features

Some JavaScript features are not supported:

• Async/await functions
• Optional chaining
• Destructuring assignments
• Classes
• Try/catch blocks

Semantic Versioning

Topscript is using Semantic Versioning: SemVer

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/mrkamel/topscript

License

The library is available as open source under the terms of the MIT License.