js-exec 🧰

Execute sandboxed JavaScript strings.

---

The problem

Executing an inputted string, as JS code can be Extremely risky. These risks can be reduced, when using new Function syntax; however, this can also be limiting, as it would only give you access to the global scope.

This solution ✨

js-exec will sandbox the JavaScript code (passed as a string). It will only give it access to the objects that are given to the sandbox. This way, you will have full control of what the code can or cannot access.

• Features
• Executing TypeScript
• Installation
• Usage
  • Basic
  • Callbacks
  • Interceptors
  • Global Values
• Contributing
• Code of Conduct
• LICENSE

Features

• No Dependencies - no dependencies
• TypeScript - Everything is TypeScript based
• Lint - Preconfigured ESlint with Airbnb config
• Interceptors - pass in interceptors to the sandbox, to manipulate the source, before being executed

Execute TypeScript

We are adding a TypeScript interceptors, very soon. Please stay tuned for exciting news.

Installation

This module is distributed via npm which should be installed as one of your project's dependencies:

npm i --save js-exec

Usage

Basic

• Install js-exec
• Import exec from the package
• Pass the source to exec.
• Use the sandbox returned to pass dependencies to the code.

import { exec } from "js-exec";

const source = `console.log("Hello from js-exec 👋");`;

const sandbox = exec(source);

sandbox();
// Error: Cannot read property 'log' of undefined

sandbox({ console });
// Hello from js-exec 👋

Callbacks

The execfunction will accept a second parameter—i.e. options—for additional customizations.

You can pass in onSuccess and onError callbacks to the options object:

import { exec } from "js-exec";

const source = `console.log("Hello from js-exec 👋");`;

const sandbox = exec(source, {
  onSuccess: () => console.log("Taadaa 🎉🎉"),
  onError: (e: Error) => console.log("Something occurred 🥺\n", e),
});

sandbox({});
// Something occurred 🥺
// TypeError: Cannot read property 'log' of undefined

sandbox({ console });
// Hello from js-exec 👋
// Taadaa 🎉🎉

Interceptors

Interceptors will help you run functions on the code, before it gets executed.

Each Interceptor receives a source: string and returns a transformed source: string.

import { exec, Source } from "js-exec";

const source = `console.log("There are some f***s here!");`;

//Removes bad words inside the source
const removeBadWords = (source: Source): Source => {
  let cleanSource = source;
  const badWordsArray = ["f***"];
  const textToReplace = "🚫BAD WORD🚫";
  badWordsArray.forEach(
    (word) => (cleanSource = cleanSource.replace(word, textToReplace))
  );
  return cleanSource;
};

//Interceptors are run sequentially
const interceptors = [removeBadWords];

//interceptors are passed into the options object
const runCode = exec(source, { interceptors });
runCode({ console });
// There are some 🚫BAD WORD🚫s here!

Global Values

You can also make values available, on all executions of the sandbox; If, you wish to re-use them.

const pi = 3.141592;

const globalValues = { pi }

//pi will be available on every execution of runCode
const runCode = exec(source, { globalValues });

Contributing

This package is a beginner-friendly package. If you don't know where to start, visit Make a Pull Request to learn how to make pull requests.

Please visit Contributing for more info.

Code of Conduct

Please visit Code of Conduct.

---

License

MIT